funm

General matrix function

Syntax

F = funm(A,f)

Description

F = funm(A,f) computes the function f(A) for the square matrix A. For details, see Matrix Function.

Examples

Matrix Cube Root

Find matrix B, such that B3 = A, where A is a 3-by-3 identity matrix.

To solve B3 = A, compute the cube root of the matrix A using the funm function. Create the symbolic function f(x) = x^(1/3) and use it as the second argument for funm. The cube root of an identity matrix is the identity matrix itself.

A = sym(eye(3))

syms f(x)
f(x) = x^(1/3);

B = funm(A,f)

A =
[ 1, 0, 0]
[ 0, 1, 0]
[ 0, 0, 1]
 
B =
[ 1, 0, 0]
[ 0, 1, 0]
[ 0, 0, 1]

Replace one of the 0 elements of matrix A with 1 and compute the matrix cube root again.

A(1,2) = 1
B = funm(A,f)

A =
[ 1, 1, 0]
[ 0, 1, 0]
[ 0, 0, 1]

B =
[ 1, 1/3, 0]
[ 0,   1, 0]
[ 0,   0, 1]

Now, compute the cube root of the upper triangular matrix.

A(1:2,2:3) = 1
B = funm(A,f)

A =
[ 1, 1, 1]
[ 0, 1, 1]
[ 0, 0, 1]

B =
[ 1, 1/3, 2/9]
[ 0,   1, 1/3]
[ 0,   0,   1]

Verify that B3 = A.

B^3

ans =
[ 1, 1, 1]
[ 0, 1, 1]
[ 0, 0, 1]

Matrix Lambert W Function

Find the matrix Lambert W function.

First, create a 3-by-3 matrix A using variable-precision arithmetic with five digit accuracy. In this example, using variable-precision arithmetic instead of exact symbolic numbers lets you speed up computations and decrease memory usage. Using only five digits helps the result to fit on screen.

savedefault = digits(5);
A = vpa(magic(3))

A =
[ 8.0, 1.0, 6.0]
[ 3.0, 5.0, 7.0]
[ 4.0, 9.0, 2.0]

Create the symbolic function f(x) = lambertw(x).

syms f(x)
f(x) = lambertw(x);

To find the Lambert W function (W0 branch) in a matrix sense, callfunm using f(x) as its second argument.

W0 = funm(A,f)

W0 =
[  1.5335 + 0.053465i, 0.11432 + 0.47579i, 0.36208 - 0.52925i]
[ 0.21343 + 0.073771i,  1.3849 + 0.65649i, 0.41164 - 0.73026i]
[  0.26298 - 0.12724i,  0.51074 - 1.1323i,   1.2362 + 1.2595i]

Verify that this result is a solution of the matrix equation A = W0·eW0 within the specified accuracy.

W0*expm(W0)

ans =
[               8.0, 1.0 - 5.6843e-13i, 6.0 + 1.1369e-13i]
[ 3.0 - 2.2737e-13i, 5.0 - 2.8422e-14i, 7.0 - 4.1211e-13i]
[ 4.0 - 2.2737e-13i, 9.0 - 9.9476e-14i, 2.0 + 1.4779e-12i]

Now, create the symbolic function f(x) representing the branch W-1 of the Lambert W function.

f(x) = lambertw(-1,x);

Find the W-1 branch for the matrix A.

Wm1 = funm(A,f)

Wm1 =
[   0.40925 - 4.7154i, 0.54204 + 0.5947i, 0.13764 - 0.80906i]
[ 0.38028 + 0.033194i, 0.65189 - 3.8732i, 0.056763 - 1.0898i]
[   0.2994 - 0.24756i, - 0.105 - 1.6513i,  0.89453 - 3.0309i]

Verify that this result is the solution of the matrix equation A = Wm1·eWm1 within the specified accuracy.

Wm1*expm(Wm1)

ans =
[ 8.0 - 8.3844e-13i,  1.0 - 3.979e-13i, 6.0 - 9.0949e-13i]
[ 3.0 - 9.6634e-13i,  5.0 + 1.684e-12i, 7.0 + 4.5475e-13i]
[ 4.0 - 1.3642e-12i, 9.0 + 1.6698e-12i, 2.0 + 1.7053e-13i]

Matrix Exponential, Logarithm, and Square Root

You can use funm with appropriate second arguments to find matrix exponential, logarithm, and square root. However, the more efficient approach is to use the functions expm, logm, and sqrtm for this task.

