f01 Chapter Contents
f01 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_matop_real_gen_matrix_cond_log (f01jjc)

## 1  Purpose

nag_matop_real_gen_matrix_cond_log (f01jjc) computes an estimate of the relative condition number ${\kappa }_{\mathrm{log}}\left(A\right)$ of the logarithm of a real $n$ by $n$ matrix $A$, in the $1$-norm. The principal matrix logarithm $\mathrm{log}\left(A\right)$ is also returned.

## 2  Specification

 #include #include
 void nag_matop_real_gen_matrix_cond_log (Integer n, double a[], Integer pda, double *condla, NagError *fail)

## 3  Description

For a matrix with no eigenvalues on the closed negative real line, the principal matrix logarithm $\mathrm{log}\left(A\right)$ is the unique logarithm whose spectrum lies in the strip $\left\{z:-\pi <\mathrm{Im}\left(z\right)<\pi \right\}$.
The Fréchet derivative of the matrix logarithm of $A$ is the unique linear mapping $E⟼L\left(A,E\right)$ such that for any matrix $E$
 $logA+E - logA - LA,E = oE .$
The derivative describes the first order effect of perturbations in $A$ on the logarithm $\mathrm{log}\left(A\right)$.
The relative condition number of the matrix logarithm can be defined by
 $κlogA = LA A logA ,$
where $‖L\left(A\right)‖$ is the norm of the Fréchet derivative of the matrix logarithm at $A$.
To obtain the estimate of ${\kappa }_{\mathrm{log}}\left(A\right)$, nag_matop_real_gen_matrix_cond_log (f01jjc) first estimates $‖L\left(A\right)‖$ by computing an estimate $\gamma$ of a quantity $K\in \left[{n}^{-1}{‖L\left(A\right)‖}_{1},n{‖L\left(A\right)‖}_{1}\right]$, such that $\gamma \le K$.
The algorithms used to compute ${\kappa }_{\mathrm{log}}\left(A\right)$ and $\mathrm{log}\left(A\right)$ are based on a Schur decomposition, the inverse scaling and squaring method and Padé approximants. Further details can be found in Al–Mohy and Higham (2011) and Al–Mohy et al. (2012).

## 4  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 MIMS EPrint 2012.72
Higham N J (2008) Functions of Matrices: Theory and Computation SIAM, Philadelphia, PA, USA

## 5  Arguments

1:     nIntegerInput
On entry: $n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
2:     a[$\mathit{dim}$]doubleInput/Output
Note: the dimension, dim, of the array a must be at least ${\mathbf{pda}}×{\mathbf{n}}$.
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]$.
On entry: the $n$ by $n$ matrix $A$.
On exit: the $n$ by $n$ principal matrix logarithm, $\mathrm{log}\left(A\right)$.
3:     pdaIntegerInput
On entry: the stride separating matrix row elements in the array a.
Constraint: ${\mathbf{pda}}\ge {\mathbf{n}}$.
On exit: with ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_NOERROR or NW_SOME_PRECISION_LOSS, an estimate of the relative condition number of the matrix logarithm, ${\kappa }_{\mathrm{log}}\left(A\right)$. Alternatively, if ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_RCOND, contains the absolute condition number of the matrix logarithm.
5:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
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 {\mathbf{n}}$.
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.
NE_NEGATIVE_EIGVAL
$A$ has eigenvalues on the negative real line. The principal logarithm is not defined in this case; nag_matop_complex_gen_matrix_cond_log (f01kjc) can be used to return a complex, non-principal log.
NE_RCOND
The relative condition number is infinite. The absolute condition number was returned instead.
NE_SINGULAR
$A$ is singular so the logarithm cannot be computed.
NW_SOME_PRECISION_LOSS
$\mathrm{log}\left(A\right)$ has been computed using an IEEE double precision Padé approximant, although the arithmetic precision is higher than IEEE double precision.

## 7  Accuracy

nag_matop_real_gen_matrix_cond_log (f01jjc) uses the norm estimation function nag_linsys_real_gen_norm_rcomm (f04ydc) to produce an estimate $\gamma$ of a quantity $K\in \left[{n}^{-1}{‖L\left(A\right)‖}_{1},n{‖L\left(A\right)‖}_{1}\right]$, such that $\gamma \le K$. For further details on the accuracy of norm estimation, see the documentation for nag_linsys_real_gen_norm_rcomm (f04ydc).
For a normal matrix $A$ (for which ${A}^{\mathrm{T}}A=A{A}^{\mathrm{T}}$), the Schur decomposition is diagonal and the computation of the matrix logarithm reduces to evaluating the logarithm of the eigenvalues of $A$ and then constructing $\mathrm{log}\left(A\right)$ using the Schur vectors. This should give a very accurate result. In general, however, no error bounds are available for the algorithm. 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. See Al–Mohy and Higham (2011) and Section 11.2 of Higham (2008) for details and further discussion.

## 8  Parallelism and Performance

nag_matop_real_gen_matrix_cond_log (f01jjc) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_matop_real_gen_matrix_cond_log (f01jjc) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

nag_matop_real_gen_matrix_cond_std (f01jac) uses a similar algorithm to nag_matop_real_gen_matrix_cond_log (f01jjc) to compute an estimate of the absolute condition number (which is related to the relative condition number by a factor of $‖A‖/‖\mathrm{log}\left(A\right)‖$). However, the required Fréchet derivatives are computed in a more efficient and stable manner by nag_matop_real_gen_matrix_cond_log (f01jjc) and so its use is recommended over nag_matop_real_gen_matrix_cond_std (f01jac).
The amount of real allocatable memory required by the algorithm is typically of the order $10{n}^{2}$.
The cost of the algorithm is $O\left({n}^{3}\right)$ floating-point operations; see Al–Mohy et al. (2012).
If the matrix logarithm alone is required, without an estimate of the condition number, then nag_matop_real_gen_matrix_log (f01ejc) should be used. If the Fréchet derivative of the matrix logarithm is required then nag_matop_real_gen_matrix_frcht_log (f01jkc) should be used. If $A$ has negative real eigenvalues then nag_matop_complex_gen_matrix_cond_log (f01kjc) can be used to return a complex, non-principal matrix logarithm and its condition number.

## 10  Example

This example estimates the relative condition number of the matrix logarithm $\mathrm{log}\left(A\right)$, where
 $A = 4 -1 0 1 2 5 -2 2 1 1 3 -1 2 0 2 8 .$

### 10.1  Program Text

Program Text (f01jjce.c)

### 10.2  Program Data

Program Data (f01jjce.d)

### 10.3  Program Results

Program Results (f01jjce.r)