Documentation

### This is machine translation

Mouseover text to see original. Click the button below to return to the English version of the page.

# funm

Evaluate general matrix function

## Syntax

```F = funm(A,fun) F = funm(A,fun,options) F = funm(A,fun,options,p1,p2,...) [F,exitflag] = funm(...) [F,exitflag,output] = funm(...) ```

## Description

`F = funm(A,fun)` evaluates the user-defined function `fun` at the square matrix argument `A`. `F = fun(x,k)` must accept a vector `x` and an integer `k`, and return a vector `f` of the same size of `x`, where `f(i)` is the `k`th derivative of the function `fun` evaluated at `x(i)`. The function represented by fun must have a Taylor series with an infinite radius of convergence, except for `fun = @log`, which is treated as a special case.

You can also use `funm` to evaluate the special functions listed in the following table at the matrix `A`.

Function

Syntax for Evaluating Function at Matrix A

`exp`

`funm(A, @exp)`

`log`

`funm(A, @log)`

`sin`

`funm(A, @sin)`

`cos`

`funm(A, @cos)`

`sinh`

`funm(A, @sinh)`

`cosh`

`funm(A, @cosh)`

For matrix square roots, use `sqrtm(A)` instead. For matrix exponentials, which of `expm(A)` or ```funm(A, @exp)``` is the more accurate depends on the matrix `A`.

The function represented by `fun` must have a Taylor series with an infinite radius of convergence. The exception is `@log`, which is treated as a special case. Parameterizing Functions explains how to provide additional parameters to the function `fun`, if necessary.

`F = funm(A,fun,options)` sets the algorithm's parameters to the values in the structure `options`.

The following table lists the fields of `options`.

Field

Description

Values

`options.Display`

Level of display

`'off'` (default), `'on'`, `'verbose'`

`options.TolBlk`

Tolerance for blocking Schur form

Positive scalar. The default is `0.1`.

`options.TolTay`

Termination tolerance for evaluating the Taylor series of diagonal blocks

Positive scalar. The default is `eps`.

`options.MaxTerms`

Maximum number of Taylor series terms

Positive integer. The default is `250`.

`options.MaxSqrt`

When computing a logarithm, maximum number of square roots computed in inverse scaling and squaring method.

Positive integer. The default is `100`.

`options.Ord`

Specifies the ordering of the Schur form `T`.

A vector of length `length(A)`. `options.Ord(i)` is the index of the block into which `T(i,i)` is placed. The default is `[]`.

`F = funm(A,fun,options,p1,p2,...)` passes extra inputs `p1,p2,...` to the function.

`[F,exitflag] = funm(...)` returns a scalar `exitflag` that describes the exit condition of `funm`. `exitflag` can have the following values:

• `0` — The algorithm was successful.

• `1` — One or more Taylor series evaluations did not converge, or, in the case of a logarithm, too many square roots are needed. However, the computed value of `F` might still be accurate.

`[F,exitflag,output] = funm(...)` returns a structure `output` with the following fields:

Field

Description

`output.terms`

Vector for which `output.terms(i)` is the number of Taylor series terms used when evaluating the ith block, or, in the case of the logarithm, the number of square roots of matrices of dimension greater than 2.

`output.ind`

Cell array for which the `(i,j)` block of the reordered Schur factor `T` is ```T(output.ind{i}, output.ind{j})```.

`output.ord`

Ordering of the Schur form, as passed to `ordschur`

`output.T`

Reordered Schur form

If the Schur form is diagonal then `output = struct('terms',ones(n,1),'ind',{1:n})`.

## Examples

### Example 1

The following command computes the matrix sine of the 3-by-3 magic matrix.

```F=funm(magic(3), @sin) F = -0.3850 1.0191 0.0162 0.6179 0.2168 -0.1844 0.4173 -0.5856 0.8185```

### Example 2

The statements

```S = funm(X,@sin); C = funm(X,@cos);```

produce the same results to within roundoff error as

```E = expm(i*X); C = real(E); S = imag(E); ```

In either case, the results satisfy `S*S+C*C = I`, where `I = eye(size(X))`.

### Example 3

To compute the function `exp(x) + cos(x)` at `A` with one call to `funm`, use

```F = funm(A,@fun_expcos) ```

where `fun_expcos` is the following function.

```function f = fun_expcos(x, k) % Return kth derivative of exp + cos at X. g = mod(ceil(k/2),2); if mod(k,2) f = exp(x) + sin(x)*(-1)^g; else f = exp(x) + cos(x)*(-1)^g; end ```

## Algorithms

The algorithm `funm` uses is described in .

## References

 Davies, P. I. and N. J. Higham, “A Schur-Parlett algorithm for computing matrix functions,” SIAM J. Matrix Anal. Appl., Vol. 25, Number 2, pp. 464-485, 2003.

 Golub, G. H. and C. F. Van Loan, Matrix Computation, Third Edition, Johns Hopkins University Press, 1996, p. 384.

 Moler, C. B. and C. F. Van Loan, “Nineteen Dubious Ways to Compute the Exponential of a Matrix, Twenty-Five Years Later” SIAM Review 20, Vol. 45, Number 1, pp. 1-47, 2003.