NAG Toolbox: nag_matop_real_symm_matrix_fun (f01ef)

Purpose

Syntax

Description

References

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 $\max \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 $\max \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

   $\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

Further Comments

Example

Open in the MATLAB editor: f01ef_example

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