MATLAB Function Reference Previous page   Next Page
funm

Evaluate general matrix function

Syntax

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 kth 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:

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

Example 2. The statements

produce the same results to within roundoff error as

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

where fun_expcos is the following M-file function.

Algorithm

The algorithm funm uses is described in [1].

See Also

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.


Previous page  functions fwrite Next page

© 1994-2005 The MathWorks, Inc.