symfunmatrix

Create symbolic matrix function

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, which must be a cell array of symbolic scalar and matrix variables.

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\hspace{0.17em}{\Sigma }_2+{\Sigma }_2\hspace{0.17em}{\Sigma }_1\\ \\ \mathrm{where}\\ \\ \mathrm{ }{\Sigma }_1=\left(\begin{array}{cc}-2& 1\\ 0& 4\end{array}\right)\\ \\ \mathrm{ }{\Sigma }_2=\left(\begin{array}{cc}1& 2\\ 2& 2\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

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

Example: {X,Y}

Data Types: cell

[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

• Differentiation functions, such as divergence, curl, jacobian, and laplacian, currently do not accept symbolic matrix functions as input. To evaluate differentiation with respect to vectors and matrices, use the diff function instead.

• 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