symfunmatrix

Create symbolic matrix function

Since R2022a

Syntax

f = symfunmatrix(formula,inputs)

f = symfunmatrix(formula,inputs,[nrow ncol])

Description

f = symfunmatrix(formula,inputs) creates the symbolic matrix function f. The symbolic expression formula is the body of the function f that can be converted to the symmatrix data type. The variables in inputs are the input arguments of the function f.

• If the input arguments of function f are multiple variables, inputs must be a cell array of symbolic scalar and matrix variables.

• If the input argument of function f is a single variable, you can specify inputs as a symbolic scalar variable or a symbolic matrix variable.

f = symfunmatrix(formula,inputs,[nrow ncol]) also explicitly specifies the size of the evaluated symbolic matrix function f(var1,var2,...) as nrow-by-ncol for the inputs = {var1,var2,...}.

• If formula represents an unassigned abstract function, then f(var1,var2,...) has the size of nrow-by-ncol. For example:

  syms x 2 matrix;
  f = symfunmatrix('g(x)',{x},[3 4]);
  size(f(x))

  ans =
       3     4

• If formula represents a symbolic expression or a function with definition, then the size of f(var1,var2,...) follows the size of formula. For example:

  syms X Y 2 matrix;
  f = symfunmatrix(X*Y - Y*X,{X,Y},[3 3]);
  size(f(X,Y))

  ans =
       2     2

Examples

Define and Evaluate Symbolic Matrix Functions

Create two symbolic matrix variables with size 2-by-2.

syms X Y [2 2] matrix

Create a symbolic matrix function that represents the matrix operation $\mathit{XY}-\mathit{YX}$ by using symfunmatrix.

f = symfunmatrix(X*Y - Y*X,{X,Y})

f(X, Y) = $$X\hspace{0.17em}Y-Y\hspace{0.17em}X$$

Evaluate the function for the matrix values $\mathit{X}=\left[\begin{array}{cc}1& 2\\ 2& 2\end{array}\right]$ and $\mathit{Y}=\left[\begin{array}{cc}-2& 1\\ 0& 4\end{array}\right]$. The evaluated function is a symbolic matrix variable of data type symmatrix.

fEval = f([1 2; 2 2],[-2 1; 0 4])

fEval = 
$$\begin{array}{l}-{\Sigma }_1+{\Sigma }_2\\ \\ \mathrm{where}\\ \\ \mathrm{ }{\Sigma }_1=\left(\begin{array}{cc}0& -2\\ 8& 8\end{array}\right)\\ \\ \mathrm{ }{\Sigma }_2=\left(\begin{array}{cc}-2& 9\\ -4& 10\end{array}\right)\end{array}$$

class(fEval)

ans = 
'symmatrix'

Convert the evaluated function to the sym data type.

fSym = symmatrix2sym(fEval)

fSym = 
$$\left(\begin{array}{cc}-2& 11\\ -12& 2\end{array}\right)$$

Input Arguments

formula — Function body

symbolic expression | abstract function

Function body, specified as a symbolic expression that can be converted to the symmatrix data type or an abstract function.

Example: X*Y.'

inputs — Input argument or arguments of function

cell array of symbolic scalar and matrix variables | symbolic scalar variable | symbolic matrix variable

Input argument or arguments of a function, specified as a cell array of symbolic scalar and matrix variables, a symbolic scalar variable, or a symbolic matrix variable.

Example: {X,Y}, symmatrix('t',[2 3])

Data Types: cell | sym | symmatrix

[nrow ncol] — Dimensions of evaluated symbolic matrix function

vector of nonnegative integers

Dimensions of the evaluated symbolic matrix function, specified as a vector of nonnegative integers. As a shortcut, you can create a square symbolic matrix function by specifying only one integer.

Example: [2 3]

Output Arguments

f — Symbolic matrix function

symfunmatrix object

Symbolic matrix function, returned as a symfunmatrix object.

While the data type of the function f is symfunmatrix, the data type of the evaluated function, such as f([-2 3],[1 0]), is symmatrix.

Limitations

• To show all the functions in Symbolic Math Toolbox™ that accept symbolic matrix functions as input, use the command methods symfunmatrix.

Tips

• When evaluating a symbolic matrix function, you must substitute values that have the same size as the defined input arguments. For example, see Define and Evaluate Symbolic Matrix Functions. For comparison, this example returns an error:

  syms X [2 2] matrix
  syms f(X) [1 1] matrix keepargs
  f(ones(4))
  

Version History

Introduced in R2022a

R2023a: Specify inputs as a symbolic scalar variable or a symbolic matrix variable

When creating a symbolic matrix function with a single variable as its input argument, you can specify the inputs argument as a symbolic scalar variable or a symbolic matrix variable. For example, you can create a symbolic matrix function using:

syms X [4 5] matrix
f = symfunmatrix("f(X)",X,[1 1])

In previous releases, the inputs argument must be a cell array of symbolic scalar and matrix variables, even if function f has only one input argument.