docstr: Computes a square root of the square matrix `A`, i.e. returns
  a matrix `B = A^{1/2}` such that `B^2 = A`. The square root
  of a matrix, if it exists, is not unique.
  
  **Examples**
  
  Square roots of some simple matrices::
  
      >>> from mpmath import *
      >>> mp.dps = 15; mp.pretty = True
      >>> sqrtm([[1,0], [0,1]])
      [1.0  0.0]
      [0.0  1.0]
      >>> sqrtm([[0,0], [0,0]])
      [0.0  0.0]
      [0.0  0.0]
      >>> sqrtm([[2,0],[0,1]])
      [1.4142135623731  0.0]
      [            0.0  1.0]
      >>> sqrtm([[1,1],[1,0]])
      [ (0.920442065259926 - 0.21728689675164j)  (0.568864481005783 + 0.351577584254143j)]
      [(0.568864481005783 + 0.351577584254143j)  (0.351577584254143 - 0.568864481005783j)]
      >>> sqrtm([[1,0],[0,1]])
      [1.0  0.0]
      [0.0  1.0]
      >>> sqrtm([[-1,0],[0,1]])
      [(0.0 - 1.0j)           0.0]
      [         0.0  (1.0 + 0.0j)]
      >>> sqrtm([[j,0],[0,j]])
      [(0.707106781186547 + 0.707106781186547j)                                       0.0]
      [                                     0.0  (0.707106781186547 + 0.707106781186547j)]
  
  A square root of a rotation matrix, giving the corresponding
  half-angle rotation matrix::
  
      >>> t1 = 0.75
      >>> t2 = t1 * 0.5
      >>> A1 = matrix([[cos(t1), -sin(t1)], [sin(t1), cos(t1)]])
      >>> A2 = matrix([[cos(t2), -sin(t2)], [sin(t2), cos(t2)]])
      >>> sqrtm(A1)
      [0.930507621912314  -0.366272529086048]
      [0.366272529086048   0.930507621912314]
      >>> A2
      [0.930507621912314  -0.366272529086048]
      [0.366272529086048   0.930507621912314]
  
  The identity `(A^2)^{1/2} = A` does not necessarily hold::
  
      >>> A = matrix([[4,1,4],[7,8,9],[10,2,11]])
      >>> sqrtm(A**2)
      [ 4.0  1.0   4.0]
      [ 7.0  8.0   9.0]
      [10.0  2.0  11.0]
      >>> sqrtm(A)**2
      [ 4.0  1.0   4.0]
      [ 7.0  8.0   9.0]
      [10.0  2.0  11.0]
      >>> A = matrix([[-4,1,4],[7,-8,9],[10,2,11]])
      >>> sqrtm(A**2)
      [  7.43715112194995  -0.324127569985474   1.8481718827526]
      [-0.251549715716942    9.32699765900402  2.48221180985147]
      [  4.11609388833616   0.775751877098258   13.017955697342]
      >>> chop(sqrtm(A)**2)
      [-4.0   1.0   4.0]
      [ 7.0  -8.0   9.0]
      [10.0   2.0  11.0]
  
  For some matrices, a square root does not exist::
  
      >>> sqrtm([[0,1], [0,0]])
      Traceback (most recent call last):
        ...
      ZeroDivisionError: matrix is numerically singular
  
  Two examples from the documentation for Matlab's ``sqrtm``::
  
      >>> mp.dps = 15; mp.pretty = True
      >>> sqrtm([[7,10],[15,22]])
      [1.56669890360128  1.74077655955698]
      [2.61116483933547  4.17786374293675]
      >>>
      >>> X = matrix(\
      ...   [[5,-4,1,0,0],
      ...   [-4,6,-4,1,0],
      ...   [1,-4,6,-4,1],
      ...   [0,1,-4,6,-4],
      ...   [0,0,1,-4,5]])
      >>> Y = matrix(\
      ...   [[2,-1,-0,-0,-0],
      ...   [-1,2,-1,0,-0],
      ...   [0,-1,2,-1,0],
      ...   [-0,0,-1,2,-1],
      ...   [-0,-0,-0,-1,2]])
      >>> mnorm(sqrtm(X) - Y)
      4.53155328326114e-19
