Main Content

syms

Create symbolic scalar variables and functions, and matrix variables and functions

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 f(var1,...,varN) [nrow ncol] matrix``
``syms f(var1,...,varN) [nrow ncol] matrix keepargs``
``syms f(var1,...,varN) n matrix``
``syms f(var1,...,varN) n matrix keepargs``
``syms(symArray)``
``syms``
``S = syms``

Description

example

````syms var1 ... varN` creates symbolic scalar variables `var1 ... varN` of type `sym`. Separate the different variables with spaces. This syntax clears all previous definitions of `var1 ... varN`.```

example

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

example

````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. Use this option in addition to any of the input argument combinations in previous syntaxes.```

example

````syms f(var1,...,varN)` creates the symbolic function `f` of type `symfun` and the symbolic scalar variables `var1,...,varN` of type `sym`, which represent the input arguments of `f`. This syntax clears all previous definitions of `var1,...,varN` including symbolic assumptions. The evaluated symbolic function `f(var1,...,varN)` is of type `sym`.```
````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` and `f2`, 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`.```

example

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

example

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

example

````syms var1 ... varN n matrix` creates `n`-by-`n` symbolic matrix variables.```
````syms f(var1,...,varN) [nrow ncol] matrix` creates the symbolic matrix function `f` of type `symfunmatrix` and the symbolic scalar variables `var1,...,varN` of type `sym`. The evaluated symbolic matrix function `f(var1,...,varN)` is of type `symmatrix` and has the size `nrow`-by-`ncol`. This syntax clears all previous definitions of `var1,...,varN` including symbolic assumptions.```

example

````syms f(var1,...,varN) [nrow ncol] matrix keepargs` keeps existing definitions of `var1,...,varN` in the workspace. If any of the variables `var1,...,varN` does not exist in the workspace, then this syntax creates them as symbolic scalar variables of type `sym`. The size of the evaluated symbolic matrix function `f(var1,...,varN)` is `nrow`-by-`ncol`.```
````syms f(var1,...,varN) n matrix` creates a square symbolic matrix function, where the evaluated symbolic matrix function `f(var1,...,varN)` has the size `n`-by-`n`. This syntax clears all previous definitions of `var1,...,varN` including symbolic assumptions.```
````syms f(var1,...,varN) n matrix keepargs` keeps existing definitions of `var1,...,varN` in the workspace. If any of the variables `var1,...,varN` does not exist in the workspace, then this syntax creates them as symbolic scalar variables of type `sym`.```

example

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

example

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

example

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

Examples

collapse all

Create symbolic scalar variables `x` and `y`.

```syms x y x```
`x = $x$`
`y`
`y = $y$`

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 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)$```

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`

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 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 a formula for `f`.

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

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

`f(1,2)`
`ans = $5$`

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 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}\left(x,y\right)$ and ${f}_{2,2}\left(x,y\right)$ 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 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 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 ```

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 B-B 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 ```

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}} A X$`
`H = diff(f,X,X.')`
`H = ${A}^{\mathrm{T}}+A$`

Create the function $\mathit{v}\left(\mathbit{r},\mathit{t}\right)=\frac{{‖\mathbit{r}‖}_{2}}{\mathit{t}}$, where $\mathbit{r}$ is a 1-by-3 vector and $\mathit{t}$ is a scalar.

Create $\mathbit{r}$ as a symbolic matrix variable and $\mathit{t}$ as a symbolic scalar variable. Create $\mathit{v}\left(\mathbit{r},\mathit{t}\right)$ as a symbolic matrix function and keep existing definitions of $\mathbit{r}$ and $\mathit{t}$ in the workspace.

```syms r [1 3] matrix syms t syms v(r,t) [1 1] matrix keepargs```

Assign the formula of $\mathit{v}\left(\mathbit{r},\mathit{t}\right)$.

`v(r,t) = norm(r)/t`
`v(r, t) = ${‖r‖}_{2} {t}^{-1}$`

The symbolic matrix function accepts scalars, vectors, and matrices as its input arguments. Evaluate the function for the vector value $\mathbit{r}=\left(1,2,2\right)$ and the scalar value $\mathit{t}=3$.

`vEval = v([1 2 2],3)`
```vEval =  ```

Convert the evaluated function from the `symmatrix` data type to the `sym` data type.

`vSym = symmatrix2sym(vEval)`
`vSym = $1$`

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

Create some symbolic scalar variables, functions, matrix variables, matrix functions, and arrays.

```syms a f(x) syms A [2 1] syms B [2 2] matrix syms g(B) [2 2] matrix keepargs```

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

`syms`
```Your symbolic variables are: A A1 A2 B a f g x ```

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

`S = syms`
```S = 8x1 cell {'A' } {'A1'} {'A2'} {'B' } {'a' } {'f' } {'g' } {'x' } ```

Create several symbolic objects.

```syms a b c f(x) syms D g(y) [2 2] matrix```

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

collapse all

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

Example: `x y123 z_1`

Dimensions of vector, matrix, or array of symbolic scalar variables, specified as a vector of nonnegative integers.

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

Dimensions of the square matrix, specified as a nonnegative scalar integer. For example, `syms x 3 matrix` creates a square `3`-by-`3` symbolic matrix variable.

Example: `3`

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`

Symbolic function or matrix function with its input arguments, specified as function and variable names 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 a variable name is valid, use `isvarname`.

Example: `F(r,t)`, `f(x,y)`

Dimensions of symbolic matrix variables or functions, specified as a vector of nonnegative integers.

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

Symbolic scalar variables and functions to create, 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

collapse all

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

Limitations

• Differentiation functions, such as `divergence`, `curl`, `jacobian`, and `laplacian`, currently do not accept symbolic matrix variables and 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 variables and symbolic matrix functions as input, use the command `methods symmatrix` and ```methods symfunmatrix```.

Tips

• You can create multiple symbolic objects in one call. For example, ```syms f(x) g(t) y``` creates two symbolic functions (`f` and `g`) and three symbolic scalar variables (`x`, `t`, and `y`).

• `syms` is a shortcut for `sym`, `symfun`, `symmatrix`, and `symfunmatrix`. This shortcut lets you create several symbolic objects with one function call. For example, you can use `sym` and create each symbolic scalar 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 or parallel for loops because it generates variables without direct output assignment and modifies the global state of the workspace. Using `syms` within functions can create side effects and other unexpected behaviors. Instead, use `sym` with left-side output assignment, such as ```t = sym('t')```. For more details, see Choose syms or sym Function.

• These 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` or `syms f(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.

• When evaluating a symbolic matrix function, you must substitute values that have the same size as the defined input arguments. For example, see Create Function of Vector and Scalar. 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 before R2006a

expand all