hide long namesshow long names
hide short namesshow short names
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_real_gen_matrix_log (f01ej)

Purpose

nag_matop_real_gen_matrix_log (f01ej) computes the principal matrix logarithm, log(A)log(A), of a real nn by nn matrix AA, with no eigenvalues on the closed negative real line.

Syntax

[a, imnorm, ifail] = f01ej(a, 'n', n)
[a, imnorm, ifail] = nag_matop_real_gen_matrix_log(a, 'n', n)

Description

Any nonsingular matrix AA 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) < π}{z:-π<Im(z)<π}.
log(A)log(A) 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, : :) – double array
The first dimension of the array a must be at least max (1,n)max(1,n)
The second dimension of the array must be at least nn
The nn by nn matrix AA.

Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The second dimension of the array a.
nn, the order of the matrix AA.
Constraint: n0n0.

Input Parameters Omitted from the MATLAB Interface

lda

Output Parameters

1:     a(lda, : :) – double array
The first dimension of the array a will be max (1,n)max(1,n)
The second dimension of the array will be nn
ldamax (1,n)ldamax(1,n).
The nn by nn principal matrix logarithm, log(A)log(A).
2:     imnorm – double scalar
imnorm = 0imnorm=0. This parameter is no longer required by nag_matop_real_gen_matrix_log (f01ej).
3:     ifail – int64int32nag_int scalar
ifail = 0ifail=0 unless the function detects an error (see [Error Indicators and Warnings]).

Error Indicators and Warnings

Errors or warnings detected by the function:
  ifail = 1ifail=1
There was an error whilst reordering the Schur form of AA.
Note:  this failure should not occur and suggests that the function has been called incorrectly.
  ifail = 2ifail=2
AA is singular so the logarithm cannot be computed.
  ifail = 3ifail=3
The routine was unable to compute the Schur decomposition of AA.
Note:  this failure should not occur and suggests that the function has been called incorrectly.
  ifail = 4ifail=4
AA was found to have eigenvalues on the closed, negative real line. The principal logarithm is not defined in this case, so a non-principal logarithm was returned.
  ifail = 5ifail=5
An unexpected internal error occurred. Please contact NAG.
  ifail = 6ifail=6
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.
There was a problem obtaining the weights and nodes from the Gaussian quadrature function nag_quad_1d_gauss_wgen (d01bc).
  ifail = 1ifail=-1
Input parameter number __ is invalid.
  ifail = 3ifail=-3
On entry, parameter lda is invalid.
Constraint: ldanldan.
  ifail = 999ifail=-999
Allocation of memory failed. If AA has real eigenvalues then up to 4 × N24×N2 of double allocatable memory may be required. Otherwise up to 4 × N24×N2 of complex allocatable memory may be required.

Accuracy

For a normal matrix AA (for which ATA = AATATA=AAT), the Schur decomposition is diagonal and the algorithm reduces to evaluating the logarithm of the eigenvalues of AA and then constructing log(A)log(A) 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 AA, κlog (A) κ log (A) , which is a measure of the sensitivity of the computed logarithm to perturbations in the matrix AA, satisfies
κlog (A) (κ(A))/(log(A)) ,
κ log (A) κ(A) log(A) ,
where κ(A)κ(A) is the condition number of AA. Further, the sensitivity of the computation of log(A)log(A) is worst when AA has an eigenvalue of very small modulus, or has a complex conjugate pair of eigenvalues lying close to the negative real axis.

Further Comments

If AA has real eigenvalues then up to 4n24n2 of double allocatable memory may be required. Otherwise up to 4n24n2 of complex allocatable memory may be required.
The cost of the algorithm is O(n3)O(n3) floating point operations. The exact cost depends on the eigenvalue distribution of AA; see Algorithm 11.11 of Higham (2008).
If estimates of the condition number of the matrix logarithm are required then nag_matop_real_gen_matrix_cond_std (f01ja) should be used.
nag_matop_complex_gen_matrix_log (f01fj) can be used to find the principal logarithm of a complex matrix. It can also be used to return a complex, non-principal logarithm if a real matrix has no principal logarithm due to the presence of negative eigenvalues.

Example

function nag_matop_real_gen_matrix_log_example
a =  [3, -3,  1,  1;
      2,  1, -2,  1;
      1,  1,  3, -1;
      2,  0,  2,  0];
% Compute log(a)
[a, imnorm, ifail] = nag_matop_real_gen_matrix_log(a)
 

a =

    1.1957   -1.2076   -0.5802    1.0872
    0.8464    1.0133   -0.5985   -0.1641
    0.4389    0.6701    1.8449   -1.2111
    1.2792    0.6177    2.1448   -1.9743


imnorm =

   5.4895e-16


ifail =

                    0


function f01ej_example
a =  [3, -3,  1,  1;
      2,  1, -2,  1;
      1,  1,  3, -1;
      2,  0,  2,  0];
% Compute log(a)
[a, imnorm, ifail] = f01ej(a)
 

a =

    1.1957   -1.2076   -0.5802    1.0872
    0.8464    1.0133   -0.5985   -0.1641
    0.4389    0.6701    1.8449   -1.2111
    1.2792    0.6177    2.1448   -1.9743


imnorm =

   5.4895e-16


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