docstr_tok: ["Computes","a","square","root","of","the","square","matrix","`","A","`",",","i.e",".","returns","a","matrix","`","B","=","A^","{","1\/2","}","`","such","that","`","B^2","=","A","`",".","The","square","root","of","a","matrix",",","if","it","exists",",","is","not","unique",".","*","*","Examples","*","*","Square","roots","of","some","simple","matrices",":",":",">",">",">","from","mpmath","import","*",">",">",">","mp.dps","=","15",";","mp.pretty","=","True",">",">",">","sqrtm","(","[","[","1,0","]",",","[","0,1","]","]",")","[","1.0","0.0","]","[","0.0","1.0","]",">",">",">","sqrtm","(","[","[","0,0","]",",","[","0,0","]","]",")","[","0.0","0.0","]","[","0.0","0.0","]",">",">",">","sqrtm","(","[","[","2,0","]",",","[","0,1","]","]",")","[","1.4142135623731","0.0","]","[","0.0","1.0","]",">",">",">","sqrtm","(","[","[","1,1","]",",","[","1,0","]","]",")","[","(","0.920442065259926","-","0.21728689675164j",")","(","0.568864481005783","+","0.351577584254143j",")","]","[","(","0.568864481005783","+","0.351577584254143j",")","(","0.351577584254143","-","0.568864481005783j",")","]",">",">",">","sqrtm","(","[","[","1,0","]",",","[","0,1","]","]",")","[","1.0","0.0","]","[","0.0","1.0","]",">",">",">","sqrtm","(","[","[","-1,0","]",",","[","0,1","]","]",")","[","(","0.0","-","1.0j",")","0.0","]","[","0.0","(","1.0","+","0.0j",")","]",">",">",">","sqrtm","(","[","[","j,0","]",",","[","0",",","j","]","]",")","[","(","0.707106781186547","+","0.707106781186547j",")","0.0","]","[","0.0","(","0.707106781186547","+","0.707106781186547j",")","]","A","square","root","of","a","rotation","matrix",",","giving","the","corresponding","half-angle","rotation","matrix",":",":",">",">",">","t1","=","0.75",">",">",">","t2","=","t1","*","0.5",">",">",">","A1","=","matrix","(","[","[","cos","(","t1",")",",","-sin","(","t1",")","]",",","[","sin","(","t1",")",",","cos","(","t1",")","]","]",")",">",">",">","A2","=","matrix","(","[","[","cos","(","t2",")",",","-sin","(","t2",")","]",",","[","sin","(","t2",")",",","cos","(","t2",")","]","]",")",">",">",">","sqrtm","(","A1",")","[","0.930507621912314","-0.366272529086048","]","[","0.366272529086048","0.930507621912314","]",">",">",">","A2","[","0.930507621912314","-0.366272529086048","]","[","0.366272529086048","0.930507621912314","]","The","identity","`","(","A^2",")","^","{","1\/2","}","=","A","`","does","not","necessarily","hold",":",":",">",">",">","A","=","matrix","(","[","[","4,1,4","]",",","[","7,8,9","]",",","[","10,2,11","]","]",")",">",">",">","sqrtm","(","A","*","*","2",")","[","4.0","1.0","4.0","]","[","7.0","8.0","9.0","]","[","10.0","2.0","11.0","]",">",">",">","sqrtm","(","A",")","*","*","2","[","4.0","1.0","4.0","]","[","7.0","8.0","9.0","]","[","10.0","2.0","11.0","]",">",">",">","A","=","matrix","(","[","[","-4,1,4","]",",","[","7",",","-8,9","]",",","[","10,2,11","]","]",")",">",">",">","sqrtm","(","A","*","*","2",")","[","7.43715112194995","-0.324127569985474","1.8481718827526","]","[","-0.251549715716942","9.32699765900402","2.48221180985147","]","[","4.11609388833616","0.775751877098258","13.017955697342","]",">",">",">","chop","(","sqrtm","(","A",")","*","*","2",")","[","-4.0","1.0","4.0","]","[","7.0","-8.0","9.0","]","[","10.0","2.0","11.0","]","For","some","matrices",",","a","square","root","does","not","exist",":",":",">",">",">","sqrtm","(","[","[","0,1","]",",","[","0,0","]","]",")","Traceback","(","most","recent","call","last",")",":","...","ZeroDivisionError",":","matrix","is","numerically","singular","Two","examples","from","the","documentation","for","Matlab","'s","``","sqrtm","``",":",":",">",">",">","mp.dps","=","15",";","mp.pretty","=","True",">",">",">","sqrtm","(","[","[","7,10","]",",","[","15,22","]","]",")","[","1.56669890360128","1.74077655955698","]","[","2.61116483933547","4.17786374293675","]",">",">",">",">",">",">","X","=","matrix","(","\\","...","[","[","5",",","-4,1,0,0","]",",","...","[","-4,6",",","-4,1,0","]",",","...","[","1",",","-4,6",",","-4,1","]",",","...","[","0,1",",","-4,6",",","-4","]",",","...","[","0,0,1",",","-4,5","]","]",")",">",">",">","Y","=","matrix","(","\\","...","[","[","2",",","-1",",","-0",",","-0",",","-0","]",",","...","[","-1,2",",","-1,0",",","-0","]",",","...","[","0",",","-1,2",",","-1,0","]",",","...","[","-0,0",",","-1,2",",","-1","]",",","...","[","-0",",","-0",",","-0",",","-1,2","]","]",")",">",">",">","mnorm","(","sqrtm","(","X",")","-","Y",")","4.53155328326114e-19"]
code: def sqrtm(ctx, A, _may_rotate=2):
      r"""
          Computes a square root of the square matrix `A`, i.e. returns
          a matrix `B = A^{1/2}` such that `B^2 = A`. The square root
          of a matrix, if it exists, is not unique.
  
          **Examples**
  
          Square roots of some simple matrices::
  
              >>> from mpmath import *
              >>> mp.dps = 15; mp.pretty = True
              >>> sqrtm([[1,0], [0,1]])
              [1.0  0.0]
              [0.0  1.0]
              >>> sqrtm([[0,0], [0,0]])
              [0.0  0.0]
              [0.0  0.0]
              >>> sqrtm([[2,0],[0,1]])
              [1.4142135623731  0.0]
              [            0.0  1.0]
              >>> sqrtm([[1,1],[1,0]])
              [ (0.920442065259926 - 0.21728689675164j)  (0.568864481005783 + 0.351577584254143j)]
              [(0.568864481005783 + 0.351577584254143j)  (0.351577584254143 - 0.568864481005783j)]
              >>> sqrtm([[1,0],[0,1]])
              [1.0  0.0]
              [0.0  1.0]
              >>> sqrtm([[-1,0],[0,1]])
              [(0.0 - 1.0j)           0.0]
              [         0.0  (1.0 + 0.0j)]
              >>> sqrtm([[j,0],[0,j]])
              [(0.707106781186547 + 0.707106781186547j)                                       0.0]
              [                                     0.0  (0.707106781186547 + 0.707106781186547j)]
  
          A square root of a rotation matrix, giving the corresponding
          half-angle rotation matrix::
  
              >>> t1 = 0.75
              >>> t2 = t1 * 0.5
              >>> A1 = matrix([[cos(t1), -sin(t1)], [sin(t1), cos(t1)]])
              >>> A2 = matrix([[cos(t2), -sin(t2)], [sin(t2), cos(t2)]])
              >>> sqrtm(A1)
              [0.930507621912314  -0.366272529086048]
              [0.366272529086048   0.930507621912314]
              >>> A2
              [0.930507621912314  -0.366272529086048]
              [0.366272529086048   0.930507621912314]
  
          The identity `(A^2)^{1/2} = A` does not necessarily hold::
  
              >>> A = matrix([[4,1,4],[7,8,9],[10,2,11]])
              >>> sqrtm(A**2)
              [ 4.0  1.0   4.0]
              [ 7.0  8.0   9.0]
              [10.0  2.0  11.0]
              >>> sqrtm(A)**2
              [ 4.0  1.0   4.0]
              [ 7.0  8.0   9.0]
              [10.0  2.0  11.0]
              >>> A = matrix([[-4,1,4],[7,-8,9],[10,2,11]])
              >>> sqrtm(A**2)
              [  7.43715112194995  -0.324127569985474   1.8481718827526]
              [-0.251549715716942    9.32699765900402  2.48221180985147]
              [  4.11609388833616   0.775751877098258   13.017955697342]
              >>> chop(sqrtm(A)**2)
              [-4.0   1.0   4.0]
              [ 7.0  -8.0   9.0]
              [10.0   2.0  11.0]
  
          For some matrices, a square root does not exist::
  
              >>> sqrtm([[0,1], [0,0]])
              Traceback (most recent call last):
                ...
              ZeroDivisionError: matrix is numerically singular
  
          Two examples from the documentation for Matlab's ``sqrtm``::
  
              >>> mp.dps = 15; mp.pretty = True
              >>> sqrtm([[7,10],[15,22]])
              [1.56669890360128  1.74077655955698]
              [2.61116483933547  4.17786374293675]
              >>>
              >>> X = matrix(\
              ...   [[5,-4,1,0,0],
              ...   [-4,6,-4,1,0],
              ...   [1,-4,6,-4,1],
              ...   [0,1,-4,6,-4],
              ...   [0,0,1,-4,5]])
              >>> Y = matrix(\
              ...   [[2,-1,-0,-0,-0],
              ...   [-1,2,-1,0,-0],
              ...   [0,-1,2,-1,0],
              ...   [-0,0,-1,2,-1],
              ...   [-0,-0,-0,-1,2]])
              >>> mnorm(sqrtm(X) - Y)
              4.53155328326114e-19
  
          """
      A = ctx.matrix(A)
      # Trivial
      if A * 0 == A:
          return A
      prec = ctx.prec
      if _may_rotate:
          d = ctx.det(A)
          if abs(ctx.im(d)) < 16 * ctx.eps and ctx.re(d) < 0:
              return ctx._sqrtm_rot(A, _may_rotate - 1)
      try:
          ctx.prec += 10
          tol = ctx.eps * 128
          Y = A
          Z = I = A**0
          k = 0
          # Denman-Beavers iteration
          while 1:
              Yprev = Y
              try:
                  Y, Z = 0.5 * (Y + ctx.inverse(Z)), 0.5 * (
                      Z + ctx.inverse(Y)
                  )
              except ZeroDivisionError:
                  if _may_rotate:
                      Y = ctx._sqrtm_rot(A, _may_rotate - 1)
                      break
                  else:
                      raise
              mag1 = ctx.mnorm(Y - Yprev, "inf")
              mag2 = ctx.mnorm(Y, "inf")
              if mag1 <= mag2 * tol:
                  break
              if _may_rotate and k > 6 and not mag1 < mag2 * 0.001:
                  return ctx._sqrtm_rot(A, _may_rotate - 1)
              k += 1
              if k > ctx.prec:
                  raise ctx.NoConvergence
      finally:
          ctx.prec = prec
      Y *= 1
      return Y
  
file_path: catboost/contrib/python/mpmath/py3/mpmath/matrices/calculus.py
imports: from ..libmp.backend import xrange
label_desc: Use image node_id 6 for calling the MatrixCalculusMethods obj's underlying member method code with example usage: obj.sqrtm(ctx, A, _may_rotate) and returns: Y, A, ctx, ctx