MATLAB Function Reference
funm

Evaluate general matrix function

Syntax

• ```F = funm(A,fun)
```F = funm(A, fun, options)
```[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`.

Parameterizing Functions Called by Function Functions, in the online MATLAB Mathematics documentation, 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.TolBlk` Level of display `'off'` (default), `'on'`, `'verbose'` `options.TolTay` Tolerance for blocking Schur form Positive scalar. The default is `eps`. `options.MaxTerms` Maximum number of Tayor 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, 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. 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. `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 M-file 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
```

Algorithm

The algorithm `funm` uses is described in [1].

`expm`, `logm`, `sqrtm`, `function_handle` (`@`)

References

[1]  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.

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

[3]  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.

 functions fwrite