Create this square matrix and find its exponential, logarithm, and square root.

syms x
A = [1 -1; 0 x]
expA = expm(A)
logA = logm(A)
sqrtA = sqrtm(A)

A =
[ 1, -1]
[ 0,  x]
 
expA =
[ exp(1), (exp(1) - exp(x))/(x - 1)]
[      0,                    exp(x)]
 
logA =
[ 0, -log(x)/(x - 1)]
[ 0,          log(x)]
 
sqrtA =
[ 1, 1/(x - 1) - x^(1/2)/(x - 1)]
[ 0,                     x^(1/2)]

Find the matrix exponential, logarithm, and square root of A using funm. Use the symbolic expressions exp(x), log(x), and sqrt(x) as the second argument of funm. The results are identical.

expA = funm(A,exp(x))
logA = funm(A,log(x))
sqrtA = funm(A,sqrt(x))

expA =
[ exp(1), exp(1)/(x - 1) - exp(x)/(x - 1)]
[      0,                          exp(x)]
 
logA =
[ 0, -log(x)/(x - 1)]
[ 0,          log(x)]
 
sqrtA =
[ 1, 1/(x - 1) - x^(1/2)/(x - 1)]
[ 0,                     x^(1/2)]

Input Arguments

A — Input matrix

square matrix

Input matrix, specified as a square symbolic or numeric matrix.

f — Function

symbolic function | symbolic expression

Function, specified as a symbolic function or expression.

Output Arguments

F — Resulting matrix

symbolic matrix

Resulting function, returned as a symbolic matrix.

More About

Matrix Function

Matrix function is a scalar function that maps one matrix to another.

Suppose, f(x), where x is a scalar, has a Taylor series expansion. Then the matrix function f(A), where A is a matrix, is defined by the Taylor series of f(A), with addition and multiplication performed in the matrix sense.

If A can be represented as A = P·D·P-1, where D is a diagonal matrix, such that

$$D=\left(\begin{array}{ccc}{d}_1& \cdots & 0\\ ⋮& \ddots & ⋮\\ 0& \cdots & d_n\end{array}\right)$$

then the matrix function f(A) can be computed as follows:

$$f\left(A\right)=P\cdot \left(\begin{array}{ccc}f\left(d_1\right)& \cdots & 0\\ ⋮& \ddots & ⋮\\ 0& \cdots & f\left(d_n\right)\end{array}\right)\cdot P^{-1}$$

Non-diagonalizable matrices can be represented as A = P·J·P-1, where J is a Jordan form of the matrix A. Then, the matrix function f(A) can be computed by using the following definition on each Jordan block:

$$f\left(\left(\begin{array}{ccccc}\lambda & 1& 0& \cdots & 0\\ 0& \ddots & \ddots & \ddots & ⋮\\ ⋮& \ddots & \ddots & \ddots & 0\\ ⋮& \ddots & \ddots & \ddots & 1\\ 0& \cdots & \cdots & 0& \lambda \end{array}\right)\right)=\left(\begin{array}{ccccc}\frac{f\left(\lambda \right)}{0!}& \frac{f^{\prime }\left(\lambda \right)}{1!}& \frac{f^{″}\left(\lambda \right)}{2!}& \cdots & \frac{f^{\left(n-1\right)}\left(\lambda \right)}{\left(n-1\right)!}\\ 0& \ddots & \ddots & \ddots & ⋮\\ ⋮& \ddots & \ddots & \ddots & \frac{f^{″}\left(\lambda \right)}{2!}\\ ⋮& \ddots & \ddots & \ddots & \frac{f^{\prime }\left(\lambda \right)}{1!}\\ 0& \cdots & \cdots & 0& \frac{f\left(\lambda \right)}{0!}\end{array}\right)$$

Tips

• For compatibility with the MATLAB^® funm function, funm accepts the following arguments:

  • Function handles such as @exp and @sin, as its second input argument.

  • The options input argument, such as funm(A,f,options).

  • Additional input arguments of the function f, such as funm(A,f,options,p1,p2,...)

  • The exitflag output argument, such as [F,exitflag] = funm(A,f). Here, exitflag is 1 only if the funm function call errors, for example, if it encounters a division by zero. Otherwise, exitflag is 0.

  For more details and a list of all acceptable function handles, see the MATLAB funm function.

• If the input matrix A is numeric (not a symbolic object) and the second argument f is a function handle, then the funm call invokes the MATLAB funm function.

Version History

Introduced in R2014b