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 Toolbox: nag_matop_real_symm_matrix_fun (f01ef)

Purpose

nag_matop_real_symm_matrix_fun (f01ef) computes the matrix function, f(A)f(A), of a real symmetric nn by nn matrix AA. f(A)f(A) must also be a real symmetric matrix.

Syntax

[a, user, iflag, ifail] = f01ef(uplo, a, f, 'n', n, 'user', user)
[a, user, iflag, ifail] = nag_matop_real_symm_matrix_fun(uplo, a, f, 'n', n, 'user', user)

Description

f(A)f(A) is computed using a spectral factorization of AA 
A = Q D QT ,
A = Q D QT ,
where DD is the diagonal matrix whose diagonal elements, didi, are the eigenvalues of AA, and QQ is an orthogonal matrix whose columns are the eigenvectors of AA. f(A)f(A) is then given by
f(A) = Q f(D) QT ,
f(A) = Q f(D) QT ,
where f(D)f(D) is the diagonal matrix whose iith diagonal element is f(di)f(di). See for example Section 4.5 of Higham (2008). f(di)f(di) is assumed to be real.

References

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

Parameters

Compulsory Input Parameters

1:     uplo – string (length ≥ 1)
If uplo = 'U'uplo='U', the upper triangle of the matrix AA is stored.
If uplo = 'L'uplo='L', the lower triangle of the matrix AA is stored.
Constraint: uplo = 'U'uplo='U' or 'L''L'.
2:     a(lda, : :) – double array
The first dimension of the array a must be at least max (1,n)max(1,n)
The second dimension of the array must be at least nn
The nn by nn symmetric matrix AA.
  • If uplo = 'U'uplo='U', the upper triangular part of aa must be stored and the elements of the array below the diagonal are not referenced.
  • If uplo = 'L'uplo='L', the lower triangular part of aa must be stored and the elements of the array above the diagonal are not referenced.
3:     f – function handle or string containing name of m-file
The function f evaluates f(zi)f(zi) at a number of points zizi.
[iflag, fx, user] = f(iflag, n, x, user)

Input Parameters

1:     iflag – int64int32nag_int scalar
iflag will be zero.
2:     n – int64int32nag_int scalar
nn, the number of function values required.
3:     x(n) – double array
The nn points x1,x2,,xnx1,x2,,xn at which the function ff is to be evaluated.
4:     user – Any MATLAB object
f is called from nag_matop_real_symm_matrix_fun (f01ef) with the object supplied to nag_matop_real_symm_matrix_fun (f01ef).

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(x)f(x); for instance f(x)f(x) may not be defined, or may be complex. If iflag is returned as nonzero then nag_matop_real_symm_matrix_fun (f01ef) will terminate the computation, with ifail = 6ifail=-6.
2:     fx(n) – double array
The nn function values. fx(i)fxi should return the value f(xi)f(xi), for i = 1,2,,ni=1,2,,n.
3:     user – Any MATLAB object

Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The first dimension of the array a.
nn, the order of the matrix AA.
Constraint: n0n0.
2:     user – Any MATLAB object
user is not used by nag_matop_real_symm_matrix_fun (f01ef), 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.

Input Parameters Omitted from the MATLAB Interface

lda iuser ruser

Output Parameters

1:     a(lda, : :) – double array
The first dimension of the array a will be max (1,n)max(1,n)
The second dimension of the array will be nn
ldamax (1,n)ldamax(1,n).
If ifail = 0ifail=0, the upper or lower triangular part of the nn by nn matrix function, f(A)f(A).
2:     user – Any MATLAB object
3:     iflag – int64int32nag_int scalar
iflag = 0iflag=0, unless you have set iflag nonzero inside f, in which case iflag will be the value you set and ifail will be set to ifail = 6ifail=-6.
4:     ifail – int64int32nag_int scalar
ifail = 0ifail=0 unless the function detects an error (see [Error Indicators and Warnings]).

Error Indicators and Warnings

Errors or warnings detected by the function:
  ifail > 0ifail>0
The computation of the spectral factorization failed to converge.
  ifail = 1ifail=-1
Constraint: uplo = 'L'uplo='L' or 'U''U'.
  ifail = 2ifail=-2
Constraint: n0n0.
  ifail = 3ifail=-3
An internal error occurred when computing the spectral factorization. Please contact NAG.
  ifail = 4ifail=-4
Constraint: ldanldan.
  ifail = 6ifail=-6
iflag was set to a nonzero value in f.
  ifail = 999ifail=-999
Dynamic memory allocation failed.

Accuracy

Provided that f(D)f(D) can be computed accurately then the computed matrix function will be close to the exact matrix function. See Section 10.2 of Higham (2008) for details and further discussion.

Further Comments

The cost of the algorithm is O(n3)O(n3) plus the cost of evaluating f(D)f(D). If λ̂iλ^i is the iith computed eigenvalue of AA, then the user-supplied function f will be asked to evaluate the function ff at f(λ̂i)f(λ^i), i = 1,2,,ni=1,2,,n.
For further information on matrix functions, see Higham (2008).
nag_matop_complex_herm_matrix_fun (f01ff) can be used to find the matrix function f(A)f(A) for a complex Hermitian matrix AA.

Example

function nag_matop_real_symm_matrix_fun_example
uplo = 'u';
a =  [1, 2, 3, 4;
      0, 1, 2, 3;
      0, 0, 1, 2;
      0, 0, 0, 1];
% Compute f(a)
[aOut, user, iflag, ifail] = nag_matop_real_symm_matrix_fun(uplo, a, @f);
% Display results
[ifail] = nag_file_print_matrix_real_gen(uplo, 'n', aOut, 'Symmetric f(a)')

function [iflag, fx, user] = f(iflag, n, x, user)
  fx = cos(x);
 
 Symmetric f(a)
          1       2       3       4
 1  -0.5420 -0.6612 -0.0261  0.1580
 2           0.2306 -0.3396 -0.0261
 3                   0.2306 -0.6612
 4                          -0.5420

ifail =

                    0


function f01ef_example
uplo = 'u';
a =  [1, 2, 3, 4;
      0, 1, 2, 3;
      0, 0, 1, 2;
      0, 0, 0, 1];
% Compute f(a)
[aOut, user, iflag, ifail] = f01ef(uplo, a, @f);
% Display results
[ifail] = x04ca(uplo, 'n', aOut, 'Symmetric f(a)')

function [iflag, fx, user] = f(iflag, n, x, user)
  fx = cos(x);
 
 Symmetric f(a)
          1       2       3       4
 1  -0.5420 -0.6612 -0.0261  0.1580
 2           0.2306 -0.3396 -0.0261
 3                   0.2306 -0.6612
 4                          -0.5420

ifail =

                    0



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–2013