syms

Create symbolic scalar variables, functions, and matrix variables

Syntax

syms var1 ... varN

syms var1 ... varN [n1 ... nM]

syms var1 ... varN n

syms ___ set

syms f(var1,...,varN)

syms f(var1,...,varN) [n1 ... nM]

syms f(var1,...,varN) n

syms var1 ... varN [nrow ncol] matrix

syms var1 ... varN n matrix

syms(symArray)

syms

S = syms

Description

syms var1 ... varN creates symbolic scalar variables var1 ... varN of type sym. Separate different variables by spaces. This syntax clears all previous definitions of var1 ... varN. Since R2018b, syms also clears all assumptions from the variables.

syms var1 ... varN [n1 ... nM] creates arrays of symbolic scalar variables var1 ... varN, where each array has the size n1-by-...-by-nM and contains automatically generated symbolic scalar variables as its elements. For brevity, an array of symbolic scalar variables is also called a symbolic array. For example, syms a [1 3] creates the symbolic array a = [a1 a2 a3] and the symbolic scalar variables a1, a2, and a3 in the MATLAB^® workspace. For multidimensional arrays, these elements have the prefix a followed by the element’s index using _ as a delimiter, such as a1_3_2.

syms var1 ... varN n creates n-by-n matrices of symbolic scalar variables filled with automatically generated elements. For brevity, a matrix of symbolic scalar variables is also called a symbolic matrix.

syms ___ set sets the assumption that the created symbolic scalar variables belong to set, and clears other assumptions. Here, set can be real, positive, integer, or rational. You can also combine multiple assumptions using spaces. For example, syms x positive rational creates a symbolic scalar variable x with a positive rational value.

syms f(var1,...,varN) creates the symbolic function f of type symfun and the symbolic scalar variables var1,...,varN, which represent the input arguments of f. This syntax clears all previous definitions of var1,...,varN including symbolic assumptions. You can create multiple symbolic functions in one call. For example, syms f(x) g(t) creates two symbolic functions (f and g) and two symbolic scalar variables (x and t).

syms f(var1,...,varN) [n1 ... nM] creates an n1-by-...-by-nM symbolic array with automatically generated symbolic functions as its elements. This syntax also generates the symbolic scalar variables var1,...,varN that represent the input arguments of f. For example, syms f(x) [1 2] creates the symbolic array f(x) = [f1(x) f2(x)], the symbolic functions f1(x) and f2(x), and the symbolic scalar variable x in the MATLAB workspace. For multidimensional arrays, these elements have the prefix f followed by the element’s index using _ as a delimiter, such as f1_3_2.

syms f(var1,...,varN) n creates an n-by-n matrix of symbolic functions filled with automatically generated elements.

syms var1 ... varN [nrow ncol] matrix creates symbolic matrix variables var1 ... varN of type symmatrix, where each symbolic matrix variable has the size nrow-by-ncol. (since R2021a)

syms var1 ... varN n matrix creates n-by-n symbolic matrix variables. (since R2021a)

syms(symArray) creates the symbolic scalar variables and functions contained in symArray, where symArray is either a vector of symbolic scalar variables or a cell array of symbolic scalar variables and functions. This syntax clears all previous definitions of variables specified in symArray including symbolic assumptions. Use this syntax only when such an array is returned by another function, such as solve or symReadSSCVariables.

syms lists the names of all symbolic scalar variables, functions, and arrays in the MATLAB workspace.

S = syms returns a cell array of the names of all symbolic scalar variables, functions, and arrays.

Examples

Create Symbolic Scalar Variables

Create symbolic scalar variables x and y.

syms x y
x

x = $$x$$

y

y = $$y$$

Create Vector of Symbolic Scalar Variables

Create a 1-by-4 vector of symbolic scalar variables a with the automatically generated elements $$a_1,\dots ,a_4$$. This command also creates the symbolic scalar variables a1, ..., a4 in the MATLAB workspace.

syms a [1 4]
a

