# subs

Symbolic substitution

## Syntax

``snew = subs(s,old,new)``
``snew = subs(s,new)``
``snew = subs(s)``
``sMnew = subs(sM,oldM,newM)``
``sMnew = subs(sM,newM)``

## Description

example

````snew = subs(s,old,new)` returns a copy of `s`, replacing all occurrences of `old` with `new`, and then evaluates `s`. Here, `s` is an expression that contains symbolic scalar variables and `old` specifies the scalar variables to be substituted.```

example

````snew = subs(s,new)` returns a copy of `s`, replacing all occurrences of the default symbolic scalar variable in `s` with `new`, and then evaluates `s`. The default variable is defined by `symvar(s,1)`.```

example

````snew = subs(s)` returns a copy of `s`, replacing symbolic scalar variables in `s`, with their values obtained from the calling function and the MATLAB® Workspace, and then evaluates `s`. Variables with no assigned values remain as variables.```

example

````sMnew = subs(sM,oldM,newM)` returns a copy of `sM`, replacing all occurrences of `oldM` with `newM`, and then evaluates `sM`. Here, `sM` is an expression that contains symbolic matrix variables and `oldM` specifies the matrix variables to be substituted. (since R2021b)```

example

````sMnew = subs(sM,newM)` returns a copy of `sM`, replacing all occurrences of the default symbolic matrix variable in `sM` with `newM`, and then evaluates `sM`. (since R2021b)```

## Examples

collapse all

Replace `a` with `4` in this expression.

```syms a b subs(a + b,a,4)```
`ans = $b+4$`

Replace `a*b` with `5` in this expression.

`subs(a*b^2,a*b,5)`
`ans = $5 b$`

Substitute the default symbolic scalar variable in this expression with `a`. If you do not specify the scalar variable or expression to replace, `subs` uses `symvar` to find the default variable. For `x + y`, the default variable is `x`.

```syms x y a symvar(x + y,1)```
`ans = $x$`

Therefore, subs replaces `x` with `a`.

`subs(x + y,a)`
`ans = $a+y$`

When you assign a new value to a symbolic scalar variable, expressions containing the variable are not automatically evaluated. Instead, evaluate expressions by using `subs`.

Define the expression `y = x^2`.

```syms x y = x^2;```

Assign `2` to `x`. The value of `y` is still `x^2` instead of `4`.

```x = 2; y```
`y = ${x}^{2}$`

Evaluate `y` with the new value of `x` by using `subs`.

`subs(y)`
`ans = $4$`

Make multiple substitutions by specifying the old and new values as vectors.

```syms a b subs(cos(a) + sin(b), [a,b], [sym('alpha'),2])```
`ans = $\mathrm{sin}\left(2\right)+\mathrm{cos}\left(\alpha \right)$`

Alternatively, for multiple substitutions, use cell arrays.

`subs(cos(a) + sin(b), {a,b}, {sym('alpha'),2})`
`ans = $\mathrm{sin}\left(2\right)+\mathrm{cos}\left(\alpha \right)$`

Replace the symbolic scalar variable `a` in this expression with the 3-by-3 magic square matrix. Note that the constant `1` expands to the 3-by-3 matrix with all its elements equal to `1`.

```syms a t subs(exp(a*t) + 1, a, -magic(3))```
```ans =  $\left(\begin{array}{ccc}{\mathrm{e}}^{-8 t}+1& {\mathrm{e}}^{-t}+1& {\mathrm{e}}^{-6 t}+1\\ {\mathrm{e}}^{-3 t}+1& {\mathrm{e}}^{-5 t}+1& {\mathrm{e}}^{-7 t}+1\\ {\mathrm{e}}^{-4 t}+1& {\mathrm{e}}^{-9 t}+1& {\mathrm{e}}^{-2 t}+1\end{array}\right)$```

You can also replace an element of a vector, matrix, or array with a nonscalar value. For example, create these 2-by-2 matrices.

`A = sym('A',[2,2])`
```A =  $\left(\begin{array}{cc}{A}_{1,1}& {A}_{1,2}\\ {A}_{2,1}& {A}_{2,2}\end{array}\right)$```
`B = sym('B',[2,2])`
```B =  $\left(\begin{array}{cc}{B}_{1,1}& {B}_{1,2}\\ {B}_{2,1}& {B}_{2,2}\end{array}\right)$```

