`subs`

Substitute into an object

MuPAD® notebooks will be removed in a future release. Use MATLAB® live scripts instead.

MATLAB live scripts support most MuPAD functionality, though there are some differences. For more information, see Convert MuPAD Notebooks to MATLAB Live Scripts.

Syntax

subs(f, old = new, <Unsimplified>)
subs(f, old₁ = new₁, old₂ = new₂, …, options)
subs(f, [old₁ = new₁, old₂ = new₂, …], options)
subs(f, {old₁ = new₁, old₂ = new₂, …}, options)
subs(f, table(old₁ = new₁, old₂ = new₂, …), options)
subs(f, s₁, s₂, …, options)

Description

subs(f, old = new) searches f for operands matching old, and replaces old with new. See Example 1.

subs does not replace subexpressions. For example, subs(a + b + c, b + c = d) does not replace b + c. Instead, use subsex. For details, see Example 8.

The subs function returns a modified copy of the object. The function does not change the object itself.

By default, the subs function does not evaluate the result of a substitution. To enforce evaluation of all modified subexpressions, use the EvalChanges option. Also, you can reevaluate the whole returned result by using the eval function. Evaluation of the returned result is slower and less efficient than evaluation of the modified subexpressions. See Example 3 and Example 4.

The call subs(f, old1 = new1, old2 = new2, ...) applies the specified substitutions in a sequence from left to right (sequential substituton). This call applies each substitution (except for the first substitution) to the result of the previous substitution. See Example 5.

The call subs(f, [old1 = new1, old2 = new2, ...]) applies all specified substitutions to the operands of the original input object f (parallel substitution). This call does not use the results of any previous substitutions. If you specify multiple substitutions of the same operand, this call computes only the first substitution. Specifying substitutions by lists, sets, or tables invokes parallel substitution. See Example 6.

The call subs(f, s1, s2, ...) is a general form of substitution that can combine sequential and parallel substitutions. This call is equivalent to subs(... subs(subs(f, s1), s2), ...). MuPAD^® treats each substitution step as a sequential or a parallel substitution depending on the form of the parameters s1, s2, …. See Example 7.

You can use subs to replace operands of expression sequences. The subs function does not flatten such objects. See Example 9.

If you do not specify substitutions, subs returns the original expression without modifications. For example, subs(f) returns f.

Examples

Example 1

Use the subs function to substitute the operands in the following expressions:

subs(a + b*a, a = 4)

subs([a * (b + c), sin(b +c)], b + c = a)

Example 2

When replacing the sine function in an expression, use the hold command to prevent the evaluation of the identifier sin:

subs(sin(x), hold(sin) = cos);
domtype(hold(sin))

Otherwise, MuPAD replaces sin by its value. The function environment (see funcenv) defines the value of sin:

subs(sin(x), sin = cos);
domtype(sin)

Inside the expression sin(x), the 0-th operand sin is the identifier, not the function environment:

domtype(op(sin(x), 0))

Example 3

The subs function evaluates the original expression, performs a substitution, but does not evaluate the modified expression:

subs(y^2 + sin(x), x = PI)

To evaluate the modified subexpression, use the EvalChanges option:

subs(y^2 + sin(x), x = PI, EvalChanges)

Alternatively, use the eval function to evaluate the result returned by subs:

S := subs(y^2 + sin(x), x = PI):
eval(S)

Example 4

The subs function with the EvalChanges option returns the same results as the evaluation of the whole expression:

eval(subs(sin(x + 3 - PI)*numeric::int(_plus(sin(k/y) $ k = 1..5),
                                       y = 0..1), x=-3));
subs(sin(x + 3 - PI)*numeric::int(_plus(sin(k/y) $ k = 1..5),
                                  y = 0..1), x = -3, EvalChanges)

The evaluation of the returned result is slower and less efficient than the evaluation of the modified subexpressions:

time(eval(subs(sin(x + 3 - PI)*numeric::int(_plus(sin(k/y) $ k = 1..5),
                                            y = 0..1), x = -3)));
