Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

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$
${\mathbf{ifail}}=-4$
Constraint: $\mathit{lda}\ge {\mathbf{n}}$.
${\mathbf{ifail}}=-6$
iflag was set to a nonzero value in f.
${\mathbf{ifail}}=-99$
${\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.

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
```