Replace the first element of the matrix `A` with the matrix `B`. While making this substitution, `subs` expands the 2-by-2 matrix `A` into this 4-by-4 matrix.

`A44 = subs(A, A(1,1), B)`
```A44 =  $\left(\begin{array}{cccc}{B}_{1,1}& {B}_{1,2}& {A}_{1,2}& {A}_{1,2}\\ {B}_{2,1}& {B}_{2,2}& {A}_{1,2}& {A}_{1,2}\\ {A}_{2,1}& {A}_{2,1}& {A}_{2,2}& {A}_{2,2}\\ {A}_{2,1}& {A}_{2,1}& {A}_{2,2}& {A}_{2,2}\end{array}\right)$```

`subs` does not let you replace a nonscalar or matrix with a scalar that shrinks the matrix size.

Create a structure array with symbolic expressions as the field values.

```syms x y z S = struct('f1',x*y,'f2',y + z,'f3',y^2)```
```S = struct with fields: f1: x*y f2: y + z f3: y^2 ```

Replace the symbolic scalar variables `x`, `y`, and `z` with numeric values.

`Sval = subs(S,[x y z],[0.5 1 1.5])`
```Sval = struct with fields: f1: 1/2 f2: 5/2 f3: 1 ```

Replace the symbolic scalar variables `x` and `y` with these 2-by-2 matrices. When you make multiple substitutions involving vectors or matrices, use cell arrays to specify the old and new values.

```syms x y subs(x*y, {x,y}, {[0 1; -1 0], [1 -1; -2 1]})```
```ans =  $\left(\begin{array}{cc}0& -1\\ 2& 0\end{array}\right)$```

Note that since `x` and `y` are scalars, these substitutions are element-wise.

`[0 1; -1 0].*[1 -1; -2 1]`
```ans = 2×2 0 -1 2 0 ```

Eliminate scalar variables from an equation by using the variable's value from another equation. In the second equation, isolate the variable on the left side using `isolate`, and then substitute the right side with the variable in the first equation.

First, declare the equations `eqn1` and `eqn2`.

```syms x y eqn1 = sin(x)+y == x^2 + y^2; eqn2 = y*x == cos(x);```

Isolate `y` in `eqn2` by using `isolate`.

`eqn2 = isolate(eqn2,y)`
```eqn2 =  $y=\frac{\mathrm{cos}\left(x\right)}{x}$```

Eliminate `y` from `eqn1` by substituting the right side of `eqn2` with the left side of `eqn2` in `eqn1`.

`eqn1 = subs(eqn1,lhs(eqn2),rhs(eqn2))`
```eqn1 =  $\mathrm{sin}\left(x\right)+\frac{\mathrm{cos}\left(x\right)}{x}=\frac{{\mathrm{cos}\left(x\right)}^{2}}{{x}^{2}}+{x}^{2}$```

Replace `x` with `a` in this symbolic function.

```syms x y a syms f(x,y) f(x,y) = x + y; f = subs(f,x,a)```
`f(x, y) = $a+y$`

`subs` replaces the values in the symbolic function formula, but does not replace input arguments of the function.

`formula(f)`
`ans = $a+y$`
`argnames(f)`
`ans = $\left(\begin{array}{cc}x& y\end{array}\right)$`

Replace the arguments of a symbolic function explicitly.

```syms x y f(x,y) = x + y; f(a,y) = subs(f,x,a); f```
`f(a, y) = $a+y$`

Suppose you want to verify the solutions of this system of equations.

```syms x y eqs = [x^2 + y^2 == 1, x == y]; S = solve(eqs,[x y]); S.x```
```ans =  $\left(\begin{array}{c}-\frac{\sqrt{2}}{2}\\ \frac{\sqrt{2}}{2}\end{array}\right)$```
`S.y`
```ans =  $\left(\begin{array}{c}-\frac{\sqrt{2}}{2}\\ \frac{\sqrt{2}}{2}\end{array}\right)$```

Verify the solutions by substituting the solutions into the original system.

`isAlways(subs(eqs,S))`
```ans = 2x2 logical array 1 1 1 1 ```

Since R2021b

