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_fun_usd (f01fm)

## Purpose

nag_matop_complex_gen_matrix_fun_usd (f01fm) computes the matrix function, $f\left(A\right)$, of a complex $n$ by $n$ matrix $A$, using analytical derivatives of $f$ you have supplied.

## Syntax

[a, user, iflag, ifail] = f01fm(a, f, 'n', n, 'user', user)
[a, user, iflag, ifail] = nag_matop_complex_gen_matrix_fun_usd(a, f, 'n', n, 'user', user)

## Description

$f\left(A\right)$ is computed using the Schur–Parlett algorithm described in Higham (2008) and Davies and Higham (2003).
The scalar function $f$, and the derivatives of $f$, are returned by the function f which, given an integer $m$, should evaluate ${f}^{\left(m\right)}\left({z}_{\mathit{i}}\right)$ at a number of points ${z}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,{n}_{z}$, on the complex plane. nag_matop_complex_gen_matrix_fun_usd (f01fm) is therefore appropriate for functions that can be evaluated on the complex plane and whose derivatives, of arbitrary order, can also be evaluated on the complex plane.

## 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:     $\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$.
2:     $\mathrm{f}$ – function handle or string containing name of m-file
Given an integer $m$, the function f evaluates ${f}^{\left(m\right)}\left({z}_{i}\right)$ at a number of points ${z}_{i}$.
[iflag, fz, user] = f(m, iflag, nz, z, user)

Input Parameters

1:     $\mathrm{m}$int64int32nag_int scalar
The order, $m$, of the derivative required.
If ${\mathbf{m}}=0$, $f\left({z}_{i}\right)$ should be returned. For ${\mathbf{m}}>0$, ${f}^{\left(m\right)}\left({z}_{i}\right)$ should be returned.
2:     $\mathrm{iflag}$int64int32nag_int scalar
iflag will be zero.
3:     $\mathrm{nz}$int64int32nag_int scalar
${n}_{z}$, the number of function or derivative values required.
4:     $\mathrm{z}\left({\mathbf{nz}}\right)$ – complex array
The ${n}_{z}$ points ${z}_{1},{z}_{2},\dots ,{z}_{{n}_{z}}$ at which the function $f$ is to be evaluated.
5:     $\mathrm{user}$ – Any MATLAB object
f is called from nag_matop_complex_gen_matrix_fun_usd (f01fm) with the object supplied to nag_matop_complex_gen_matrix_fun_usd (f01fm).

Output Parameters

1:     $\mathrm{iflag}$int64int32nag_int scalar
iflag should either be unchanged from its entry value of zero, or may be set nonzero to indicate that there is a problem in evaluating the function $f\left(z\right)$; for instance $f\left({z}_{i}\right)$ may not be defined for a particular ${z}_{i}$. If iflag is returned as nonzero then nag_matop_complex_gen_matrix_fun_usd (f01fm) will terminate the computation, with ${\mathbf{ifail}}={\mathbf{2}}$.
2:     $\mathrm{fz}\left({\mathbf{nz}}\right)$ – complex array
The ${n}_{z}$ function or derivative values. ${\mathbf{fz}}\left(\mathit{i}\right)$ should return the value ${f}^{\left(m\right)}\left({z}_{\mathit{i}}\right)$, for $\mathit{i}=1,2,\dots ,{n}_{z}$.
3:     $\mathrm{user}$ – Any MATLAB object

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the array a.
$n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
2:     $\mathrm{user}$ – Any MATLAB object
user is not used by nag_matop_complex_gen_matrix_fun_usd (f01fm), but is passed to f. Note that for large objects it may be more efficient to use a global variable which is accessible from the m-files than to use user.

### 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$ matrix, $f\left(A\right)$.
2:     $\mathrm{user}$ – Any MATLAB object
3:     $\mathrm{iflag}$int64int32nag_int scalar
${\mathbf{iflag}}=0$, unless iflag has been set nonzero inside f, in which case iflag will be the value set and ifail will be set to ${\mathbf{ifail}}={\mathbf{2}}$.
4:     $\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 Taylor series failed to converge.
${\mathbf{ifail}}=2$
iflag has been set nonzero by the user.
${\mathbf{ifail}}=3$
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.
${\mathbf{ifail}}=4$
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.
${\mathbf{ifail}}=5$
An unexpected internal error occurred. Please contact NAG.
${\mathbf{ifail}}=-1$
Input argument number $_$ is invalid.
${\mathbf{ifail}}=-3$
On entry, argument lda is invalid.
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

For a normal matrix $A$ (for which ${A}^{\mathrm{H}}A=A{A}^{\mathrm{H}}$), the Schur decomposition is diagonal and the algorithm reduces to evaluating $f$ at the eigenvalues of $A$ and then constructing $f\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 further discussion of the Schur–Parlett algorithm.

## Further Comments

Up to $6{n}^{2}$ of complex allocatable memory is 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. There is an additional cost in evaluating $f$ and its derivatives. If the derivatives of $f$ are not known analytically, then nag_matop_complex_gen_matrix_fun_num (f01fl) can be used to evaluate $f\left(A\right)$ using numerical differentiation. If $A$ is complex Hermitian then it is recommended that nag_matop_complex_herm_matrix_fun (f01ff) be used as it is more efficient and, in general, more accurate than nag_matop_complex_gen_matrix_fun_usd (f01fm).
Note that $f$ must be analytic in the region of the complex plane containing the spectrum of $A$.
For further information on matrix functions, see Higham (2008).
If estimates of the condition number of the matrix function are required then nag_matop_complex_gen_matrix_cond_usd (f01kc) should be used.
nag_matop_real_gen_matrix_fun_usd (f01em) can be used to find the matrix function $f\left(A\right)$ for a real matrix $A$.

## Example

This example finds the ${e}^{3A}$ where
 $A= 1.0+0.0i 0.0+0.0i 1.0+0.0i 0.0+2.0i 0.0+1.0i 1.0+0.0i -1.0+0.0i 1.0+0.0i -1.0+0.0i 0.0+1.0i 0.0+1.0i 0.0+1.0i 1.0+1.0i 0.0+2.0i -1.0+0.0i 0.0+1.0i .$
```function f01fm_example

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

a = [ 1.0+0.0i, 0.0+0.0i,  1.0+0.0i, 0.0+2.0i;
0.0+1.0i, 1.0+0.0i, -1.0+0.0i, 1.0+0.0i;
-1.0+0.0i, 0.0+1.0i,  0.0+1.0i, 0.0+1.0i;
1.0+1.0i, 0.0+2.0i, -1.0+0.0i, 0.0+1.0i];

% Compute exp(3*a)
[exp3a, user, iflag, ifail] = f01fm(a, @f);

disp('f(A) = exp(3A)');
disp(exp3a);

function [iflag, fz, user] = f(m, iflag, nz, z, user)
fz = double(3^m)*exp(3*z);
```
```f01fm example results

f(A) = exp(3A)
-10.3264 +14.8082i  -1.4883 +74.3369i -12.1206 -47.0956i  41.5622 +32.2927i
63.3909 -40.5336i -21.0117 -62.7073i  16.5106 +35.2787i  -5.1725 +17.9413i
-6.3954 +56.4708i  25.4246 +13.8034i -14.4937 - 9.2397i -20.3167 + 2.8647i
31.4957 +23.2757i  28.6003 +21.4573i -23.8034 -11.6547i  23.9841 +18.7737i

```

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