naginterfaces.library.matop.real_​gen_​matrix_​log

naginterfaces.library.matop.real_gen_matrix_log(a)

real_gen_matrix_log computes the principal matrix logarithm, $\log \left(A\right)$, of a real $n\times n$ matrix $A$, with no eigenvalues on the closed negative real line.

For full information please refer to the NAG Library document for f01ej

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f01/f01ejf.html

Parameters

afloat, array-like, shape $(n,n)$

The $n\times n$ matrix $A$.

Returns

afloat, ndarray, shape $(n,n)$

The $n\times n$ principal matrix logarithm, $\log \left(A\right)$.

imnormfloat

If the function has given a reliable answer then $imnorm=0.0$. If $imnorm$ differs from $0.0$ by more than unit roundoff (as returned by machine.precision) then the computed matrix logarithm is unreliable.

Raises

NagValueError

(errno $-1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 0$.

(errno $1$)

$A$ is singular so the logarithm cannot be computed.

(errno $2$)

$A$ was found to have eigenvalues on the negative real line. The principal logarithm is not defined in this case. complex_gen_matrix_log() can be used to find a complex non-principal logarithm.

(errno $4$)

An unexpected internal error occurred. Please contact NAG.

Warns

NagAlgorithmicWarning

(errno $3$)

The arithmetic precision is higher than that used for the Padé approximant computed matrix logarithm.

Notes

Any nonsingular matrix $A$ has infinitely many logarithms. For a matrix with no eigenvalues on the closed negative real line, the principal logarithm is the unique logarithm whose spectrum lies in the strip $\left\{z:-\pi <Im\left(\left(z\right)<\pi \right)\right\}$.

$\log \left(A\right)$ is computed using the inverse scaling and squaring algorithm for the matrix logarithm described in Al–Mohy and Higham (2011), adapted to real matrices by Al–Mohy et al. (2012).

References

Al–Mohy, A H and Higham, N J, 2011, Improved inverse scaling and squaring algorithms for the matrix logarithm, SIAM J. Sci. Comput. (34(4)), C152–C169

Al–Mohy, A H, Higham, N J and Relton, S D, 2012, Computing the Fréchet derivative of the matrix logarithm and estimating the condition number, SIAM J. Sci. Comput. (35(4)), C394–C410

Higham, N J, 2008, Functions of Matrices: Theory and Computation, SIAM, Philadelphia, PA, USA