f01 Chapter Contents
f01 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_matop_real_symm_matrix_fun (f01efc)

## 1  Purpose

nag_matop_real_symm_matrix_fun (f01efc) 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.

## 2  Specification

 #include #include
void  nag_matop_real_symm_matrix_fun (Nag_OrderType order, Nag_UploType uplo, Integer n, double a[], Integer pda,
 void (*f)(Integer *flag, Integer n, const double x[], double fx[], Nag_Comm *comm),
Nag_Comm *comm, Integer *flag, NagError *fail)

## 3  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.

## 4  References

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

## 5  Arguments

1:     orderNag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or $\mathrm{Nag_ColMajor}$.
2:     uploNag_UploTypeInput
On entry: if ${\mathbf{uplo}}=\mathrm{Nag_Upper}$, the upper triangle of the matrix $A$ is stored.
If ${\mathbf{uplo}}=\mathrm{Nag_Lower}$, the lower triangle of the matrix $A$ is stored.
Constraint: ${\mathbf{uplo}}=\mathrm{Nag_Upper}$ or $\mathrm{Nag_Lower}$.
3:     nIntegerInput
On entry: $n$, the order of the matrix $A$.
Constraint: ${\mathbf{n}}\ge 0$.
4:     a[$\mathit{dim}$]doubleInput/Output
Note: the dimension, dim, of the array a must be at least ${\mathbf{pda}}×{\mathbf{n}}$.
On entry: the $n$ by $n$ symmetric matrix $A$.
If ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${A}_{ij}$ is stored in ${\mathbf{a}}\left[\left(j-1\right)×{\mathbf{pda}}+i-1\right]$.
If ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${A}_{ij}$ is stored in ${\mathbf{a}}\left[\left(i-1\right)×{\mathbf{pda}}+j-1\right]$.
If ${\mathbf{uplo}}=\mathrm{Nag_Upper}$, the upper triangular part of $A$ must be stored and the elements of the array below the diagonal are not referenced.
If ${\mathbf{uplo}}=\mathrm{Nag_Lower}$, the lower triangular part of $A$ must be stored and the elements of the array above the diagonal are not referenced.
On exit: the upper or lower triangular part of the $n$ by $n$ matrix function, $f\left(A\right)$.
5:     pdaIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) of the matrix $A$ in the array a.
Constraint: ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
6:     ffunction, supplied by the userExternal Function
The function f evaluates $f\left({z}_{i}\right)$ at a number of points ${z}_{i}$.
The specification of f is:
 void f (Integer *flag, Integer n, const double x[], double fx[], Nag_Comm *comm)
1:     flagInteger *Input/Output
On entry: flag will be zero.
On exit: flag 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 flag is returned as nonzero then nag_matop_real_symm_matrix_fun (f01efc) will terminate the computation, with ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_USER_STOP.
2:     nIntegerInput
On entry: $n$, the number of function values required.
3:     x[n]const doubleInput
On entry: the $n$ points ${x}_{1},{x}_{2},\dots ,{x}_{n}$ at which the function $f$ is to be evaluated.
4:     fx[n]doubleOutput
On exit: the $n$ function values. ${\mathbf{fx}}\left[\mathit{i}-1\right]$ should return the value $f\left({x}_{\mathit{i}}\right)$, for $\mathit{i}=1,2,\dots ,n$.
5:     commNag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to f.
userdouble *
iuserInteger *
pPointer
The type Pointer will be void *. Before calling nag_matop_real_symm_matrix_fun (f01efc) you may allocate memory and initialize these pointers with various quantities for use by f when called from nag_matop_real_symm_matrix_fun (f01efc) (see Section 3.2.1.1 in the Essential Introduction).
7:     commNag_Comm *Communication Structure
The NAG communication argument (see Section 3.2.1.1 in the Essential Introduction).
8:     flagInteger *Output
On exit: ${\mathbf{flag}}=0$, unless you have set flag nonzero inside f, in which case flag will be the value you set and fail will be set to ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_USER_STOP.
9:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
NE_CONVERGENCE
The computation of the spectral factorization failed to converge.
NE_INT
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 0$.
NE_INT_2
On entry, ${\mathbf{pda}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pda}}\ge {\mathbf{n}}$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_USER_STOP
flag was set to a nonzero value in f.

## 7  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.

## 8  Parallelism and Performance

nag_matop_real_symm_matrix_fun (f01efc) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_matop_real_symm_matrix_fun (f01efc) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

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 (f01ffc) can be used to find the matrix function $f\left(A\right)$ for a complex Hermitian matrix $A$.

## 10  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 .$

### 10.1  Program Text

Program Text (f01efce.c)

### 10.2  Program Data

Program Data (f01efce.d)

### 10.3  Program Results

Program Results (f01efce.r)