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_num (f01kb)

## Purpose

nag_matop_complex_gen_matrix_cond_num (f01kb) computes an estimate of the absolute condition number of a matrix function f$f$ at a complex n$n$ by n$n$ matrix A$A$ in the 1$1$-norm. Numerical differentiation is used to evaluate the derivatives of f$f$ when they are required.

## Syntax

[a, user, iflag, conda, norma, normfa, ifail] = f01kb(a, f, 'n', n, 'user', user)
[a, user, iflag, conda, norma, normfa, ifail] = nag_matop_complex_gen_matrix_cond_num(a, f, 'n', n, 'user', user)

## Description

The absolute condition number of f$f$ at A$A$, condabs(f,A)${\mathrm{cond}}_{\mathrm{abs}}\left(f,A\right)$ is given by the norm of the Fréchet derivative of f$f$, L(A,E)$L\left(A,E\right)$, which is defined by
 ‖L(X)‖ := maxE ≠ 0 (‖L(X,E)‖)/(‖E‖) . $‖L(X)‖ := maxE≠0 ‖L(X,E)‖ ‖E‖ .$
The Fréchet derivative in the direction E$E$, L(X,E)$L\left(X,E\right)$ is linear in E$E$ and can therefore be written as
 vec (L(X,E)) = K(X) vec(E) , $vec ( L(X,E) ) = K(X) vec(E) ,$