Define the product of two 2-by-2 matrices. Declare the matrices as symbolic matrix variables with `symmatrix` data type.

```syms X Y [2 2] matrix sM = X*Y```
`sM = $X Y$`

Replace the matrix variables $X$ and $Y$ with 2-by-2 symbolic matrices. When you make multiple substitutions involving vectors or matrices, use cell arrays to specify the old and new values.

`S = subs(sM,{X,Y},{[0 1; -1 0], [1 -1; -2 1]})`
```S =  ```

Convert the expression `S` to the `sym` data type to show the result of the substituted matrix multiplication.

`Ssym = symmatrix2sym(S)`
```Ssym =  $\left(\begin{array}{cc}-2& 1\\ -1& 1\end{array}\right)$```

Since R2021b

Create a matrix of symbolic numbers.

`A = sym([1 4 2; 4,1,2; 2,2,3])`
```A =  $\left(\begin{array}{ccc}1& 4& 2\\ 4& 1& 2\\ 2& 2& 3\end{array}\right)$```

Compute the coefficients of the characteristic polynomial of `A` using the `charpoly` function.

`c = charpoly(A);`

Next, define $X$ as a 3-by-3 symbolic matrix variable. Use the coefficients `c` to create the polynomial $p\left(X\right)={c}_{1}{X}^{3}+{c}_{2}{X}^{2}+{c}_{3}X+{c}_{4}{I}_{3}$, where $X$ is an indeterminate that represents a 3-by-3 matrix.

```syms X [3 3] matrix p = c(1)*X^3 + c(2)*X^2 + c(3)*X + c(4)*X^0```
`p = $21 {\mathrm{I}}_{3}-17 X-5 {X}^{2}+{X}^{3}$`

Substitute $X$ in the polynomial $p\left(X\right)$ with `A` using the `subs` function. According to the Cayley-Hamilton theorem, this results in a 3-by-3 zero matrix, since the coefficients `c` are the characteristic polynomial of `A`. Use `symmatrix2sym` to convert the substituted expression to a matrix of symbolic numbers.

`Y = subs(p,A)`
```Y =  ```
`Z = symmatrix2sym(Y)`
```Z =  $\left(\begin{array}{ccc}0& 0& 0\\ 0& 0& 0\\ 0& 0& 0\end{array}\right)$```

## Input Arguments

collapse all

Input, specified as a symbolic scalar variable, expression, equation, function, array, matrix, or a structure.

Data Types: `sym` | `symfun` | `struct`

Scalar variable to substitute, specified as a symbolic scalar variable, expression, array, or a cell array.

Data Types: `sym` | `cell`

New value to substitute with, specified as a number, symbolic number, scalar variable, expression, array, structure, or a cell array.

Data Types: `sym` | `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64` | `char` | `string` | `struct` | `cell`

Since R2021b

Input, specified as a symbolic matrix variable, or symbolic expression containing matrix variables.

Data Types: `symmatrix`

Since R2021b

Matrix variable to substitute, specified as a symbolic matrix variable, symbolic expression, or cell array containing matrix variables.

Data Types: `symmatrix` | `cell`

Since R2021b

New value to substitute with, specified as a number, symbolic number, matrix variable, expression, array, or cell array. `newM` must have the same dimension as `oldM`, or as the default symbolic matrix variable in `sM`.

Data Types: `sym` | `symmatrix` | `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64` | `char` | `string` | `struct` | `cell`

## Tips

• `subs(s,old,new)` does not modify `s`. To modify `s`, use `s = subs(s,old,new)`.

• If `old` and `new` are both vectors or cell arrays of the same size, `subs` replaces each element of `old` with the corresponding element of `new`.

• If `old` is a scalar, and `new` is a vector or matrix, then `subs(s,old,new)` replaces all instances of `old` in `s` with `new`, performing all operations element-wise. All constant terms in `s` are replaced with the constant multiplied by a vector or matrix of all 1s.

• If `s` is a univariate polynomial and `new` is a numeric matrix, use `polyvalm(sym2poly(s),new)` to evaluate `s` as a matrix. All constant terms are replaced with the constant multiplied by an identity matrix.

Introduced before R2006a

## Support

#### Mathematical Modeling with Symbolic Math Toolbox

Get examples and videos