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_log (f01fj)

## Purpose

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

## Syntax

[a, ifail] = f01fj(a, 'n', n)
[a, ifail] = nag_matop_complex_gen_matrix_log(a, 'n', n)

## Description

Any nonsingular matrix A$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 {z : π < Im(z) < π}$\left\{z:-\pi <\mathrm{Im}\left(z\right)<\pi \right\}$. If A$A$ is nonsingular but has eigenvalues on the negative real line, the principal logarithm is not defined, but nag_matop_complex_gen_matrix_log (f01fj) will return a non-principal logarithm.
log(A)$\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).

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

## Parameters

### Compulsory Input Parameters

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

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The first dimension of the array a.
n$n$, the order of the matrix A$A$.
Constraint: n0${\mathbf{n}}\ge 0$.

lda

### Output Parameters

1:     a(lda, : $:$) – complex array
The first dimension of the array a will be max (1,n)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
The second dimension of the array will be n${\mathbf{n}}$
ldamax (1,n)$\mathit{lda}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The n$n$ by n$n$ principal matrix logarithm, log(A)$\mathrm{log}\left(A\right)$, unless ${\mathbf{ifail}}={\mathbf{4}}$, in which case a non-principal logarithm is returned.
2:     ifail – int64int32nag_int scalar
${\mathrm{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:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

ifail = 1${\mathbf{ifail}}=1$
A$A$ is singular so the logarithm cannot be computed.
W ifail = 2${\mathbf{ifail}}=2$
A$A$ was found to have eigenvalues on the negative real line. The principal logarithm is not defined in this case, so a non-principal logarithm was returned.
W ifail = 3${\mathbf{ifail}}=3$
The arithmetic precision is higher than that used for the Padé approximant computed matrix logarithm.
ifail = 4${\mathbf{ifail}}=4$
ifail = 1${\mathbf{ifail}}=-1$
Constraint: n0${\mathbf{n}}\ge 0$.
ifail = 3${\mathbf{ifail}}=-3$
Constraint: ldan$\mathit{lda}\ge {\mathbf{n}}$.
ifail = 999${\mathbf{ifail}}=-999$
Allocation of memory failed. The complex allocatable memory required is approximately 3n2$3{{\mathbf{n}}}^{2}$.

## Accuracy

For a normal matrix A$A$ (for which AHA = AAH${A}^{\mathrm{H}}A=A{A}^{\mathrm{H}}$), the Schur decomposition is diagonal and the algorithm reduces to evaluating the logarithm of the eigenvalues of A$A$ and then constructing log(A)$\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. 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 matrix logarithm at A$A$, κlog (A) ${\kappa }_{\mathrm{log}}\left(A\right)$, which is a measure of the sensitivity of the computed logarithm to perturbations in the matrix A$A$, satisfies
 κlog (A) ≥ (κ(A))/( ‖log(A)‖ ) , $κ log (A) ≥ κ(A) ‖log(A)‖ ,$
where κ(A)$\kappa \left(A\right)$ is the condition number of A$A$. Further, the sensitivity of the computation of log(A)$\mathrm{log}\left(A\right)$ is worst when A$A$ has an eigenvalue of very small modulus, or has a complex conjugate pair of eigenvalues lying close to the negative real axis.

Up to 4n2$4{n}^{2}$ of complex allocatable memory may be required.
The cost of the algorithm is O(n3)$O\left({n}^{3}\right)$ floating point operations. The exact cost depends on the eigenvalue distribution of A$A$; see Algorithm 11.11 of Higham (2008).
If estimates of the condition number of the matrix logarithm are required then nag_matop_complex_gen_matrix_cond_std (f01ka) should be used.
nag_matop_real_gen_matrix_log (f01ej) can be used to find the principal logarithm of a real matrix.

## Example

```function nag_matop_complex_gen_matrix_log_example
a =  [1.0+2.0i,  0.0+1.0i, 1.0+0.0i, 3.0+2.0i;
0.0+3.0i, -2.0+0.0i, 0.0+0.0i, 1.0+0.0i;
1.0+0.0i, -2.0+0.0i, 3.0+2.0i, 0.0+3.0i;
2.0+0.0i,  0.0+1.0i, 0.0+1.0i, 2.0+3.0i];
% Compute log(a)
[a, ifail] = nag_matop_complex_gen_matrix_log(a)
```
```

a =

1.0390 + 1.1672i   0.2859 + 0.3998i   0.0516 - 0.2562i   0.7586 - 0.4678i
-2.7481 + 2.6187i   1.1898 - 2.2287i   0.1369 - 0.9128i   2.1771 - 1.0118i
-0.8514 + 0.3927i  -0.2517 - 0.4791i   1.3839 + 0.2129i   1.1920 + 0.4240i
1.1970 - 0.1242i  -0.6813 + 0.3969i   0.0051 + 0.3511i   0.7867 + 0.7502i

ifail =

0

```
```function f01fj_example
a =  [1.0+2.0i,  0.0+1.0i, 1.0+0.0i, 3.0+2.0i;
0.0+3.0i, -2.0+0.0i, 0.0+0.0i, 1.0+0.0i;
1.0+0.0i, -2.0+0.0i, 3.0+2.0i, 0.0+3.0i;
2.0+0.0i,  0.0+1.0i, 0.0+1.0i, 2.0+3.0i];
% Compute log(a)
[a, ifail] = f01fj(a)
```
```

a =

1.0390 + 1.1672i   0.2859 + 0.3998i   0.0516 - 0.2562i   0.7586 - 0.4678i
-2.7481 + 2.6187i   1.1898 - 2.2287i   0.1369 - 0.9128i   2.1771 - 1.0118i
-0.8514 + 0.3927i  -0.2517 - 0.4791i   1.3839 + 0.2129i   1.1920 + 0.4240i
1.1970 - 0.1242i  -0.6813 + 0.3969i   0.0051 + 0.3511i   0.7867 + 0.7502i

ifail =

0

```

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–2013