Documentation

# `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`, `old1 = new1, old2 = new2, …`, `options`)
subs(`f`, `[old1 = new1, old2 = new2, …]`, `options`)
subs(`f`, `{old1 = new1, old2 = new2, …}`, `options`)
subs(`f`, table(`old1 = new1, old2 = new2, …`), `options`)
subs(`f`, `s1, s2, …`, `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, old1, old2, …``` Arbitrary MuPAD objects ```new, new1, new2, …``` Arbitrary MuPAD objects `s1, s2, …` 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.

`f`