NAG Library Function Document

nag_matop_real_gen_matrix_fun_std (f01ekc)

is either the exponential, sine, cosine, sinh or cosh, is computed using the Schur–Parlett algorithm 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: order – Nag_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

order = Nag_RowMajor

. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.

Constraint:

order = Nag_RowMajor

or Nag_ColMajor.

2: fun – Nag_MatFunTypeInput

On entry: indicates which matrix function will be computed.

$fun = Nag_Exp$: The matrix exponential, $e^{A}$ , will be computed.
$fun = Nag_Sin$: The matrix sine, $\sin (A)$ , will be computed.
$fun = Nag_Cos$: The matrix cosine, $\cos (A)$ , will be computed.
$fun = Nag_Sinh$: The hyperbolic matrix sine, $\sinh (A)$ , will be computed.
$fun = Nag_Cosh$: The hyperbolic matrix cosine, $\cosh (A)$ , will be computed.

Constraint:

fun = Nag_Exp

Nag_Sin

Nag_Cos

Nag_Sinh

Nag_Cosh

3: n – IntegerInput

On entry:

n

, the order of the matrix

A

Constraint:

n \geq 0

4: a[ $pda \times n$ ] – doubleInput/Output

Note: the

(i, j)

th element of the matrix

A

is stored in

$a [(j - 1) \times pda + i - 1]$ when $order = Nag_ColMajor$ ;
$a [(i - 1) \times pda + j - 1]$ when $order = Nag_RowMajor$ .

On entry: the

n

n

matrix

A

On exit: the

n

n

matrix,

f (A)

5: pda – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array a.

Constraints:

if $order = Nag_ColMajor$ , $pda \geq \max (1, n)$ ;
if $order = Nag_RowMajor$ , $pda \geq n$ .

6: imnorm – double *Output

On exit: if

A

has complex eigenvalues, nag_matop_real_gen_matrix_fun_std (f01ekc) will use complex arithmetic to compute the matrix function. 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.

A

has real eigenvalues, nag_matop_real_gen_matrix_fun_std (f01ekc) uses real arithmetic and

imnorm = 0

7: fail – NagError *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 $6 \times n^{2}$ of double allocatable memory may be required. Otherwise up to $6 \times n^{2}$ of Complex allocatable memory may be required.
NE_BAD_PARAM: On entry, argument $〈value〉$ had an illegal value.
NE_CONVERGENCE: A Taylor series failed to converge.
NE_INT: On entry, $n = 〈value〉$ .
Constraint: $n \geq 0$ .
NE_INT_2: On entry, $pda = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pda \geq \max (1, 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.; An unexpected internal error occured when evaluating the function at a point. Please contact NAG.; An unexpected internal error occurred when ordering the eigenvalues of $A$ . Please contact NAG.; The function was unable to compute the Schur decomposition of $A$ .
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.
NE_SINGULAR: The linear equations to be solved are nearly singular and the Padé approximant used to compute the exponential 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^{T} A = A A^{T}

), the Schur decomposition is diagonal and the algorithm reduces to evaluating

f

at the eigenvalues of

A

and then constructing

f (A)

using the Schur vectors.

For further discussion of the Schur–Parlett algorithm see Section 9.4 of Higham (2008).

8 Further Comments

The Integer allocatable memory required is

n

. If

A

has real eigenvalues then up to

9 \times n^{2}

of double allocatable memory may be required. If

A

has complex eigenvalues then up to

9 \times n^{2}

of Complex allocatable memory may be required.

The cost of the Schur–Parlett algorithm depends on the spectrum of

A

, but is roughly between

28 n^{3}

and

n^{4} / 3

floating-point operations; see Algorithm 9.6 of Higham (2008).

If the matrix exponential is required then it is recommended that nag_real_gen_matrix_exp (f01ecc) be used as it is, in general, more accurate that nag_matop_real_gen_matrix_fun_std (f01ekc).

nag_matop_complex_gen_matrix_fun_std (f01fkc) can be used to find the matrix exponential, sin, cos, sinh or cosh of a complex matrix.

9 Example

This example finds the matrix cosine of the matrix

A = (\begin{array}{r} 2 & 0 & 1 & 0 \\ 0 & 2 & - 2 & 1 \\ 0 & 2 & 3 & 1 \\ 1 & 4 & 0 & 0 \end{array}) .

NAG Library Function Documentnag_matop_real_gen_matrix_fun_std (f01ekc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Document

nag_matop_real_gen_matrix_fun_std (f01ekc)