docstr: Computes a logarithm of the square matrix `A`, i.e. returns
  a matrix `B = \log(A)` such that `\exp(B) = A`. The logarithm
  of a matrix, if it exists, is not unique.
  
  **Examples**
  
  Logarithms of some simple matrices::
  
      >>> from mpmath import *
      >>> mp.dps = 15; mp.pretty = True
      >>> X = eye(3)
      >>> logm(X)
      [0.0  0.0  0.0]
      [0.0  0.0  0.0]
      [0.0  0.0  0.0]
      >>> logm(2*X)
      [0.693147180559945                0.0                0.0]
      [              0.0  0.693147180559945                0.0]
      [              0.0                0.0  0.693147180559945]
      >>> logm(expm(X))
      [1.0  0.0  0.0]
      [0.0  1.0  0.0]
      [0.0  0.0  1.0]
  
  A logarithm of a complex matrix::
  
      >>> X = matrix([[2+j, 1, 3], [1-j, 1-2*j, 1], [-4, -5, j]])
      >>> B = logm(X)
      >>> nprint(B)
      [ (0.808757 + 0.107759j)    (2.20752 + 0.202762j)   (1.07376 - 0.773874j)]
      [ (0.905709 - 0.107795j)  (0.0287395 - 0.824993j)  (0.111619 + 0.514272j)]
      [(-0.930151 + 0.399512j)   (-2.06266 - 0.674397j)  (0.791552 + 0.519839j)]
      >>> chop(expm(B))
      [(2.0 + 1.0j)           1.0           3.0]
      [(1.0 - 1.0j)  (1.0 - 2.0j)           1.0]
      [        -4.0          -5.0  (0.0 + 1.0j)]
  
  A matrix `X` close to the identity matrix, for which
  `\log(\exp(X)) = \exp(\log(X)) = X` holds::
  
      >>> X = eye(3) + hilbert(3)/4
      >>> X
      [              1.25             0.125  0.0833333333333333]
      [             0.125  1.08333333333333              0.0625]
      [0.0833333333333333            0.0625                1.05]
      >>> logm(expm(X))
      [              1.25             0.125  0.0833333333333333]
      [             0.125  1.08333333333333              0.0625]
      [0.0833333333333333            0.0625                1.05]
      >>> expm(logm(X))
      [              1.25             0.125  0.0833333333333333]
      [             0.125  1.08333333333333              0.0625]
      [0.0833333333333333            0.0625                1.05]
  
  A logarithm of a rotation matrix, giving back the angle of
  the rotation::
  
      >>> t = 3.7
      >>> A = matrix([[cos(t),sin(t)],[-sin(t),cos(t)]])
      >>> chop(logm(A))
      [             0.0  -2.58318530717959]
      [2.58318530717959                0.0]
      >>> (2*pi-t)
      2.58318530717959
  
  For some matrices, a logarithm does not exist::
  
      >>> logm([[1,0], [0,0]])
      Traceback (most recent call last):
        ...
      ZeroDivisionError: matrix is numerically singular
  
  Logarithm of a matrix with large entries::
  
      >>> logm(hilbert(3) * 10**20).apply(re)
      [ 45.5597513593433  1.27721006042799  0.317662687717978]
      [ 1.27721006042799  42.5222778973542   2.24003708791604]
      [0.317662687717978  2.24003708791604    42.395212822267]
