# 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 of symbolic scalar variables or a symbolic function, and `old` specifies the symbolic scalar variables or symbolic function to be substituted. 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 ones. ```

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 assigned values in 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 of symbolic matrix variables or a symbolic matrix function, and `oldM` specifies the symbolic matrix variables or symbolic matrix function to be substituted. The substitution values `newM` must have the same size as `oldM`.```

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

## 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 because `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 ```

Define the product of two 2-by-2 matrices. Declare the matrices as symbolic matrix variables with the `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 matrix variables to be substituted and their new values. The new values must have the same size as the matrix variables to be substituted.

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

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

Define the function $\mathit{f}\left(\mathbit{A}\right)={\mathbit{A}}^{2}-2\mathbit{A}+{\mathrm{I}}_{2}$, where $\mathbit{A}$ is a 2-by-2 matrix and ${\mathrm{I}}_{2}$ is a 2-by-2 identity matrix. Substitute the variable $\mathbit{A}$ with another expression and evaluate the new function.

Create a 2-by-2 symbolic matrix variable $\mathbit{A}$. Create a symbolic matrix function $\mathit{f}\left(\mathbit{A}\right)$, keeping the existing definition of $\mathbit{A}$ in the workspace. Assign the polynomial expression of $\mathit{f}\left(\mathbit{A}\right)$.

```syms A 2 matrix syms f(A) 2 matrix keepargs f(A) = A*A - 2*A + eye(2)```
`f(A) = ${\mathrm{I}}_{2}-2 A+{A}^{2}$`

Next, create new symbolic matrix variables $\mathbit{B}$ and $\mathbit{C}$. Create a new symbolic matrix function $\mathit{g}\left(\mathbit{B},\mathbit{C}\right)$, keeping the existing definitions of $\mathbit{B}$ and $\mathbit{C}$ in the workspace.

```syms B C 2 matrix syms g(B,C) 2 matrix keepargs```

Substitute the variable $\mathbit{A}$ in $\mathit{f}\left(\mathbit{A}\right)$ with $\mathbit{B}+\mathbit{C}$. Assign the substituted result to the new function $\mathit{g}\left(\mathbit{B},\mathbit{C}\right)$.

`g(B,C) = subs(f,A,B+C)`
`g(B, C) = ${\left(B+C\right)}^{2}+{\mathrm{I}}_{2}-2 B-2 C$`

Evaluate $\mathit{g}\left(\mathbit{B},\mathbit{C}\right)$ for the matrix values $\mathbit{B}=\left[\begin{array}{cc}0& 1\\ -1& 0\end{array}\right]$ and $\mathbit{C}=\left[\begin{array}{cc}1& -1\\ -2& 1\end{array}\right]$ using `subs`.

`S = subs(g(B,C),{B,C},{[0 1; -1 0],[1 -1; -2 1]})`
```S =  ```

Convert the expression `S` from the `symmatrix` data type to the `sym` data type to show the result of the substituted polynomial.

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

## Input Arguments

collapse all

Symbolic 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, function, expression, array, or a cell array.

Data Types: `sym` | `symfun` | `cell`

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

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

Symbolic input, specified as a symbolic matrix variable, symbolic matrix function, or symbolic expression.

Data Types: `symmatrix` | `symfunmatrix`

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

Data Types: `symmatrix` | `symfunmatrix` | `cell`

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

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

## Tips

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

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

## Version History

Introduced before R2006a

expand all