a = $$\left(\begin{array}{cccc}{a}_1& a_2& a_3& a_4\end{array}\right)$$

whos

  Name      Size            Bytes  Class    Attributes

  a         1x4                 8  sym                
  a1        1x1                 8  sym                
  a2        1x1                 8  sym                
  a3        1x1                 8  sym                
  a4        1x1                 8  sym                

You can change the naming format of the generated elements by using a format character vector. Declare the symbolic scalar variables by enclosing each variable name in single quotes. syms replaces %d in the format character vector with the index of the element to generate the element names.

syms 'p_a%d' 'p_b%d' [1 4]
p_a

p_a = $$\left(\begin{array}{cccc}{p}_{\mathrm{a1}}& p_{\mathrm{a2}}& p_{\mathrm{a3}}& p_{\mathrm{a4}}\end{array}\right)$$

p_b

p_b = $$\left(\begin{array}{cccc}{p}_{\mathrm{b1}}& p_{\mathrm{b2}}& p_{\mathrm{b3}}& p_{\mathrm{b4}}\end{array}\right)$$

Create Matrix of Symbolic Scalar Variables

Create a 3-by-4 matrix of symbolic scalar variables with automatically generated elements. The elements are of the form $$A_{i,j}$$, which generates the symbolic matrix variables $$A_{1,1},\dots ,A_{3,4}$$.

syms A [3 4]
A

A = 
$$\left(\begin{array}{cccc}{A}_{1,1}& A_{1,2}& A_{1,3}& A_{1,4}\\ A_{2,1}& A_{2,2}& A_{2,3}& A_{2,4}\\ A_{3,1}& A_{3,2}& A_{3,3}& A_{3,4}\end{array}\right)$$

Set Assumptions While Creating Variables

Create symbolic scalar variables x and y, and assume that they are integers.

syms x y integer

Create another scalar variable z, and assume that it has a positive rational value.

syms z positive rational

Check assumptions.

assumptions

ans = $$\left(\begin{array}{cccc}x\in \mathbb{Z}& y\in \mathbb{Z}& z\in \mathbb{Q}& 0<z\end{array}\right)$$

Alternatively, check assumptions on each variable. For example, check assumptions set on the variable x.

assumptions(x)

ans = $$x\in \mathbb{Z}$$

Clear assumptions on x, y, and z.

assume([x y z],'clear')
assumptions

 
ans =
 
Empty sym: 1-by-0
 

Create a 1-by-3 symbolic array a and assume that the array elements have real values.

syms a [1 3] real
assumptions

ans = $$\left(\begin{array}{ccc}{a}_1\in \mathbb{R}& a_2\in \mathbb{R}& a_3\in \mathbb{R}\end{array}\right)$$

Create Symbolic Functions

Create symbolic functions with one and two arguments.

syms s(t) f(x,y)

Both s and f are abstract symbolic functions. They do not have symbolic expressions assigned to them, so the bodies of these functions are s(t) and f(x,y), respectively.

Specify the following formula for f.

f(x,y) = x + 2*y

f(x, y) = $$x+2\hspace{0.17em}y$$

Compute the function value at the point x = 1 and y = 2.

f(1,2)

ans = $$5$$

Create Symbolic Functions with Matrices as Formulas

Create a symbolic function and specify its formula by using a matrix of symbolic scalar variables.

syms x
M = [x x^3; x^2 x^4];
f(x) = M

f(x) = 
$$\left(\begin{array}{cc}x& x^3\\ x^2& x^4\end{array}\right)$$

Compute the function value at the point x = 2:

f(2)

ans = 
$$\left(\begin{array}{cc}2& 8\\ 4& 16\end{array}\right)$$

Compute the value of this function for x = [1 2 3; 4 5 6]. The result is a cell array of symbolic matrices.

xVal = [1 2 3; 4 5 6];
y = f(xVal)

y=2×2 cell array
    {2x3 sym}    {2x3 sym}
    {2x3 sym}    {2x3 sym}

Access the contents of a cell in the cell array by using braces.

y{1}

