# funm

General matrix function

## Syntax

``F = funm(A,f)``

## Description

example

````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, call`funm` 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

collapse all

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

Function, specified as a symbolic function or expression.

## Output Arguments

collapse all

Resulting function, returned as a symbolic matrix.

collapse all

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