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

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_matop_complex_gen_matrix_cond_std (f01ka)

## Purpose

nag_matop_complex_gen_matrix_cond_std (f01ka) computes an estimate of the absolute condition number of a matrix function $f$ of a complex $n$ by $n$ matrix $A$ in the $1$-norm, where $f$ is either the exponential, logarithm, sine, cosine, hyperbolic sine (sinh) or hyperbolic cosine (cosh). The evaluation of the matrix function, $f\left(A\right)$, is also returned.

## Syntax

[a, conda, norma, normfa, ifail] = f01ka(fun, a, 'n', n)
[a, conda, norma, normfa, ifail] = nag_matop_complex_gen_matrix_cond_std(fun, a, 'n', n)

## Description

The absolute condition number of $f$ at $A$, ${\mathrm{cond}}_{\mathrm{abs}}\left(f,A\right)$ is given by the norm of the Fréchet derivative of $f$, $L\left(A\right)$, which is defined by
 $LX := maxE≠0 LX,E E ,$
where $L\left(X,E\right)$ is the Fréchet derivative in the direction $E$. $L\left(X,E\right)$ is linear in $E$ and can therefore be written as
 $vec LX,E = KX vecE ,$
where the $\mathrm{vec}$ operator stacks the columns of a matrix into one vector, so that $K\left(X\right)$ is ${n}^{2}×{n}^{2}$. nag_matop_complex_gen_matrix_cond_std (f01ka) computes an estimate $\gamma$ such that $\gamma \le {‖K\left(X\right)‖}_{1}$, where ${‖K\left(X\right)‖}_{1}\in \left[{n}^{-1}{‖L\left(X\right)‖}_{1},n{‖L\left(X\right)‖}_{1}\right]$. The relative condition number can then be computed via
 $cond rel f,A = cond abs f,A A1 fA 1 .$
The algorithm used to find $\gamma$ is detailed in Section 3.4 of Higham (2008).

## References

Higham N J (2008) Functions of Matrices: Theory and Computation SIAM, Philadelphia, PA, USA

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{fun}$ – string
Indicates which matrix function will be used.
${\mathbf{fun}}=\text{'exp'}$
The matrix exponential, ${e}^{A}$, will be used.
${\mathbf{fun}}=\text{'sin'}$
The matrix sine, $\mathrm{sin}\left(A\right)$, will be used.
${\mathbf{fun}}=\text{'cos'}$
The matrix cosine, $\mathrm{cos}\left(A\right)$, will be used.
${\mathbf{fun}}=\text{'sinh'}$
The hyperbolic matrix sine, $\mathrm{sinh}\left(A\right)$, will be used.
${\mathbf{fun}}=\text{'cosh'}$
The hyperbolic matrix cosine, $\mathrm{cosh}\left(A\right)$, will be used.
${\mathbf{fun}}=\text{'log'}$
The matrix logarithm, $\mathrm{log}\left(A\right)$, will be used.
Constraint: ${\mathbf{fun}}=\text{'exp'}$, $\text{'sin'}$, $\text{'cos'}$, $\text{'sinh'}$, $\text{'cosh'}$ or $\text{'log'}$.
2:     $\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.
$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$ matrix, $f\left(A\right)$.
2:     $\mathrm{conda}$ – double scalar
An estimate of the absolute condition number of $f$ at $A$.
3:     $\mathrm{norma}$ – double scalar
The $1$-norm of $A$.
4:     $\mathrm{normfa}$ – double scalar
The $1$-norm of $f\left(A\right)$.
5:     $\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$
An internal error occurred when estimating the norm of the Fréchet derivative of $f$ at $A$. Please contact NAG.
${\mathbf{ifail}}=2$
An internal error occurred when evaluating the matrix function $f\left(A\right)$. You can investigate further by calling nag_matop_complex_gen_matrix_exp (f01fc), nag_matop_complex_gen_matrix_log (f01fj) or nag_matop_complex_gen_matrix_fun_std (f01fk) with the matrix $A$.
${\mathbf{ifail}}=-1$
On entry, ${\mathbf{fun}}=_$ was an illegal value.
${\mathbf{ifail}}=-2$
On entry, ${\mathbf{n}}<0$.
Input argument number $_$ is invalid.
${\mathbf{ifail}}=-4$
On entry, argument lda is invalid.
Constraint: $\mathit{lda}\ge {\mathbf{n}}$.
${\mathbf{ifail}}=-99$
${\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_std (f01ka) uses the norm estimation function nag_linsys_complex_gen_norm_rcomm (f04zd) to estimate a quantity $\gamma$, where $\gamma \le {‖K\left(X\right)‖}_{1}$ and ${‖K\left(X\right)‖}_{1}\in \left[{n}^{-1}{‖L\left(X\right)‖}_{1},n{‖L\left(X\right)‖}_{1}\right]$. For further details on the accuracy of norm estimation, see the documentation for nag_linsys_complex_gen_norm_rcomm (f04zd).

Approximately $6{n}^{2}$ of complex allocatable memory is required by the routine, in addition to the memory used by the underlying matrix function routines nag_matop_complex_gen_matrix_exp (f01fc), nag_matop_complex_gen_matrix_log (f01fj) or nag_matop_complex_gen_matrix_fun_std (f01fk).
nag_matop_complex_gen_matrix_cond_std (f01ka) returns the matrix function $f\left(A\right)$. This is computed using nag_matop_complex_gen_matrix_exp (f01fc) if ${\mathbf{fun}}=\text{'exp'}$, nag_matop_complex_gen_matrix_log (f01fj) if ${\mathbf{fun}}=\text{'log'}$ and nag_matop_complex_gen_matrix_fun_std (f01fk) otherwise. If only $f\left(A\right)$ is required, without an estimate of the condition number, then it is far more efficient to use nag_matop_complex_gen_matrix_exp (f01fc), nag_matop_complex_gen_matrix_log (f01fj) or nag_matop_complex_gen_matrix_fun_std (f01fk) directly.
nag_matop_real_gen_matrix_cond_std (f01ja) can be used to find the condition number of the exponential, logarithm, sine, cosine, sinh or cosh at a real matrix.

## Example

This example estimates the absolute and relative condition numbers of the matrix sinh function for
 $A = 0.0+1.0i -1.0+0.0i 1.0+0.0i 2.0+0.0i 2.0+1.0i 0.0-1.0i 0.0+0.0i 1.0+0.0i 0.0+1.0i 0.0+0.0i 1.0+1.0i 0.0+2.0i 1.0+0.0i 2.0+0.0i -2.0+3.0i 0.0+1.0i .$
```function f01ka_example

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

a = [0+1i, -1+0i,  1+0i,  2+0i;
2+1i,  0-1i,  0+0i,  1+0i;
0+1i,  0+0i,  1+1i,  0+2i;
1+0i,  2+0i, -2+3i,  0+1i];
fun = 'sinh';

% Find absolute condition number estimate
[a, conda, norma, normfa, ifail] = ...
f01ka(fun, a);

fprintf('\nf(A) = %s(A)\n', fun);
fprintf('Estimated absolute condition number is: %7.2f\n', conda);

%  Find relative condition number estimate
eps = x02aj;
if normfa > eps
cond_rel = conda*norma/normfa;
fprintf('Estimated relative condition number is: %7.2f\n', cond_rel);
else
fprintf('The estimated norm of f(A) is effectively zero;\n');
fprintf('the relative condition number is therefore undefined.\n');
end

```
```f01ka example results

f(A) = sinh(A)
Estimated absolute condition number is:    7.33
Estimated relative condition number is:    4.94
```