hide long namesshow long 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 Toolbox: nag_matop_real_gen_matrix_cond_std (f01ja)

▸▿ 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_std (f01ja) computes an estimate of the absolute condition number of a matrix function

f

at a real

n

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

, is also returned.

Syntax

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

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

Description

The absolute condition number of

f

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)

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

. nag_matop_real_gen_matrix_cond_std (f01ja) 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).

References

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

Parameters

Compulsory Input Parameters

1: $fun$ – string

Indicates which matrix function will be used.

$fun ='exp'$: The matrix exponential, $e^{A}$ , will be used.
$fun ='sin'$: The matrix sine, $\sin (A)$ , will be used.
$fun ='cos'$: The matrix cosine, $\cos (A)$ , will be used.
$fun ='sinh'$: The hyperbolic matrix sine, $\sinh (A)$ , will be used.
$fun ='cosh'$: The hyperbolic matrix cosine, $\cosh (A)$ , will be used.
$fun ='log'$: The matrix logarithm, $\log (A)$ , will be used.

Constraint:

fun ='exp'

'sin'

'cos'

'sinh'

'cosh'

'log'

2: $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

n

matrix

A

Optional Input Parameters

1: $n$ – int64int32nag_int scalar: Default: the first dimension of the array a and the second dimension of the array a. (An error is raised if these dimensions are not equal.)
$n$ , the order of the matrix $A$ .

Constraint: $n \geq 0$ .

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: $conda$ – double scalar: An estimate of the absolute condition number of $f$ at $A$ .
3: $norma$ – double scalar: The $1$ -norm of $A$ .
4: $normfa$ – double scalar: The $1$ -norm of $f (A)$ .
5: $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 evaluating the matrix function $f (A)$ . Please contact NAG.

$ifail = 2$: An internal error occurred when estimating the norm of the Fréchet derivative of $f$ at $A$ . Please contact NAG.

$ifail = - 1$: On entry, $fun =_$ was an illegal value.

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

$ifail = - 4$: 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_std (f01ja) 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 one of three underlying matrix function routines:

if $fun ='exp'$ , nag_matop_real_gen_matrix_exp (f01ec) is used;
if $fun ='log'$ , nag_matop_real_gen_matrix_log (f01ej) is used;
else, nag_matop_real_gen_matrix_fun_std (f01ek) is used.

Approximately

6 n^{2}

of real allocatable memory is required by the routine, in addition to the memory used by these underlying matrix function routines.

If only

f (A)

is required, without an estimate of the condition number, then it is far more efficient to use the appropriate matrix function routine listed above.

nag_matop_complex_gen_matrix_cond_std (f01ka) can be used to find the condition number of the exponential, logarithm, sine, cosine, sinh or cosh matrix functions at a complex matrix.

Example

This example estimates the absolute and relative condition numbers of the matrix sinh function where

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

Open in the MATLAB editor: f01ja_example

function f01ja_example


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

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

% Find absolute condition number estimate
[a, conda, norma, normfa, ifail] = f01ja( ...
                                          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

f01ja example results


f(A) = sinh(A)
Estimated absolute condition number is:  204.45
Estimated relative condition number is:    7.90

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox