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_complex_herm_matrix_fun (f01ff)

 Contents

    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example

Purpose

nag_matop_complex_herm_matrix_fun (f01ff) computes the matrix function, fA, of a complex Hermitian n by n matrix A. fA must also be a complex Hermitian matrix.

Syntax

[a, user, iflag, ifail] = f01ff(uplo, a, f, 'n', n, 'user', user)
[a, user, iflag, ifail] = nag_matop_complex_herm_matrix_fun(uplo, a, f, 'n', n, 'user', user)

Description

fA is computed using a spectral factorization of A 
A = Q D QH ,  
where D is the real diagonal matrix whose diagonal elements, di, are the eigenvalues of A, Q is a unitary matrix whose columns are the eigenvectors of A and QH is the conjugate transpose of Q. fA is then given by
fA = Q fD QH ,  
where fD is the diagonal matrix whose ith diagonal element is fdi. See for example Section 4.5 of Higham (2008). fdi 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', the upper triangle of the matrix A is stored.
If uplo='L', the lower triangle of the matrix A is stored.
Constraint: uplo='U' or 'L'.
2:     alda: – complex array
The first dimension of the array a must be at least max1,n.
The second dimension of the array a must be at least n.
The n by n Hermitian matrix A.
  • If uplo='U', the upper triangular part of a must be stored and the elements of the array below the diagonal are not referenced.
  • If uplo='L', the lower triangular part of a 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 fzi at a number of points zi.
[iflag, fx, user] = f(iflag, n, x, user)

Input Parameters

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

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 fx; for instance fx may not be defined, or may be complex. If iflag is returned as nonzero then nag_matop_complex_herm_matrix_fun (f01ff) will terminate the computation, with ifail=-6.
2:     fxn – double array
The n function values. fxi should return the value fxi, for i=1,2,,n.
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: n0.
2:     user – Any MATLAB object
user is not used by nag_matop_complex_herm_matrix_fun (f01ff), 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:     alda: – complex array
The first dimension of the array a will be max1,n.
The second dimension of the array a will be n.
If ifail=0, the upper or lower triangular part of the n by n matrix function, fA.
2:     user – Any MATLAB object
3:     iflag int64int32nag_int scalar
iflag=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=-6.
4:     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>0
The computation of the spectral factorization failed to converge.
   ifail=-1
Constraint: uplo='L' or 'U'.
   ifail=-2
Constraint: n0.
   ifail=-3
An internal error occurred when computing the spectral factorization. Please contact NAG.
   ifail=-4
Constraint: ldan.
   ifail=-6
iflag was set to a nonzero value in f.
   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

Provided that fD 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 integer allocatable memory required is n, the double allocatable memory required is 4×n-2 and the complex allocatable memory required is approximately n+nb+1×n, where nb is the block size required by nag_lapack_zheev (f08fn).
The cost of the algorithm is On3 plus the cost of evaluating fD. If λ^i is the ith computed eigenvalue of A, then the user-supplied function f will be asked to evaluate the function f at fλ^i, for i=1,2,,n.
For further information on matrix functions, see Higham (2008).
nag_matop_real_symm_matrix_fun (f01ef) can be used to find the matrix function fA for a real symmetric matrix A.

Example

This example finds the matrix cosine, cosA, of the Hermitian matrix
A= 1 2+i 3+2i 4+3i 2-i 1 2+i 3+2i 3-2i 2-i 1 2+i 4-3i 3-2i 2-i 1 .  
function f01ff_example


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

uplo = 'u';
a = [ 1,  2 + 1i,  3 + 2i,  4 + 3i;
      0,  1 + 0i,  2 + 1i,  3 + 2i;
      0,       0,  1 + 0i,  2 + 1i;
      0,       0,       0,  1 + 0i];

% Compute f(a)
[cosa, user, iflag, ifail] = ...
f01ff(uplo, a, @f);

% Display results
[ifail] = x04da( ...
                 uplo, 'n', cosa, 'Hermitian f(A) = cos(A)');



function [iflag, fx, user] = f(iflag, n, x, user)
  fx = cos(x);
f01ff example results

 Hermitian f(A) = cos(A)
          1       2       3       4
 1   0.0904 -0.3377 -0.1009 -0.1092
     0.0000 -0.0273 -0.0594 -0.1586

 2           0.4265 -0.3139 -0.1009
             0.0000 -0.0273 -0.0594

 3                   0.4265 -0.3377
                     0.0000 -0.0273

 4                           0.0904
                             0.0000

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