Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_matop_complex_gen_matrix_cond_log (f01kj)

## Purpose

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

## Syntax

[a, condla, ifail] = f01kj(a, 'n', n)
[a, condla, ifail] = nag_matop_complex_gen_matrix_cond_log(a, 'n', n)

## 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_complex_gen_matrix_cond_log (f01kj) 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).
If $A$ is nonsingular but has negative real eigenvalues, the principal logarithm is not defined, but nag_matop_complex_gen_matrix_cond_log (f01kj) will return a non-principal logarithm and its condition number.

## 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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension of the array a must be at least ${\mathbf{n}}$.
The second dimension of the array a must be at least ${\mathbf{n}}$.
The $n$ by $n$ matrix $A$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the array a and the second dimension of the array a. (An error is raised if these dimensions are not equal.)
$n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension of the array a will be ${\mathbf{n}}$.
The second dimension of the array a will be ${\mathbf{n}}$.
The $n$ by $n$ principal matrix logarithm, $\mathrm{log}\left(A\right)$. Alternatively, if ${\mathbf{ifail}}={\mathbf{2}}$, a non-principal logarithm is returned.
2:     $\mathrm{condla}$ – double scalar
With ${\mathbf{ifail}}={\mathbf{0}}$, ${\mathbf{2}}$ or ${\mathbf{3}}$, an estimate of the relative condition number of the matrix logarithm, ${\kappa }_{\mathrm{log}}\left(A\right)$. Alternatively, if ${\mathbf{ifail}}={\mathbf{4}}$, contains the absolute condition number of the matrix logarithm.
3:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
$A$ is singular so the logarithm cannot be computed.
${\mathbf{ifail}}=2$
$A$ has eigenvalues on the negative real line. The principal logarithm is not defined in this case, so a non-principal logarithm was returned.
${\mathbf{ifail}}=3$
$\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.
${\mathbf{ifail}}=4$
The relative condition number is infinite. The absolute condition number was returned instead.
${\mathbf{ifail}}=5$
An unexpected internal error occurred. This failure should not occur and suggests that the function has been called incorrectly.
${\mathbf{ifail}}=-1$
Constraint: ${\mathbf{n}}\ge 0$.
${\mathbf{ifail}}=-3$
Constraint: $\mathit{lda}\ge {\mathbf{n}}$.
${\mathbf{ifail}}=-99$
An unexpected error has been triggered by this routine. Please contact NAG.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

nag_matop_complex_gen_matrix_cond_log (f01kj) uses the norm estimation function nag_linsys_complex_gen_norm_rcomm (f04zd) 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_complex_gen_norm_rcomm (f04zd).
For a normal matrix $A$ (for which ${A}^{\mathrm{H}}A=A{A}^{\mathrm{H}}$), 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.

## Further Comments

nag_matop_complex_gen_matrix_cond_std (f01ka) uses a similar algorithm to nag_matop_complex_gen_matrix_cond_log (f01kj) 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_complex_gen_matrix_cond_log (f01kj) and so its use is recommended over nag_matop_complex_gen_matrix_cond_std (f01ka).
The amount of complex 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_complex_gen_matrix_log (f01fj) should be used. If the Fréchet derivative of the matrix logarithm is required then nag_matop_complex_gen_matrix_frcht_log (f01kk) should be used. The real analogue of this function is nag_matop_real_gen_matrix_cond_log (f01jj).

## Example

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

fprintf('f01kj example results\n\n');

% Logarithm and conditioning of matrix A
a =  [3+2i,  1,  1,     1+2i;
0+2i, -4,  0,     0;
1,    -2,  3+2i,  0+i;
1,     i,  1,     2+3i];

% Compute log(a)
[loga, condla, ifail] = f01kj(a);

% Display results
disp('Log(A):');
disp(loga);

fprintf('Estimated condition number is: %6.2f\n', condla);

```
```f01kj example results

Log(A):
1.4498 + 0.5154i   0.3665 + 0.6955i   0.1358 - 0.1097i   0.4890 + 0.1622i
-0.9351 + 0.2859i   1.2908 - 2.8365i   0.1010 - 0.0672i   0.3128 + 0.2538i
-0.1399 - 0.1083i  -0.3208 - 0.8912i   1.2738 + 0.5775i   0.2658 + 0.3127i
0.3049 - 0.0019i  -0.4858 + 0.3215i   0.1797 - 0.1922i   1.1843 + 0.9427i

Estimated condition number is:   2.25
```

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015