subs

R2026b

Symbolic substitution

Syntax

exprnew = subs(expr,match,replacement)

exprnew = subs(expr,replacement)

exprnew = subs(expr)

exprnew = subs(expr,match,replacement,Wildcards=vars)

exprnew = subs(expr,match,replacement,Wildcards=vars,Condition=condition)

Description

Substitute Variables, Functions, or Subexpressions

exprnew = subs(expr,match,replacement) replaces all occurrences of match in expr with replacement, evaluates the expression, and returns the result as a symbolic expression.

• If match and replacement are both vectors or cell arrays of the same size, then subs replaces each element of match with the corresponding element of replacement.

• If match is a scalar and replacement is a vector or matrix, then subs replaces all instances of match with replacement, performing all operations element-wise. The function replaces all constant terms in expr with the constant multiplied by a vector or matrix of all ones.

• If expr involves symbolic matrix variables or matrix functions, then replacement and match must be the same size.

exprnew = subs(expr,replacement) replaces all occurrences of the default symbolic variable in expr with replacement, evaluates the expression, and returns the result as a symbolic expression. The default variable is defined by symvar(expr,1).

exprnew = subs(expr) replaces symbolic variables and functions in expr with their assigned values in the MATLAB^® workspace, evaluates the expression, and returns the result as a symbolic expression. Variables with no assigned values remain as variables.

Substitute Using Pattern Matching

Since R2026b

exprnew = subs(expr,match,replacement,Wildcards=vars) performs pattern-based substitution by finding subexpressions in expr that match the pattern match and replacing them with replacement, treating the variables specified in vars as wildcards.

exprnew = subs(expr,match,replacement,Wildcards=vars,Condition=condition) performs pattern-based substitution using the constraint or condition specified by condition. The function replaces matching subexpressions only if condition evaluates to true for their matched wildcard values.

Examples

Single Substitution

Replace a with 4 in a symbolic expression.

syms a b
expr = a*b^2

expr = $$a\hspace{0.17em}{b}^2$$

exprnew = subs(expr,a,4)

exprnew = $$4\hspace{0.17em}{b}^2$$

Replace a*b with 5 in the original expression.

exprnew = subs(expr,a*b,5)

exprnew = $$5\hspace{0.17em}b$$

Default Substitution Variable

Substitute the default symbolic scalar variable in a symbolic expression with a. If you do not specify the scalar variable or subexpression to replace, subs uses symvar to find the default variable.

syms x y a
expr = x + y

expr = $$x+y$$

var = symvar(expr,1)

var = $$x$$

For x + y, the default variable is x. Therefore, subs replaces x with a.

exprnew = subs(expr,a)

exprnew = $$a+y$$

Evaluate Expression with New Values

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.

yeval = subs(y)

yeval = $$4$$

Multiple Substitutions

Make multiple substitutions by specifying the variables to substitute and the new values as vectors.

syms a b
expr = cos(a) + sin(b)

expr = $$\cos \left(a\right)+\sin \left(b\right)$$

exprnew = subs(expr,[a,b],[sym("alpha"),2])

exprnew = $$\sin \left(2\right)+\cos \left(\alpha \right)$$

Alternatively, for multiple substitutions, use cell arrays.

exprnew = subs(expr,{a,b},{sym("alpha"),2})

exprnew = $$\sin \left(2\right)+\cos \left(\alpha \right)$$

Substitute Scalars with Arrays

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

syms a t
expr = exp(a*t) + 1

expr = $${\mathrm{e}}^{a\hspace{0.17em}t}+1$$

expr3by3 = subs(expr,a,magic(3))

