hide long namesshow long names

hide short namesshow short names

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

▸▿ Contents

1 Purpose

2 Syntax

3 Description

4 References

▸▿ 5 Parameters

5.1 Compulsory Input Parameters

5.2 Optional Input Parameters

5.3 Output Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

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

,

{cond}_{abs} (f, A)

is given by the norm of the Fréchet derivative of

f

,

L (A)

, which is defined by

‖L (X)‖ := \max_{E \neq 0} \frac{‖L (X, E)‖}{‖E‖},

where

L (X, E)

is the Fréchet derivative in the direction

E

.

L (X, E)

is linear in

E

and can therefore be written as

vec (L (X, E)) = K (X) vec (E),

where the

vec

operator stacks the columns of a matrix into one vector, so that

K (X)

is

n^{2} \times n^{2}

. nag_matop_real_gen_matrix_cond_num (f01jb) computes an estimate

γ

such that

γ \leq {‖K (X)‖}_{1}

, where

{‖K (X)‖}_{1} \in [n^{- 1} {‖L (X)‖}_{1}, n {‖L (X)‖}_{1}]

. The relative condition number can then be computed via

{cond}_{rel} (f, A) = \frac{{cond}_{abs} (f, A) {‖A‖}_{1}}{{‖f (A)‖}_{1}} .

The algorithm used to find

γ

is detailed in Section 3.4 of Higham (2008).

The function

f

is supplied via function f which evaluates

f (z_{i})

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: $a (lda :)$ – double array

The first dimension of the array a must be at least

n

.

The second dimension of the array a must be at least

n

.

The

n

by

n

matrix

A

.

2: $f$ – function handle or string containing name of m-file

The function f evaluates

f (z_{i})

at a number of points

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: $n_{z}$ , the number of function values required.
3: $z (nz)$ – complex array: The $n_{z}$ points $z_{1}, z_{2}, \dots, z_{n_{z}}$ at which the function $f$ is to be evaluated.
4: $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: $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)$ ; for instance $f (z)$ may not be defined. If iflag is returned as nonzero then nag_matop_real_gen_matrix_cond_num (f01jb) will terminate the computation, with $ifail = 3$ .
2: $fz (nz)$ – complex array: The $n_{z}$ function values. $fz (i)$ should return the value $f (z_{i})$ , for $i = 1, 2, \dots, n_{z}$ . If $z_{i}$ lies on the real line, then so must $f (z_{i})$ .
3: $user$ – Any MATLAB object

Optional Input Parameters

1: $n$ – int64int32nag_int scalar: Default: the first dimension of the array a.
$n$ , the order of the matrix $A$ .

Constraint: $n \geq 0$ .
2: $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: $a (lda :)$ – double array: The first dimension of the array a will be $n$ .
The second dimension of the array a will be $n$ .

The $n$ by $n$ matrix, $f (A)$ .
2: $user$ – Any MATLAB object
3: $iflag$ – int64int32nag_int scalar: $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 $ifail = 3$ .
4: $conda$ – double scalar: An estimate of the absolute condition number of $f$ at $A$ .
5: $norma$ – double scalar: The $1$ -norm of $A$ .
6: $normfa$ – double scalar: The $1$ -norm of $f (A)$ .
7: $ifail$ – int64int32nag_int scalar: $ifail = 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$: An internal error occurred when estimating the norm of the Fréchet derivative of $f$ at $A$ . Please contact NAG.

$ifail = 2$: An internal error occurred when evaluating the matrix function $f (A)$ . You can investigate further by calling nag_matop_real_gen_matrix_fun_num (f01el) with the matrix $A$ and the function $f$ .

$ifail = 3$: iflag has been set nonzero by the user-supplied function.

$ifail = - 1$: On entry, $n < 0$ .
Input argument number $_$ is invalid.

$ifail = - 3$: On entry, argument lda is invalid.
Constraint: $lda \geq n$ .

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$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

γ

, where

γ \leq {‖K (X)‖}_{1}

and

{‖K (X)‖}_{1} \in [n^{- 1} {‖L (X)‖}_{1}, n {‖L (X)‖}_{1}]

. For further details on the accuracy of norm estimation, see the documentation for nag_linsys_real_gen_norm_rcomm (f04yd).

Further Comments

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 (A)

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

\cos 2 A

where

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

Open in the MATLAB editor: f01jb_example

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

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015