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

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

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.

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced before R2006a