expr3by3 = 
$$\left(\begin{array}{ccc}{\mathrm{e}}^{8\hspace{0.17em}t}+1& {\mathrm{e}}^t+1& {\mathrm{e}}^{6\hspace{0.17em}t}+1\\ {\mathrm{e}}^{3\hspace{0.17em}t}+1& {\mathrm{e}}^{5\hspace{0.17em}t}+1& {\mathrm{e}}^{7\hspace{0.17em}t}+1\\ {\mathrm{e}}^{4\hspace{0.17em}t}+1& {\mathrm{e}}^{9\hspace{0.17em}t}+1& {\mathrm{e}}^{2\hspace{0.17em}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.

A4by4 = subs(A, A(1,1), B)

A4by4 = 
$$\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)$$

You cannot use subs to replace a variable that represents a matrix with a scalar value that reduces the matrix size.

Substitute Multiple Scalars with Arrays

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

syms x y
expr = x*y

expr = $$x\hspace{0.17em}y$$

exprnew = subs(expr,{x,y},{[0 1; -1 0],[1 -1; -2 1]})

exprnew = 
$$\left(\begin{array}{cc}0& -1\\ 2& 0\end{array}\right)$$

Because x and y are scalars, these substitutions are element-wise. Compare the result with the element-wise multiplication of the two 2-by-2 matrices.

exprmult = [0 1; -1 0].*[1 -1; -2 1]

exprmult = 2×2

     0    -1
     2     0

Substitute Symbolic Scalar Variables in Structure Array

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

Substitutions in Equations

Eliminate scalar variables from an equation by using the variable value from another equation. In the second equation, isolate the variable on the left side using isolate. Then substitute the variable in the first equation with the right side of the second equation.

First, define 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{\cos \left(x\right)}{x}$$

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

eqn1 = subs(eqn1,lhs(eqn2),rhs(eqn2))

eqn1 = 
$$\sin \left(x\right)+\frac{\cos \left(x\right)}{x}=\frac{{\cos \left(x\right)}^2}{x^2}+x^2$$

Substitutions in Functions

Replace x with a in a 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 it does not replace input arguments of the function.

formula = formula(f)

formula = $$a+y$$

args = argnames(f)

args = $$\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$$

Substitute Variables with Values from Structure

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

syms x y
eqns = [x^2 + y^2 == 1, x == y];
sols = solve(eqns,[x y]);
sols.x

ans = 
$$\left(\begin{array}{c}-\frac{\sqrt{2}}{2}\\ \frac{\sqrt{2}}{2}\end{array}\right)$$

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

tf = isAlways(subs(eqns,sols))

tf = 2×2 logical array

   1   1
   1   1

Substitution Involving First-Order and Second-Order Derivatives

Create a symbolic expression that involves first-order and second-order derivatives.

syms r(t)
expr = diff(r,t,t) + diff(r,t)

expr(t) = 
$$\frac{{\partial }^2}{\partial t^2}\mathrm{ }r\left(t\right)+\frac{\partial }{\partial t}\mathrm{ }r\left(t\right)$$

Substitute the first-order derivative with another variable $v_0$ and the second-order derivative with another variable $\text{D2r}$. To do so, you must first substitute the derivative with the higher order, which is the second-order derivative.

syms v_0 D2r
exprnew = subs(expr,diff(r,t,t),D2r);
exprnew = subs(exprnew,diff(r,t),v_0)

exprnew(t) = $$\mathrm{D2r}+v_0$$

You can also make these substitutions in a single subs call by specifying the variables to replace and their replacements as vectors.

exprnew = subs(expr,[diff(r,t,t) diff(r,t)],[D2r v_0])

exprnew(t) = $$\mathrm{D2r}+v_0$$

If you want to substitute only the first-order derivative while keeping the second-order derivative intact, you can continue with the previous workflow by changing the temporary variable $\text{D2r}$ back to $\frac{{\partial }^2}{\partial t^2}r\left(t\right)$.

exprnew = subs(exprnew,D2r,diff(r,t,t))

exprnew(t) = 
$$\frac{{\partial }^2}{\partial t^2}\mathrm{ }r\left(t\right)+v_0$$

For comparison, if you first substitute the first-order derivative in the original expression with $v_0$, then the result is $v_0$. Here, subs replaces the first-order derivative with $v_0$ and the second-order derivative with $\frac{\partial }{\partial t}\frac{\partial r\left(t\right)}{\partial t}=\frac{\partial }{\partial t}{v}_0=0$. This substitution results in an expression that does not contain a second-order derivative.

syms v_0
exprnew = subs(expr,diff(r,t),v_0)

exprnew(t) = $$v_0$$

Substitute Symbolic Matrix Variables with Arrays

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
M = X*Y

M = $$X\hspace{0.17em}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 substitute and their new values. The new values must have the same size as the matrix variables to be substituted.

Mnew = subs(M,{X,Y},{[0 sqrt(sym(2)); sqrt(sym(2)) 0], [1 -1; -2 1]})

Mnew = 
$$\begin{array}{l}{\Sigma }_1\\ \\ \mathrm{where}\\ \\ \mathrm{ }{\Sigma }_1=\left(\begin{array}{cc}-2\hspace{0.17em}\sqrt{2}& \sqrt{2}\\ \sqrt{2}& -\sqrt{2}\end{array}\right)\end{array}$$

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

Mnew = symmatrix2sym(Mnew)

Mnew = 
$$\left(\begin{array}{cc}-2\hspace{0.17em}\sqrt{2}& \sqrt{2}\\ \sqrt{2}& -\sqrt{2}\end{array}\right)$$

Substitute Variables in Symbolic Matrix Function

Since R2022a

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

Create a 2-by-2 symbolic matrix variable $A$. Create a symbolic matrix function $f\left(A\right)$, keeping the existing definition of $A$ in the workspace. Assign the polynomial expression of $f\left(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\hspace{0.17em}A+A^2$$

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

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

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

g(B,C) = subs(f,A,B+C)

g(B, C) = $${\left(B+C\right)}^2+{\mathrm{I}}_2-2\hspace{0.17em}B-2\hspace{0.17em}C$$

Evaluate $g\left(B,C\right)$ for the matrix values $B=\left[\begin{array}{cc}0& 1\\ -1& 0\end{array}\right]$ and $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 = 
$$\begin{array}{l}-2\hspace{0.17em}{\Sigma }_1-2\hspace{0.17em}{\Sigma }_2+{\left({\Sigma }_1+{\Sigma }_2\right)}^2+{\mathrm{I}}_2\\ \\ \mathrm{where}\\ \\ \mathrm{ }{\Sigma }_1=\left(\begin{array}{cc}0& 1\\ -1& 0\end{array}\right)\\ \\ \mathrm{ }{\Sigma }_2=\left(\begin{array}{cc}1& -1\\ -2& 1\end{array}\right)\end{array}$$

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

Substitute Symbolic Matrix Variables and Matrix Functions in Equation

Since R2022b

Define the equation $\frac{\partial }{\partial X^T}\frac{\partial }{\partial X}f\left(X,A\right)=2A$, where $A$ is a 3-by-3 matrix and $X$ is a 3-by-1 matrix. Substitute $f\left(X,A\right)$ with another symbolic expression and $A$ with symbolic values. Check if the equation is true for these values.

Create two symbolic matrix variables $A$ and $X$. Create a symbolic matrix function $f\left(X,A\right)$, keeping the existing definitions of $A$ and $X$ in the workspace. Create the equation.

syms A [3 3] matrix
syms X [3 1] matrix
syms f(X,A) [1 1] matrix keepargs
eqn = diff(diff(f,X),X.') == 2*A

eqn(X, A) = 
$$\frac{\partial }{\partial X^{\mathrm{T}}}\mathrm{ }\frac{\partial }{\partial X}\mathrm{ }f\left(X,A\right)=2\hspace{0.17em}A$$

Substitute $f\left(X,A\right)$ with $X^{T}AX$ and evaluate the second-order differential function in the equation for this expression.

eqn = subs(eqn,f,X.'*A*X)

eqn(X, A) = $$A^{\mathrm{T}}+A=2\hspace{0.17em}A$$

Substitute $A$ with the Hilbert matrix of order 3.

eqn = subs(eqn,A,hilb(3))

eqn(X, A) = 
$$\begin{array}{l}{\Sigma }_1+{{\Sigma }_1}^{\mathrm{T}}=2\hspace{0.17em}{\Sigma }_1\\ \\ \mathrm{where}\\ \\ \mathrm{ }{\Sigma }_1=\left(\begin{array}{ccc}1& \frac{1}{2}& \frac{1}{3}\\ \frac{1}{2}& \frac{1}{3}& \frac{1}{4}\\ \frac{1}{3}& \frac{1}{4}& \frac{1}{5}\end{array}\right)\end{array}$$

Check if the equation is true for these values by using isAlways. Because isAlways accepts only a symbolic input of type symfun or sym, convert eqn from type symfunmatrix to type symfun before using isAlways.

tf = isAlways(symfunmatrix2symfun(eqn))

tf = 3×3 logical array

   1   1   1
   1   1   1
   1   1   1

Evaluate Expression Involving Symbolic Matrix Variables

Since R2023b

Define the expression $X{Y}^2-Y{X}^2$, where $X$ and $Y$ are 3-by-3 matrices. Create the matrices as symbolic matrix variables.

syms X Y [3 3] matrix
C = X*Y^2 - Y*X^2

C = $$X\hspace{0.17em}{Y}^2-Y\hspace{0.17em}{X}^2$$

Assign values to the matrices X and Y.

X = [-1 2 pi; 0 1/2 2; 2 1 0];
Y = [3 2 2; -1 2 1; 1 2 -1];

Evaluate the expression C with the assigned values of X and Y by using subs.

Cnew = subs(C)

Cnew = 
$$\begin{array}{l}-{\Sigma }_1\hspace{0.17em}{{\Sigma }_2}^2+{\Sigma }_2\hspace{0.17em}{{\Sigma }_1}^2\\ \\ \mathrm{where}\\ \\ \mathrm{ }{\Sigma }_1=\left(\begin{array}{ccc}3& 2& 2\\ -1& 2& 1\\ 1& 2& -1\end{array}\right)\\ \\ \mathrm{ }{\Sigma }_2=\left(\begin{array}{ccc}-1& 2& \pi \\ 0& \frac{1}{2}& 2\\ 2& 1& 0\end{array}\right)\end{array}$$

Convert the result from the symmatrix data type to the double data type.

Cnum = double(Cnew)

Cnum = 3×3

  -42.8496  -13.3584  -13.4336
   -0.7168    3.1416    0.0752
   -3.2832   29.8584   16.4248

Substitute Terms That Match Pattern

Since R2026b

Create a symbolic expression.

syms x y z
expr = x + y*z

expr = $$x+y\hspace{0.17em}z$$

Create a symbolic variable to use as a wildcard for pattern-based substitution.

syms w

Replace all terms in the expression that match the pattern w with 3 using subs. The variables x, y, and z in the expression are replaced, resulting in the output 12.

exprnew = subs(expr,w,3,Wildcards=w)

exprnew = $$12$$

Apply Trigonometric Identity

Since R2026b

Create a symbolic expression where you want to apply a specific trigonometric identity.

syms x y
expr = cos(x)^2 + sin(x)^2 + tan(y)^2 + x

expr = $${\cos \left(x\right)}^2+{\sin \left(x\right)}^2+{\tan \left(y\right)}^2+x$$

Create a symbolic variable to use as a wildcard for substitution. To apply the trigonometric identity $${\cos }^2(\theta )+{\sin }^2(\theta )=1$$, define the pattern to match and its replacement.

syms w
match = cos(w)^2 + sin(w)^2

match = $${\cos \left(w\right)}^2+{\sin \left(w\right)}^2$$

replacement = 1

replacement = 
1

Replace the terms that match the pattern based on the trigonometric identity.

exprnew = subs(expr,match,replacement,Wildcards=w)

exprnew = $${\tan \left(y\right)}^2+x+1$$

For comparison, use the simplify function to simplify your original expression.

res_simp = simplify(expr)

res_simp = 
$$-\frac{-x\hspace{0.17em}{\sin \left(y\right)}^2+x+1}{{\sin \left(y\right)}^2-1}$$

While simplify applies a broad set of algebraic and trigonometric rules, it might not produce the intended form. Here, simplify rewrites the tan and cos functions in terms of sin before simplifying the original expression in expr.

Substitute Terms That Match Pattern and Condition

Since R2026b

Create a symbolic matrix with integer numbers and symbolic variables. Here, the variable c is assumed to be an integer.

syms a b
syms c integer
M = [a 2 3; 3 4 b; 3 3 c]

M = 
$$\left(\begin{array}{ccc}a& 2& 3\\ 3& 4& b\\ 3& 3& c\end{array}\right)$$

Create a symbolic variable to use as a wildcard for substitution. Define a condition for the pattern to match any symbolic object of type integer.

syms w
condition = @(w) isSymType(w,"integer");

Replace all integers in the matrix M with 5.

Mnew = subs(M,w,5,Wildcards=w,Condition=condition)

Mnew = 
$$\left(\begin{array}{ccc}a& 5& 5\\ 5& 5& b\\ 5& 5& c\end{array}\right)$$

Here, the variable c is not replaced by 5. Although c is assumed to have any integer value, the type of this object is variable, which does not satisfy the condition defined in condition.

symType(c)

ans = 
"variable"

Check the existing assumptions on c.

assumptions

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

Define a new condition for the wildcard variable using in based on this assumption.

condition = @(w) in(w,"integer");

Replace all integers in the matrix M with 5. Now, the variable c is replaced by 5.

Mnew = subs(M,w,5,Wildcards=w,Condition=condition)

Mnew = 
$$\left(\begin{array}{ccc}a& 5& 5\\ 5& 5& b\\ 5& 5& 5\end{array}\right)$$

Input Arguments

expr — Symbolic input

symbolic scalar variable | symbolic matrix variable | symbolic function | symbolic matrix function | symbolic expression | symbolic equation | symbolic array | structure

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

Data Types: sym | symmatrix | symfun | symfunmatrix (since R2022a) | struct

match — Symbolic variables, functions, or subexpressions to substitute

symbolic scalar variable | symbolic matrix variable | symbolic function | symbolic matrix function | symbolic expression | symbolic array | cell array

Symbolic variables, functions, or subexpressions to substitute, specified as a symbolic scalar variable, matrix variable, function, matrix function, expression, array, or a cell array.

When using the Wildcards option, match defines a symbolic pattern where designated variables act as wildcards. In this case, match must be of type sym or symfun, and the subs function replaces each scalar subexpression in expr that matches the symbolic pattern. (since R2026b)

Data Types: sym | symmatrix | symfun | symfunmatrix | cell

replacement — New replacement value

number | symbolic number | symbolic scalar variable | symbolic matrix variable | symbolic function | symbolic matrix function | symbolic expression | symbolic array | structure | cell array

New replacement value, specified as a number, symbolic number, scalar variable, matrix variable, function, matrix function, expression, array, structure, or cell array.

When substituting symbolic matrix variables or matrix functions, replacement must have the same size as match or as the default symbolic variable in expr.

When using the Wildcards option, replacement defines a replacement for terms that match a pattern involving wildcards. In this case, the subs function performs scalar substitution on matching subexpressions. The replacement value must be of type sym, symfun, single, double, int8, int16, int32, int64, uint8, uint16, uint32, or uint64. (since R2026b)

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

vars — Wildcard variables for pattern matching

symbolic scalar variable | vector of symbolic scalar variables

Since R2026b

Wildcard variables for pattern matching, specified as a symbolic scalar variable or vector of symbolic scalar variables. The symbolic variables used as wildcards must be different from the variables used in the input expression expr.

Data Types: sym

condition — Condition to constrain pattern matching

function handle

Since R2026b

Condition to constrain pattern matching, specified as a function handle that evaluates to true or false for wildcard values. The subs function performs substitution only when condition evaluates to true for the matched wildcard values. This table shows examples of function handles and their corresponding matching conditions.

Function handle	Matching Condition
@(w) true	Matches any wildcard value that is complex
@(w) w > 0	Matches any wildcard value that is greater than 0
@(w) (0 < w) & (w < 5)	Matches any wildcard value that is greater than 0 and less than 5
@(w) ~has(w,sym("t"))	Matches any wildcard value that does not include the variable t
@(w) isSymType(w,"symfun")	Matches any wildcard value that is a symbolic function
@(w) isSymType(w,"integer")	Matches any wildcard value that is explicitly an integer number
@(w) in(w,"integer")	Matches any wildcard value that is an integer number by including assumptions

Because symbolic variables are complex by default, pattern-based substitution finds matches for any wildcard value that is complex and satisfies the condition @(w) true. The subs function performs as many independent replacements as possible, starting with the smallest matching subexpressions.

When performing pattern-based substitution, subs takes into account all assumptions made about the variables in expr by using isAlways internally. Therefore, when specifying a condition to constrain pattern matching, you do not need to call isAlways explicitly. For example, you can define the condition to constrain pattern matching as @(w) w > 0 instead of @(w) isAlways(w > 0).

Data Types: function_handle

Output Arguments

exprnew — Symbolic expression after substitution

symbolic number | symbolic scalar variable | symbolic matrix variable | symbolic function | symbolic matrix function | symbolic expression | symbolic equation | symbolic array | structure

Symbolic expression after substitution, returned as a symbolic number, scalar variable, matrix variable, function, matrix function, expression, equation, array, or structure.

Data Types: sym | symmatrix | symfun | symfunmatrix

Tips

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

• If expr is a univariate polynomial and replacement is a numeric matrix, use polyvalm(sym2poly(expr),replacement) to evaluate expr as a matrix. The function replaces all constant terms with the constant multiplied by an identity matrix.

Version History

Introduced before R2006a

R2026b: Substitute terms using pattern matching and condition

The subs function now supports pattern-based substitution using the Wildcards and Condition arguments. You can use pattern-based substitution to:

• Replace specific parts of an expression that match a pattern.

• Define condition that controls when to replace a matching term.

• Apply mathematical identities, including your own custom identities, to simplify symbolic expressions.

For more information, see Pattern-Based Substitution.

R2023b: Substitute symbolic matrix variables with their workspace values

You can use the syntax subs(expr) to substitute the symbolic matrix variables and matrix functions in expr with their assigned values in the MATLAB workspace and then evaluate expr. Variables with no assigned values remain as variables. For an example, see Evaluate Expression Involving Symbolic Matrix Variables.

R2022b: Substitute symbolic matrix variables and matrix functions in symbolic equations or conditions

The subs function accepts a symbolic equation or condition of type symmatrix or symfunmatrix as the first input argument. For an example, see Substitute Symbolic Matrix Variables and Matrix Functions in Equation.

R2022b: Symbolic substitution involving derivatives follows input order

Starting in R2022b, symbolic substitution involving derivatives or the diff function follows the input order of the symbolic objects to be substituted. For example, this code performs symbolic substitution involving the diff function.

syms m k x(t)
syms x_t x_t_ddot
eqSHM = m*diff(x(t),t,2) == -k*x(t);
eqSHMnew = subs(eqSHM,[x(t) diff(x(t),t,2)],[x_t x_t_ddot])

Before R2022b, the code returns this output:

eqSHMnew = 
m*x_t_ddot == -k*x_t

Starting in R2022b, the code returns this output:

eqSHMnew =
0 == -k*x_t

The difference in output occurs because subs now first substitutes x(t) with x_t, resulting in m*diff(x_t,t,2) on the left side, which is equal to 0. To obtain the substitution result as in previous releases, specify the diff(x(t),t,2) term first so that subs substitutes it before the x(t) term.

eqSHMnew = subs(eqSHM,[diff(x(t),t,2) x(t)],[x_t_ddot x_t])

eqSHMnew = 
m*x_t_ddot == -k*x_t

R2022a: Substitute variables in symbolic matrix functions

The subs function accepts a symbolic matrix function of type symfunmatrix as the first input argument. For an example, see Substitute Variables in Symbolic Matrix Function.

R2021b: Substitute symbolic matrix variables in symbolic expressions

The subs function accepts a symbolic expression of type symmatrix as the first input argument. For an example, see Substitute Symbolic Matrix Variables with Arrays.