ans = 
$$\left(\begin{array}{ccc}1& 2& 3\\ 4& 5& 6\end{array}\right)$$

Create Symbolic Matrices as Functions of Two Variables

Create a 2-by-2 symbolic matrix with automatically generated symbolic functions as its elements.

syms f(x,y) 2
f

f(x, y) = 
$$\left(\begin{array}{cc}{f}_{1,1}\left(x,y\right)& f_{1,2}\left(x,y\right)\\ f_{2,1}\left(x,y\right)& f_{2,2}\left(x,y\right)\end{array}\right)$$

Assign symbolic expressions to the symbolic functions f1_1(x,y) and f2_2(x,y). These functions are displayed as $$f_{1,1}(x,y)$$ and $$f_{2,2}(x,y)$$ in the Live Editor. When you assign these expressions, the symbolic matrix f still contains the initial symbolic functions in its elements.

f1_1(x,y) = 2*x;
f2_2(x,y) = x - y;
f

f(x, y) = 
$$\left(\begin{array}{cc}{f}_{1,1}\left(x,y\right)& f_{1,2}\left(x,y\right)\\ f_{2,1}\left(x,y\right)& f_{2,2}\left(x,y\right)\end{array}\right)$$

Substitute the expressions assigned to f1_1(x,y) and f2_2(x,y) by using the subs function.

A = subs(f)

A(x, y) = 
$$\left(\begin{array}{cc}2\hspace{0.17em}x& f_{1,2}\left(x,y\right)\\ f_{2,1}\left(x,y\right)& x-y\end{array}\right)$$

Evaluate the value of the symbolic matrix A, which contains the substituted expressions at x = 2 and y = 3.

A(2,3)

ans = 
$$\left(\begin{array}{cc}4& f_{1,2}\left(2,3\right)\\ f_{2,1}\left(2,3\right)& -1\end{array}\right)$$

Create Symbolic Matrix Variables

Since R2021a

Create two symbolic matrix variables with size 2-by-3. Nonscalar symbolic matrix variables are displayed as bold characters in the Live Editor and Command Window.

syms A B [2 3] matrix
A

A = $$A$$

B

B = $$B$$

Add the two matrices. The result is represented by the matrix notation $$\text{A}+\text{B}$$.

X = A + B

X = $$A+B$$

The data type of X is symmatrix.

class(X)

ans = 
'symmatrix'

Convert the symbolic matrix variable X to a matrix of symbolic scalar variables Y. The result is denoted by the sum of the matrix components.

Y = symmatrix2sym(X)

Y = 
$$\left(\begin{array}{ccc}{A}_{1,1}+B_{1,1}& A_{1,2}+B_{1,2}& A_{1,3}+B_{1,3}\\ A_{2,1}+B_{2,1}& A_{2,2}+B_{2,2}& A_{2,3}+B_{2,3}\end{array}\right)$$

The data type of Y is sym.

class(Y)

ans = 
'sym'

Show that the converted result in Y is equal to the sum of two matrices of symbolic scalar variables.

syms A B [2 3]
Y2 = A + B

Y2 = 
$$\left(\begin{array}{ccc}{A}_{1,1}+B_{1,1}& A_{1,2}+B_{1,2}& A_{1,3}+B_{1,3}\\ A_{2,1}+B_{2,1}& A_{2,2}+B_{2,2}& A_{2,3}+B_{2,3}\end{array}\right)$$

isequal(Y,Y2)

ans = logical
   1

Commutation Relation of Symbolic Matrix Variables

Since R2021a

Symbolic matrix variables represent matrices, vectors, and scalars in compact matrix notation. When representing nonscalars, these variables are noncommutative. When mathematical formulas involve matrices and vectors, writing them using symbolic matrix variables is more concise and clear than writing them componentwise.

Create two symbolic matrix variables.

syms A B [2 2] matrix

Check the commutation relation for multiplication between two symbolic matrix variables.

A*B - B*A

ans = $$A\hspace{0.17em}B-B\hspace{0.17em}A$$

