Documentation

# `subsex`

Extended substitution

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

```subsex(`f`, `old = new`, <Unsimplified>)
subsex(`f`, `old1 = new1, old2 = new2, …`, <Unsimplified>)
subsex(`f`, `[old1 = new1, old2 = new2, …]`, <Unsimplified>)
subsex(`f`, `{old1 = new1, old2 = new2, …}`, <Unsimplified>)
subsex(`f`, table(`old1 = new1, old2 = new2, …`), <Unsimplified>)
subsex(`f`, `s1, s2, …`, <Unsimplified>)
```

## Description

`subsex(f, old = new)` returns a copy of the object `f` in which all expressions matching `old` are replaced by the value `new`.

`subsex` returns a modified copy of the object, but does not change the object itself.

`subsex(f, old = new)` searches `f` for subexpressions matching `old`. Each such subexpression is replaced by `new`.

Unlike the `subs` function, `subsex` replaces “incomplete” subexpressions. For example, ```subsex(a + b + c, b + c = d)``` replaces `b + c` but ```subs(a + b + c, b + c = d)``` does not replace `b + c`. In general, combinations of the operands of the n-ary “operators” `+`, `*`, `and`, `_exprseq`, `intersect`, `or`, `_lazy_and`, `_lazy_or`, and `union` can be replaced. In particular, partial sums and partial products can be replaced. Note that these operations are assumed to be commutative, e.g., ```subsex(a*b*c, a*c = new)``` does replace the partial product `a*c` by `new`. See Example 1 and Example 2. However, the advantage of `subs` over `subsex` is that `subs` is much faster.

`subsex` additionally replaces powers with the same base, if the exponent of the expression is an integer multiple of the replacement power, e.g. like in ```subsex(a^4, a^2 = new)```. This rule also matches inverted expressions like in ```subsex(1/sqrt(x), sqrt(x)=new)```, which is internally equivalent to ```subsex(x^(-1/2), x^(1/2)=new)```. Cf. Example 3.

The call `subsex(f, old1 = new1, old2 = new2, ...)` invokes a “sequential substitution”. See the `subs` help page for details.

The call `subsex(f, [old1 = new1, old2 = new2, ...])` invokes a “parallel substitution”. See the `subs` help page for details.

The call `subsex(f, s1, s2, ...)` describes the most general form of substitution which may combine sequential and parallel substitutions. This call is equivalent to ```subsex(... subsex(subsex(f, s1), s2), ...)```. Depending on the form of `s1`, `s2`, , sequential or parallel substitutions are carried out in each step. An example can be found on the `subs` help page.

After substitution, the result is not evaluated. Use the function `eval` to enforce evaluation. Cf. Example 5.

Operands of expression sequences can be replaced by `subsex`. Such objects are not flattened. Cf. Example 6.

The call `subsex(f)` is allowed; it returns `f` without modifications.

## Examples

### Example 1

We demonstrate some simple substitutions; `subsex` finds and replaces partial sums and products:

`subsex(a + b + c, a + c = x)`

`subsex(a*b*c, a*c = x)`

`subsex(a * (b + c) + b + c, b + c = a)`

`subsex(a + b*c*d + b*d, b*d = c);`

### Example 2

We replace subexpressions inside a symbolic union of sets:

`subsex(a union b union c, a union b = w)`

The same can be achieved by using the functional equivalent `_union` of the operator `union`:

`subsex(_union(a, b, c), _union(a, b) = w)`

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

### Example 3

`subsex` replaces powers with with the same base, if the exponent of the expression is an integer multiple of the replacement power:

`subsex(1/a^4, a^2 = X)`

This holds even for exponents which are expressions:

`subsex(1/a^(6*x), a^(2*x) = X)`

`1/sqrt(x)` is internally `x^(-1/2)`, so the replacement of `sqrt(x)` which is internally `x^(1/2)` works, too:

`subsex(1/sqrt(n), sqrt(n) = X)`

### Example 4

`subsex` is often useful to convert the output of one command into a form required by the next one. As an example, we compute the Laplace transform of the two-dimensional ODE

,

,

and transform the result into a form suitable for calling `solve` by replacing the unknown Laplace transforms by symbolic names:

```xfrm1 := laplace(x'(t) = x(t) + 2*y(t), t, s); xfrm2 := laplace(y'(t) = 5*x(t) + 2*y(t), t, s)```

For readability, we give names to both substitutions:

```sub_x := laplace(x(t),t,s) = X: sub_y := laplace(y(t),t,s) = Y:```
```Leqn1 := subs(xfrm1, sub_x, sub_y, x(0) = 1); Leqn2 := subs(xfrm2, sub_x, sub_y, y(0) =-2)```

`solve({Leqn1, Leqn2}, {X, Y})`

### Example 5

The result of `subsex` is not evaluated. In the following call, the identifier `sin` is not replaced by its value, i.e., by the procedure defining the behavior of the system's sine function. Consequently, `sin(2*PI)` is not simplified to 0 by this procedure:

`subsex(sin(2*x*y), x*y = PI)`

The function `eval` enforces evaluation:

`eval(subsex(sin(2*x*y), x*y = PI))`

### Example 6

Operands of expression sequences can be substituted. Note that sequences need to be enclosed in brackets:

`subsex((a, b, a*b*c), a*b = x)`

### Example 7

The option `Unsimplified` suppresses simplification:

`subsex(2 + a + b, a + b = 0, Unsimplified)`

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

 `Unsimplified` Prevents simplification of the returned object after substitution As the last step of a substitution, the modified object is simplified (however, not evaluated). This option suppresses this final simplification. See Example 7.

## Return Values

Copy of the input object with replaced operands.

`f`