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_cond_num (f01jb)

## Purpose

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

## Syntax

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

## 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_real_gen_matrix_cond_num (f01jb) 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).
The function $f$ is supplied via function f which evaluates $f\left({z}_{i}\right)$ at a number of points ${z}_{i}$.

## References

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)$ – double 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
The function f evaluates $f\left({z}_{i}\right)$ at a number of points ${z}_{i}$.
[iflag, fz, user] = f(iflag, nz, z, user)

Input Parameters

1:     $\mathrm{iflag}$int64int32nag_int scalar
iflag will be zero.
2:     $\mathrm{nz}$int64int32nag_int scalar
${n}_{z}$, the number of function values required.
3:     $\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.
4:     $\mathrm{user}$ – Any MATLAB object
f is called from nag_matop_real_gen_matrix_cond_num (f01jb) with the object supplied to nag_matop_real_gen_matrix_cond_num (f01jb).

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\right)$ may not be defined. If iflag is returned as nonzero then nag_matop_real_gen_matrix_cond_num (f01jb) will terminate the computation, with ${\mathbf{ifail}}={\mathbf{3}}$.
2:     $\mathrm{fz}\left({\mathbf{nz}}\right)$ – complex array
The ${n}_{z}$ function values. ${\mathbf{fz}}\left(\mathit{i}\right)$ should return the value $f\left({z}_{\mathit{i}}\right)$, for $\mathit{i}=1,2,\dots ,{n}_{z}$. If ${z}_{i}$ lies on the real line, then so must $f\left({z}_{i}\right)$.
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_real_gen_matrix_cond_num (f01jb), 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)$ – double 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{3}}$.
4:     $\mathrm{conda}$ – double scalar
An estimate of the absolute condition number of $f$ at $A$.
5:     $\mathrm{norma}$ – double scalar
The $1$-norm of $A$.
6:     $\mathrm{normfa}$ – double scalar
The $1$-norm of $f\left(A\right)$.
7:     $\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_real_gen_matrix_fun_num (f01el) with the matrix $A$ and the function $f$.
${\mathbf{ifail}}=3$
iflag has been set nonzero by the user-supplied function.
${\mathbf{ifail}}=-1$
On entry, ${\mathbf{n}}<0$.
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

nag_matop_real_gen_matrix_cond_num (f01jb) uses the norm estimation function nag_linsys_real_gen_norm_rcomm (f04yd) 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_real_gen_norm_rcomm (f04yd).

The matrix function is computed using the underlying matrix function routine nag_matop_real_gen_matrix_fun_num (f01el). Approximately $6{n}^{2}$ of real allocatable memory is required by the routine, in addition to the memory used by the underlying matrix function routine.
If only $f\left(A\right)$ is required, without an estimate of the condition number, then it is far more efficient to use the underlying matrix function routine.
The complex analogue of this function is nag_matop_complex_gen_matrix_cond_num (f01kb).

## Example

This example estimates the absolute and relative condition numbers of the matrix function $\mathrm{cos}2A$ where
 $A= -1 -1 -2 1 0 1 -1 0 -1 -2 1 -1 0 -1 0 -1 .$
```function f01jb_example

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

a = [-1,  -1,  -2,   1;
0,   1,  -1,   0;
-1,  -2,   1,  -1;
0,  -1,   0,  -1];

% Find absolute condition number estimate
[a, user, iflag, conda, norma, normfa, ifail] = ...
f01jb(a, @fcos2);

fprintf('\nf(a) = cos(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;\n');
fprintf('the relative condition number is therefore undefined.\n');
end

function [iflag, fz, user] = fcos2(iflag, nz, z, user)
fz = cos(2*z);
```
```f01jb example results

f(a) = cos(2A)
Estimated absolute condition number is:    4.10
Estimated relative condition number is:   14.48
```

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