isequal(A*B,B*A)

ans = logical
   0

Check the commutation relation for addition between two symbolic matrix variables.

isequal(A+B,B+A)

ans = logical
   1

Find Hessian Matrix

Since R2021a

Create 3-by-3 and 3-by-1 symbolic matrix variables.

syms A 3 matrix
syms X [3 1] matrix

Find the Hessian matrix of $${\text{X}}^T\text{A}\text{X}$$. Derived equations involving symbolic matrix variables are displayed in typeset as they would be in textbooks.

f = X.'*A*X

f = $$X^{\mathrm{T}}\hspace{0.17em}A\hspace{0.17em}X$$

H = diff(f,X,X.')

H = $$A^{\mathrm{T}}+A$$

Create Symbolic Objects from Returned Symbolic Array

Certain functions, such as solve and symReadSSCVariables, can return a vector of symbolic scalar variables or a cell array of symbolic scalar variables and functions. These variables or functions do not automatically appear in the MATLAB workspace. Create these variables or functions from the vector or cell array by using syms.

Solve the equation sin(x) == 1 by using solve. The parameter k in the solution does not appear in the MATLAB workspace.

syms x
eqn = sin(x) == 1;
[sol,parameter,condition] = solve(eqn,x,'ReturnConditions',true);
parameter

parameter = $$k$$

Create the parameter k by using syms. The parameter k now appears in the MATLAB workspace.

syms(parameter)

Similarly, use syms to create the symbolic objects contained in a vector or cell array. Examples of functions that return a cell array of symbolic objects are symReadSSCVariables and symReadSSCParameters.

List All Symbolic Scalar Variables, Functions, and Arrays

Create some symbolic scalar variables, functions, and arrays.

syms a f(x)
syms A [2 2]

Display a list of all symbolic scalar variables, functions, and arrays that currently exist in the MATLAB workspace by using syms.

syms

Your symbolic variables are:

A     A1_1  A1_2  A2_1  A2_2  a     f     x                                   

Instead of displaying a list, return a cell array by providing an output to syms.

S = syms

S = 8x1 cell
    {'A'   }
    {'A1_1'}
    {'A1_2'}
    {'A2_1'}
    {'A2_2'}
    {'a'   }
    {'f'   }
    {'x'   }

Delete All Symbolic Variables, Functions, or Arrays

Create several symbolic objects.

syms a b c f(x)

Return all symbolic objects as a cell array by using the syms function. Use the cellfun function to delete all symbolic objects in the cell array symObj.

symObj = syms;
cellfun(@clear,symObj)

Check that you deleted all symbolic objects by calling syms. The output is empty, meaning no symbolic objects exist in the MATLAB workspace.

syms

Input Arguments

var1 ... varN — Symbolic scalar variables, matrices, arrays, or matrix variables

valid variable names separated by spaces

Symbolic scalar variables, matrices, arrays, or matrix variables (since R2021a), specified as valid variable names separated by spaces. Each variable name must begin with a letter and can contain only alphanumeric characters and underscores. To verify that the name is a valid variable name, use isvarname.

Example: x y123 z_1

[n1 ... nM] — Vector, matrix, or array dimensions of symbolic scalar variables

vector of integers

Vector, matrix, or array dimensions of symbolic scalar variables, specified as a vector of integers. As a shortcut, you can create a square matrix by specifying only one integer. For example, syms x 3 creates a square 3-by-3 matrix of symbolic scalar variables.

Example: [2 3], [2,3]

[nrow ncol] — Matrix dimensions of symbolic matrix variables

vector of integers

Matrix dimensions of symbolic matrix variables, specified as a vector of integers. As a shortcut, you can create a square symbolic matrix variable by specifying only one integer. For example, syms x 3 matrix creates a square 3-by-3 symbolic matrix variable.

Example: [2 3], [2,3]

set — Assumptions on symbolic scalar variables

real | positive | integer | rational

Assumptions on symbolic scalar variables, specified as real, positive, integer, or rational.

You can combine multiple assumptions using spaces. For example, syms x positive rational creates a symbolic scalar variable x with a positive rational value.

Example: rational

f(var1,...,varN) — Symbolic function with its input arguments

expression with parentheses

Symbolic function with its input arguments, specified as an expression with parentheses. The function name f and the variable names var1...varN must be valid variable names. That is, they must begin with a letter and can contain only alphanumeric characters and underscores. To verify that the name is a valid variable name, use isvarname.

Example: s(t), f(x,y)

symArray — Symbolic scalar variables and functions

vector of symbolic scalar variables | cell array of symbolic scalar variables and functions

Symbolic scalar variables or functions, specified as a vector of symbolic scalar variables or a cell array of symbolic scalar variables and functions. Such a vector or array is typically the output of another function, such as solve or symReadSSCVariables.

Output Arguments

S — Names of all symbolic scalar variables, functions, and arrays

cell array of character vectors

Names of all symbolic scalar variables, functions, and arrays in the MATLAB workspace, returned as a cell array of character vectors.

Limitations

• Using Symbolic Math Toolbox™, you can create symbolic functions that depend on symbolic scalar variables as parameters. However, symbolic matrix variables cannot be parameter-dependent. For example, the command syms A(x) [3 2] matrix currently errors.

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

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

Tips

• syms is a shortcut for sym. This shortcut lets you create several symbolic scalar variables in one function call. Alternatively, you can use sym and create each variable separately. However, when you create variables using sym, any existing assumptions on the created variables are retained. You can also use symfun to create symbolic functions.

• In functions and scripts, do not use syms to create symbolic scalar variables with the same names as MATLAB functions. For these names, MATLAB does not create symbolic scalar variables, but keeps the names assigned to the MATLAB functions. If you want to create a symbolic scalar variable with the same name as a MATLAB function inside a function or a script, use sym instead. For example, use alpha = sym('alpha').

• Avoid using syms within functions, since it generates variables without direct output assignment. Using syms within functions can create side effects and other unexpected behaviors. Instead, use sym with left-side output assignment within functions, such as t = sym('t'). For more details, see Choose syms or sym Function.

• The following variable names are invalid with syms: integer, real, rational, positive, and clear. To create symbolic scalar variables with these names, use sym. For example, real = sym('real').

• clear x does not clear the symbolic object of its assumptions, such as real, positive, or any assumptions set by assume, sym, or syms. To remove assumptions, use one of these options:

  • syms x clears all assumptions from x.

  • assume(x,'clear') clears all assumptions from x.

  • clear all clears all objects in the MATLAB workspace and resets the symbolic engine.

  • assume and assumeAlso provide more flexibility for setting assumptions on symbolic scalar variables.

• When you replace one or more elements of a numeric vector or matrix with a symbolic number, MATLAB converts that number to a double-precision number.

  A = eye(3);
  A(1,1) = sym(pi)

  A =
      3.1416         0         0
           0    1.0000         0
           0         0    1.0000

  You cannot replace elements of a numeric vector or matrix with a symbolic scalar variable, expression, or function because these elements cannot be converted to double-precision numbers. For example, syms a; A(1,1) = a throws an error.

Compatibility Considerations

syms clears assumptions

Behavior changed in R2018b

syms now clears any assumptions on the symbolic scalar variables that it creates. For example,

syms x real
assume(x <= 5);
assumptions(x)

ans =
 
x <= 5

syms x
assumptions(x)

ans =
 
Empty sym: 1-by-0

To retain existing assumptions on a cleared variable, recreate it using sym instead of syms. For example,

syms x real
assume(x <= 5);
clear x
x = sym('x');
assumptions(x)

ans =
 
x <= 5

syms will no longer support clear option

Warns starting in R2018b

The syntaxes syms x clear and the equivalent syms('x','clear') now warn that they will be removed in a future release.

In previous releases, both syntaxes cleared all assumptions applied to x. To update your code, call syms and specify the symbolic scalar variables whose assumptions you want to clear. For example, syms x clears all assumptions applied to x.