docstr_tok: ["Computes","a","logarithm","of","the","square","matrix","`","A","`",",","i.e",".","returns","a","matrix","`","B","=","\\log","(","A",")","`","such","that","`","\\exp","(","B",")","=","A","`",".","The","logarithm","of","a","matrix",",","if","it","exists",",","is","not","unique",".","*","*","Examples","*","*","Logarithms","of","some","simple","matrices",":",":",">",">",">","from","mpmath","import","*",">",">",">","mp.dps","=","15",";","mp.pretty","=","True",">",">",">","X","=","eye","(","3",")",">",">",">","logm","(","X",")","[","0.0","0.0","0.0","]","[","0.0","0.0","0.0","]","[","0.0","0.0","0.0","]",">",">",">","logm","(","2","*","X",")","[","0.693147180559945","0.0","0.0","]","[","0.0","0.693147180559945","0.0","]","[","0.0","0.0","0.693147180559945","]",">",">",">","logm","(","expm","(","X",")",")","[","1.0","0.0","0.0","]","[","0.0","1.0","0.0","]","[","0.0","0.0","1.0","]","A","logarithm","of","a","complex","matrix",":",":",">",">",">","X","=","matrix","(","[","[","2+j",",","1",",","3","]",",","[","1-j",",","1-2","*","j",",","1","]",",","[","-4",",","-5",",","j","]","]",")",">",">",">","B","=","logm","(","X",")",">",">",">","nprint","(","B",")","[","(","0.808757","+","0.107759j",")","(","2.20752","+","0.202762j",")","(","1.07376","-","0.773874j",")","]","[","(","0.905709","-","0.107795j",")","(","0.0287395","-","0.824993j",")","(","0.111619","+","0.514272j",")","]","[","(","-0.930151","+","0.399512j",")","(","-2.06266","-","0.674397j",")","(","0.791552","+","0.519839j",")","]",">",">",">","chop","(","expm","(","B",")",")","[","(","2.0","+","1.0j",")","1.0","3.0","]","[","(","1.0","-","1.0j",")","(","1.0","-","2.0j",")","1.0","]","[","-4.0","-5.0","(","0.0","+","1.0j",")","]","A","matrix","`","X","`","close","to","the","identity","matrix",",","for","which","`","\\log","(","\\exp","(","X",")",")","=","\\exp","(","\\log","(","X",")",")","=","X","`","holds",":",":",">",">",">","X","=","eye","(","3",")","+","hilbert","(","3",")","\/4",">",">",">","X","[","1.25","0.125","0.0833333333333333","]","[","0.125","1.08333333333333","0.0625","]","[","0.0833333333333333","0.0625","1.05","]",">",">",">","logm","(","expm","(","X",")",")","[","1.25","0.125","0.0833333333333333","]","[","0.125","1.08333333333333","0.0625","]","[","0.0833333333333333","0.0625","1.05","]",">",">",">","expm","(","logm","(","X",")",")","[","1.25","0.125","0.0833333333333333","]","[","0.125","1.08333333333333","0.0625","]","[","0.0833333333333333","0.0625","1.05","]","A","logarithm","of","a","rotation","matrix",",","giving","back","the","angle","of","the","rotation",":",":",">",">",">","t","=","3.7",">",">",">","A","=","matrix","(","[","[","cos","(","t",")",",","sin","(","t",")","]",",","[","-sin","(","t",")",",","cos","(","t",")","]","]",")",">",">",">","chop","(","logm","(","A",")",")","[","0.0","-2.58318530717959","]","[","2.58318530717959","0.0","]",">",">",">","(","2","*","pi-t",")","2.58318530717959","For","some","matrices",",","a","logarithm","does","not","exist",":",":",">",">",">","logm","(","[","[","1,0","]",",","[","0,0","]","]",")","Traceback","(","most","recent","call","last",")",":","...","ZeroDivisionError",":","matrix","is","numerically","singular","Logarithm","of","a","matrix","with","large","entries",":",":",">",">",">","logm","(","hilbert","(","3",")","*","10","*","*","20",")",".apply","(","re",")","[","45.5597513593433","1.27721006042799","0.317662687717978","]","[","1.27721006042799","42.5222778973542","2.24003708791604","]","[","0.317662687717978","2.24003708791604","42.395212822267","]"]
code: def logm(ctx, A):
      r"""
      Computes a logarithm of the square matrix `A`, i.e. returns
      a matrix `B = \log(A)` such that `\exp(B) = A`. The logarithm
      of a matrix, if it exists, is not unique.
  
      **Examples**
  
      Logarithms of some simple matrices::
  
          >>> from mpmath import *
          >>> mp.dps = 15; mp.pretty = True
          >>> X = eye(3)
          >>> logm(X)
          [0.0  0.0  0.0]
          [0.0  0.0  0.0]
          [0.0  0.0  0.0]
          >>> logm(2*X)
          [0.693147180559945                0.0                0.0]
          [              0.0  0.693147180559945                0.0]
          [              0.0                0.0  0.693147180559945]
          >>> logm(expm(X))
          [1.0  0.0  0.0]
          [0.0  1.0  0.0]
          [0.0  0.0  1.0]
  
      A logarithm of a complex matrix::
  
          >>> X = matrix([[2+j, 1, 3], [1-j, 1-2*j, 1], [-4, -5, j]])
          >>> B = logm(X)
          >>> nprint(B)
          [ (0.808757 + 0.107759j)    (2.20752 + 0.202762j)   (1.07376 - 0.773874j)]
          [ (0.905709 - 0.107795j)  (0.0287395 - 0.824993j)  (0.111619 + 0.514272j)]
          [(-0.930151 + 0.399512j)   (-2.06266 - 0.674397j)  (0.791552 + 0.519839j)]
          >>> chop(expm(B))
          [(2.0 + 1.0j)           1.0           3.0]
          [(1.0 - 1.0j)  (1.0 - 2.0j)           1.0]
          [        -4.0          -5.0  (0.0 + 1.0j)]
  
      A matrix `X` close to the identity matrix, for which
      `\log(\exp(X)) = \exp(\log(X)) = X` holds::
  
          >>> X = eye(3) + hilbert(3)/4
          >>> X
          [              1.25             0.125  0.0833333333333333]
          [             0.125  1.08333333333333              0.0625]
          [0.0833333333333333            0.0625                1.05]
          >>> logm(expm(X))
          [              1.25             0.125  0.0833333333333333]
          [             0.125  1.08333333333333              0.0625]
          [0.0833333333333333            0.0625                1.05]
          >>> expm(logm(X))
          [              1.25             0.125  0.0833333333333333]
          [             0.125  1.08333333333333              0.0625]
          [0.0833333333333333            0.0625                1.05]
  
      A logarithm of a rotation matrix, giving back the angle of
      the rotation::
  
          >>> t = 3.7
          >>> A = matrix([[cos(t),sin(t)],[-sin(t),cos(t)]])
          >>> chop(logm(A))
          [             0.0  -2.58318530717959]
          [2.58318530717959                0.0]
          >>> (2*pi-t)
          2.58318530717959
  
      For some matrices, a logarithm does not exist::
  
          >>> logm([[1,0], [0,0]])
          Traceback (most recent call last):
            ...
          ZeroDivisionError: matrix is numerically singular
  
      Logarithm of a matrix with large entries::
  
          >>> logm(hilbert(3) * 10**20).apply(re)
          [ 45.5597513593433  1.27721006042799  0.317662687717978]
          [ 1.27721006042799  42.5222778973542   2.24003708791604]
          [0.317662687717978  2.24003708791604    42.395212822267]
  
      """
      A = ctx.matrix(A)
      prec = ctx.prec
      try:
          ctx.prec += 10
          tol = ctx.eps * 128
          I = A**0
          B = A
          n = 0
          while 1:
              B = ctx.sqrtm(B)
              n += 1
              if ctx.mnorm(B - I, "inf") < 0.125:
                  break
          T = X = B - I
          L = X * 0
          k = 1
          while 1:
              if k & 1:
                  L += T / k
              else:
                  L -= T / k
              T *= X
              if ctx.mnorm(T, "inf") < tol:
                  break
              k += 1
              if k > ctx.prec:
                  raise ctx.NoConvergence
      finally:
          ctx.prec = prec
      L *= 2**n
      return L
  
file_path: catboost/contrib/python/mpmath/py3/mpmath/matrices/calculus.py
imports: from ..libmp.backend import xrange
label_desc: Use image node_id 7 for calling the MatrixCalculusMethods obj's underlying member method code with example usage: obj.logm(ctx, A) and returns: L