f01 Chapter Contents
f01 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_matop_real_gen_matrix_log (f01ejc)

## 1  Purpose

nag_matop_real_gen_matrix_log (f01ejc) computes the principal matrix logarithm, $\mathrm{log}\left(A\right)$, of a real $n$ by $n$ matrix $A$, with no eigenvalues on the closed negative real line.

## 2  Specification

 #include #include
 void nag_matop_real_gen_matrix_log (Nag_OrderType order, Integer n, double a[], Integer pda, double *imnorm, NagError *fail)

## 3  Description

Any nonsingular matrix $A$ has infinitely many logarithms. For a matrix with no eigenvalues on the closed negative real, the principal logarithm is the unique logarithm whose spectrum lies in the strip $\left\{z:-\pi <\mathrm{Im}\left(z\right)<\pi \right\}$.
$\mathrm{log}\left(A\right)$ is computed using the Schur–Parlett algorithm for the matrix logarithm described in Higham (2008) and Davies and Higham (2003).

## 4  References

Davies P I and Higham N J (2003) A Schur–Parlett algorithm for computing matrix functions. SIAM J. Matrix Anal. Appl. 25(2) 464–485
Higham N J (2008) Functions of Matrices: Theory and Computation SIAM, Philadelphia, PA, USA

## 5  Arguments

1:     orderNag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or Nag_ColMajor.
2:     nIntegerInput
On entry: $n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
3:     a[${\mathbf{pda}}×{\mathbf{n}}$]doubleInput/Output
Note: the $\left(i,j\right)$th element of the matrix $A$ is stored in
• ${\mathbf{a}}\left[\left(j-1\right)×{\mathbf{pda}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{a}}\left[\left(i-1\right)×{\mathbf{pda}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the $n$ by $n$ matrix $A$.
On exit: the $n$ by $n$ principal matrix logarithm, $\mathrm{log}\left(A\right)$.
4:     pdaIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array a.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pda}}\ge {\mathbf{n}}$.
5:     imnormdouble *Output
On exit: if $A$ has complex eigenvalues, nag_matop_real_gen_matrix_log (f01ejc) will use complex arithmetic to compute $\mathrm{log}\left(A\right)$. The imaginary part is discarded at the end of the computation, because it will theoretically vanish. imnorm contains the $1$-norm of the imaginary part, which should be used to check that the routine has given a reliable answer.
If $A$ has real eigenvalues, nag_matop_real_gen_matrix_log (f01ejc) uses real arithmetic and ${\mathbf{imnorm}}=0$.
6:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Allocation of memory failed. If $A$ has real eigenvalues then up to $4×{N}^{2}$ of double allocatable memory may be required. Otherwise up to $4×{N}^{2}$ of Complex allocatable memory may be required.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_EIGENVALUES
$A$ was found to have eigenvalues on the closed, negative real line. The principal logarithm cannot be calculated in this case.
NE_INT
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 0$.
NE_INT_2
On entry, ${\mathbf{pda}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
An unexpected internal error occured when ordering the eigenvalues of $A$. Please contact NAG.
Computation of the square root of a submatrix failed.
Note:  this failure should not occur and suggests that the function has been called incorrectly.
There was an error whilst reordering the Schur form of $A$.
Note:  this failure should not occur and suggests that the function has been called incorrectly.
There was a problem obtaining the weights and nodes from the Gaussian quadrature function nag_quad_1d_gauss_wgen (d01tcc). For details refer to nag_quad_1d_gauss_wgen (d01tcc), ${\mathbf{fail}}=〈\mathit{\text{value}}〉-6$.
The routine was unable to compute the Schur decomposition of $A$.
Note:  this failure should not occur and suggests that the function has been called incorrectly.
NE_SINGULAR
The linear equations to be solved are nearly singular and the Padé approximant may have no correct figures.
Note:  this failure should not occur and suggests that the function has been called incorrectly.

## 7  Accuracy

For a normal matrix $A$ (for which ${A}^{\mathrm{T}}A=A{A}^{\mathrm{T}}$), the Schur decomposition is diagonal and the algorithm reduces to evaluating the logarithm of the eigenvalues of $A$ and then constructing $\mathrm{log}\left(A\right)$ using the Schur vectors. See Section 9.4 of Higham (2008) for details and further discussion.
For discussion of the condition of the matrix logarithm see Section 11.2 of Higham (2008). In particular, the condition number of the logarithm of $A$ is bounded below by the inequality
 $κ log A ≥ κA logA ,$
where $\kappa \left(A\right)$ is the condition number of $A$. Further, the sensitivity of the computation of $\mathrm{log}\left(A\right)$ is worst when $A$ has an eigenvalue of very small modulus, or has a complex conjugate pair of eigenvalues lying close to the negative real axis.

If $A$ has real eigenvalues then up to $4×{{\mathbf{n}}}^{2}$ of double allocatable memory may be required. Otherwise up to $4×{{\mathbf{n}}}^{2}$ of Complex allocatable memory may be required.
The cost of the algorithm is $O\left({n}^{3}\right)$ floating-point operations. The exact cost depends on the eigenvalue distribution of $A$; see Algorithm 11.11 of Higham (2008).
nag_matop_complex_gen_matrix_log (f01fjc) can be used to find the principal logarithm of a complex matrix.

## 9  Example

This example finds the principal matrix logarithm of the matrix
 $A = 3 -3 1 1 2 1 -2 1 1 1 3 -1 2 0 2 0 .$

### 9.1  Program Text

Program Text (f01ejce.c)

### 9.2  Program Data

Program Data (f01ejce.d)

### 9.3  Program Results

Program Results (f01ejce.r)