where the vec$\mathrm{vec}$ operator stacks the columns of a matrix into one vector, so that K(X)$K\left(X\right)$ is n2 × n2${n}^{2}×{n}^{2}$. nag_matop_complex_gen_matrix_cond_num (f01kb) computes an estimate γ$\gamma$ such that γ K(X)1 $\gamma \le {‖K\left(X\right)‖}_{1}$, where K(X)1 [ n1 L(X)1 , n L(X)1 ] ${‖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
 condrel (f,A) = ( condabs (f,A) ‖A‖1 )/(‖f(A)‖1) . $cond rel (f,A) = cond abs (f,A) ‖A‖1 ‖f(A)‖ 1 .$
The algorithm used to find γ$\gamma$ is detailed in Section 3.4 of Higham (2008).
The function f$f$ is supplied via function f which evaluates f(zi)$f\left({z}_{i}\right)$ at a number of points zi${z}_{i}$.

## References

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

Input Parameters

1:     iflag – int64int32nag_int scalar
iflag will be zero.
2:     nz – int64int32nag_int scalar
nz${n}_{z}$, the number of function values required.
3:     z(nz) – complex array
The nz${n}_{z}$ points z1,z2,,znz${z}_{1},{z}_{2},\dots ,{z}_{{n}_{z}}$ at which the function f$f$ is to be evaluated.
4:     user – Any MATLAB object
f is called from nag_matop_complex_gen_matrix_cond_num (f01kb) with the object supplied to nag_matop_complex_gen_matrix_cond_num (f01kb).

Output Parameters

1:     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(z)$f\left(z\right)$; for instance f(z)$f\left(z\right)$ may not be defined. If iflag is returned as nonzero then nag_matop_complex_gen_matrix_cond_num (f01kb) will terminate the computation, with ${\mathbf{ifail}}={\mathbf{3}}$.
2:     fz(nz) – complex array
The nz${n}_{z}$ function values. fz(i)${\mathbf{fz}}\left(\mathit{i}\right)$ should return the value f(zi)$f\left({z}_{\mathit{i}}\right)$, for i = 1,2,,nz$\mathit{i}=1,2,\dots ,{n}_{z}$.
3:     user – Any MATLAB object

### 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$.
2:     user – Any MATLAB object
user is not used by nag_matop_complex_gen_matrix_cond_num (f01kb), 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.

lda iuser ruser

### 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$ matrix, f(A)$f\left(A\right)$.
2:     user – Any MATLAB object
3:     iflag – int64int32nag_int scalar
iflag = 0${\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{3}}$.
4:     conda – double scalar
An estimate of the absolute condition number of f$f$ at A$A$.
5:     norma – double scalar
The 1$1$-norm of A$A$.
6:     normfa – double scalar
The 1$1$-norm of f(A)$f\left(A\right)$.
7:     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:
ifail = 1${\mathbf{ifail}}=1$
An internal error occurred when estimating the norm of the Fréchet derivative of f$f$ at A$A$. Please contact NAG.
ifail = 2${\mathbf{ifail}}=2$
An internal error occurred while evaluating the matrix function f(A)$f\left(A\right)$. You can investigate further by calling nag_matop_complex_gen_matrix_fun_num (f01fl) with the matrix A$A$ and the function f$f$.
ifail = 3${\mathbf{ifail}}=3$
iflag has been set nonzero by the user-supplied function.
ifail = 1${\mathbf{ifail}}=-1$
On entry, n < 0${\mathbf{n}}<0$.
ifail = 3${\mathbf{ifail}}=-3$
On entry, parameter lda is invalid.
Constraint: ldan$\mathit{lda}\ge {\mathbf{n}}$.
ifail = 999${\mathbf{ifail}}=-999$
Allocation of memory failed.

## Accuracy

nag_matop_complex_gen_matrix_cond_num (f01kb) uses the norm estimation function nag_linsys_real_gen_norm_rcomm (f04yd) to estimate a quantity γ$\gamma$, where γ K(X)1 $\gamma \le {‖K\left(X\right)‖}_{1}$ and K(X)1 [ n1 L(X)1 , n L(X)1 ] ${‖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 6n2$6{n}^{2}$ of complex allocatable memory is required by the routine, in addition to the memory used by the underlying matrix function routine nag_matop_complex_gen_matrix_fun_num (f01fl).
nag_matop_complex_gen_matrix_cond_num (f01kb) returns the matrix function f(A)$f\left(A\right)$. This is computed using nag_matop_complex_gen_matrix_fun_num (f01fl). If only f(A)$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_fun_num (f01fl) directly.
The real analogue of this function is nag_matop_real_gen_matrix_cond_num (f01jb).

## Example

```function nag_matop_complex_gen_matrix_cond_num_example
a = [2+0i, 0+1i, 1+1i, 0+3i;
1+1i, 0+2i, 2+2i, 0+0i;
0+0i, 2+0i, 1+2i, 1+0i;
1+1i, 3+0i, 0+0i, 1+2i];
% Find absolute condition number estimate
[a, user, iflag, conda, norma, normfa, ifail] = nag_matop_complex_gen_matrix_cond_num(a, @fsin2);

fprintf('\nF(a) = sin(2a)\n');
fprintf('Estimated absolute condition number is: %7.2f\n', conda);

%  Find relative condition number estimate
eps = nag_machine_precision;
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 and so the\nrelative condition number is undefined.\n');
end

function [iflag, fz, user] = fsin2(iflag, nz, z, user)
fz = sin(2*z);
```
```

F(a) = sin(2a)
Estimated absolute condition number is: 2016.99
Estimated relative condition number is:   12.86

```
```function f01kb_example
a = [2+0i, 0+1i, 1+1i, 0+3i;
1+1i, 0+2i, 2+2i, 0+0i;
0+0i, 2+0i, 1+2i, 1+0i;
1+1i, 3+0i, 0+0i, 1+2i];
% Find absolute condition number estimate
[a, user, iflag, conda, norma, normfa, ifail] = f01kb(a, @fsin2);

fprintf('\nF(a) = sin(2a)\n');
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 and so the\nrelative condition number is undefined.\n');
end

function [iflag, fz, user] = fsin2(iflag, nz, z, user)
fz = sin(2*z);
```
```

F(a) = sin(2a)
Estimated absolute condition number is: 2016.99
Estimated relative condition number is:   12.86

```