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













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 

 Level of display 

 Tolerance for blocking Schur form  Positive scalar. The default is 
 Termination tolerance for evaluating the Taylor series of diagonal blocks  Positive scalar. The default is 
 Maximum number of Taylor series terms  Positive integer. The default is 
 When computing a logarithm, maximum number of square roots computed in inverse scaling and squaring method.  Positive integer. The default is 
 Specifies the ordering of the Schur form  A vector of length 
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 ofF
might still be accurate.
[F,exitflag,output] = funm(...)
returns
a structure output
with the following fields:
Field  Description 

 Vector for which 
 Cell array for which the 
 Ordering of the Schur form, as passed to 
 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 3by3 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 SchurParlett algorithm for computing matrix functions,” SIAM J. Matrix Anal. Appl., Vol. 25, Number 2, pp. 464485, 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, TwentyFive Years Later” SIAM Review 20, Vol. 45, Number 1, pp. 147, 2003.