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\left(A\right)$, of a real symmetric $n$ by $n$ matrix $A$. $f\left(A\right)$ 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\left(A\right)$ is computed using a spectral factorization of $A$
 $A = Q D QT ,$
where $D$ is the diagonal matrix whose diagonal elements, ${d}_{i}$, are the eigenvalues of $A$, and $Q$ is an orthogonal matrix whose columns are the eigenvectors of $A$. $f\left(A\right)$ is then given by
 $fA = Q fD QT ,$
where $f\left(D\right)$ is the diagonal matrix whose $i$th diagonal element is $f\left({d}_{i}\right)$. See for example Section 4.5 of Higham (2008). $f\left({d}_{i}\right)$ 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:     $\mathrm{uplo}$ – string (length ≥ 1)
If ${\mathbf{uplo}}=\text{'U'}$, the upper triangle of the matrix $A$ is stored.
If ${\mathbf{uplo}}=\text{'L'}$, the lower triangle of the matrix $A$ is stored.
Constraint: ${\mathbf{uplo}}=\text{'U'}$ or $\text{'L'}$.
2:     $\mathrm{a}\left(\mathit{lda},:\right)$ – double array
The first dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array a must be at least ${\mathbf{n}}$.
The $n$ by $n$ symmetric matrix $A$.
• If ${\mathbf{uplo}}=\text{'U'}$, the upper triangular part of $a$ must be stored and the elements of the array below the diagonal are not referenced.
• If ${\mathbf{uplo}}=\text{'L'}$, the lower triangular part of $a$ must be stored and the elements of the array above the diagonal are not referenced.
3:     $\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, fx, user] = f(iflag, n, x, user)

Input Parameters

1:     $\mathrm{iflag}$int64int32nag_int scalar
iflag will be zero.
2:     $\mathrm{n}$int64int32nag_int scalar
$n$, the number of function values required.
3:     $\mathrm{x}\left({\mathbf{n}}\right)$ – double array
The $n$ points ${x}_{1},{x}_{2},\dots ,{x}_{n}$ at which the function $f$ is to be evaluated.
4:     $\mathrm{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:     $\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(x\right)$; for instance $f\left(x\right)$ 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 ${\mathbf{ifail}}=-{\mathbf{6}}$.
2:     $\mathrm{fx}\left({\mathbf{n}}\right)$ – double array
The $n$ function values. ${\mathbf{fx}}\left(\mathit{i}\right)$ should return the value $f\left({x}_{\mathit{i}}\right)$, for $\mathit{i}=1,2,\dots ,n$.
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_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.

### Output Parameters

1:     $\mathrm{a}\left(\mathit{lda},:\right)$ – double array
The first dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array a will be ${\mathbf{n}}$.
If ${\mathbf{ifail}}={\mathbf{0}}$, the upper or lower triangular part of the $n$ by $n$ matrix function, $f\left(A\right)$.
2:     $\mathrm{user}$ – Any MATLAB object
3:     $\mathrm{iflag}$int64int32nag_int scalar
${\mathbf{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 ${\mathbf{ifail}}=-{\mathbf{6}}$.
4:     $\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}}>0$
The computation of the spectral factorization failed to converge.
${\mathbf{ifail}}=-1$
Constraint: ${\mathbf{uplo}}=\text{'L'}$ or $\text{'U'}$.
${\mathbf{ifail}}=-2$
Constraint: ${\mathbf{n}}\ge 0$.
${\mathbf{ifail}}=-3$
An internal error occurred when computing the spectral factorization. Please contact NAG.
${\mathbf{ifail}}=-4$
Constraint: $\mathit{lda}\ge {\mathbf{n}}$.
${\mathbf{ifail}}=-6$
iflag was set to a nonzero value in f.
${\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

Provided that $f\left(D\right)$ 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, and the double allocatable memory required is approximately $\left({\mathbf{n}}+\mathit{nb}+4\right)×{\mathbf{n}}$, where nb is the block size required by nag_lapack_dsyev (f08fa).
The cost of the algorithm is $O\left({n}^{3}\right)$ plus the cost of evaluating $f\left(D\right)$. If ${\stackrel{^}{\lambda }}_{i}$ is the $i$th computed eigenvalue of $A$, then the user-supplied function f will be asked to evaluate the function $f$ at $f\left({\stackrel{^}{\lambda }}_{i}\right)$, $i=1,2,\dots ,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\left(A\right)$ for a complex Hermitian matrix $A$.

## Example

This example finds the matrix cosine, $\mathrm{cos}\left(A\right)$, of the symmetric matrix
 $A= 1 2 3 4 2 1 2 3 3 2 1 2 4 3 2 1 .$
```function f01ef_example

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

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

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

% Display results
[ifail] = x04ca(uplo, 'n', cosa, 'Symmetric f(A) = cos(A)');

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

Symmetric f(A) = cos(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
```

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