time(subs(sin(x + 3 - PI)*numeric::int(_plus(sin(k/y) $ k = 1..5),
                                       y = 0..1), x = -3, EvalChanges))

Example 5

The following call results in the sequential substitution :

subs(x^3 + y*z, x = y, y = z)

Example 6

The subs function lets you use sequential and parallel substitutions. For example, substitute the operand in the following expressions sequentiallly:

subs(a^2 + b^3, a = b, b = a)

subs(a^2 + b^3, b = a, a = b)

For the same expression, parallel substitution swaps the identifiers:

subs(a^2 + b^3, [a = b, b = a])

In the following call, the substitution of y + x for a yields the intermediate result y + 2*x. From there, the substitution of z for x results in y + 2 z:

subs(a + x, a = x + y, x = z)

Parallel substitution produces a different result. The following call substitues a with x + y. Simultaneously, this call substitutes the operand x of the original expression a + x with z:

subs(a + x, [a = x + y, x = z])

If you specify the substitutions using a set of a table of equations, the subs function also performs a parallel substitution:

subs(a + x, {a = x + y, x = z})

T := table(): T[a] := x + y: T[x] := z: T

subs(a + x, T)

delete T:

Example 7

You can combine sequential and parallel substitutions:

subs(a + x, {a = x + y, x = z}, x = y)

Example 8

The subs function replaces only those operands that the op function can return. The following expression contains the subexpression x + y as the operand op(f, [1, 2]):

f := sin(z*(x + y)): op(f, [1, 2]);

Consequently, the subs function replaces this subexpression:

subs(f, x + y = z)

Syntactically, the following sum does not contain the subexpression x + y. Therefore, the subs function does not replace it:

subs(x + y + z, x + y = z)

In contrast to subs, the subsex function finds and replaces partial sums and products:

subsex(x + y + z, x + y = z)

subs(a*b*c, a*c = 5), subsex(a*b*c, a*c = 5)

delete f:

For details on substitution functions in MuPAD, please see Modify Subexpressions. For details on expression trees, please see Visualize Expression Trees.

Example 9

You can substitute operands of expression sequences. Enclose sequences in parentheses:

subs((a, b, a*b), a = x)

Example 10

The Unsimplified option suppresses simplification:

subs(a + b + 2, a = 1, b = 0, Unsimplified)

Example 11

If you try to substitute something in a domain, MuPAD ignores the substitution. For example, define a new domain with the methods "foo" and "bar":

mydomain := newDomain("Test"):
mydomain::foo := x -> 4*x:
mydomain::bar := x -> 4*x^2:

Now try to replace every number 4 inside the domain with the number 3:

mydomain := subs(mydomain, 4 = 3):

That substitution does not have any effect:

mydomain::foo(x), mydomain::bar(x)

To substitute objects in a domain method, you must substitute in the individual methods:

mydomain::foo := subs(mydomain::foo, 4 = 3):
mydomain::bar := subs(mydomain::bar, 4 = 3):
mydomain::foo(x), mydomain::bar(x)

delete mydomain:

Parameters

`f`	An arbitrary MuPAD object
`old, old₁, old₂, …`	Arbitrary MuPAD objects
`new, new₁, new₂, …`	Arbitrary MuPAD objects
`s₁, s₂, …`	Either equations `old = new`, or lists or sets of such equations, or tables whose entries are interpreted as such equations.

Options

EvalChanges

After substitution, evaluate all modified subexpressions.

By default, the subs function does not evaluate the modified object. The EvalChanges option enforces the evaluation of all modified subexpressions. See Example 3 and Example 4.

Unsimplified

Do not simplify the result of a substitution.

As the last step of a substitution, MuPAD automatically simplifies (but does not evaluate) the modified object. The Unsimplified option suppresses the final simplification. See Example 10.

Return Values

Copy of the input object with replaced operands.

Overloaded By

f