# Substitution by `usubs`

If an uncertain matrix or model object (`umat`, `uss`, `ufrd`) has many uncertain parameters, it is often useful to freeze some, but not all, of the uncertain parameters to specific values for analysis. The `usubs` command accomplishes this, and also allows more complicated substitutions for an element.

`usubs` accepts a list of element names and respective values to substitute for them. For example, can create three uncertain real parameters and use them to create a 2-by-2 uncertain matrix, `A`.

```delta = ureal('delta',2); eta = ureal('eta',6); rho = ureal('rho',-1); A = [3+delta+eta delta/eta;7+rho rho+delta*eta] ```
```A = Uncertain matrix with 2 rows and 2 columns. The uncertainty consists of the following blocks: delta: Uncertain real, nominal = 2, variability = [-1,1], 2 occurrences eta: Uncertain real, nominal = 6, variability = [-1,1], 3 occurrences rho: Uncertain real, nominal = -1, variability = [-1,1], 1 occurrences Type "A.NominalValue" to see the nominal value, "get(A)" to see all properties, and "A.Uncertainty" to interact with the uncertain elements. ```

Use `usubs` to substitute the uncertain element named `delta` in `A` with the value 2.3, leaving all other uncertain elements intact. That the result, `B`, is an uncertain matrix with dependence only on `eta` and `rho`.

`B = usubs(A,'delta',2.3) `
```B = Uncertain matrix with 2 rows and 2 columns. The uncertainty consists of the following blocks: eta: Uncertain real, nominal = 6, variability = [-1,1], 3 occurrences rho: Uncertain real, nominal = -1, variability = [-1,1], 1 occurrences Type "B.NominalValue" to see the nominal value, "get(B)" to see all properties, and "B.Uncertainty" to interact with the uncertain elements. ```

To set multiple elements, list individually, or group the values in a data structure. For instance, the following code creates identical uncertain matrices `B1` and `B2`. In each case, you replace `delta` by 2.3, and `eta` by the uncertain real parameter `A.Uncertainty.rho`.

`B1 = usubs(A,'delta',2.3,'eta',A.Uncertainty.rho)`
```B1 = Uncertain matrix with 2 rows and 2 columns. The uncertainty consists of the following blocks: rho: Uncertain real, nominal = -1, variability = [-1,1], 4 occurrences Type "B1.NominalValue" to see the nominal value, "get(B1)" to see all properties, and "B1.Uncertainty" to interact with the uncertain elements. ```
```S.delta = 2.3; S.eta = A.Uncertainty.rho; B2 = usubs(A,S)```
```B2 = Uncertain matrix with 2 rows and 2 columns. The uncertainty consists of the following blocks: rho: Uncertain real, nominal = -1, variability = [-1,1], 4 occurrences Type "B2.NominalValue" to see the nominal value, "get(B2)" to see all properties, and "B2.Uncertainty" to interact with the uncertain elements. ```

`usubs` ignores substitutions that do not match uncertain parameters in the model or matrix. For example, the following returns an uncertain matrix that is the same as `A`.

`B3 = usubs(A,'fred',5); `

### Specifying the Substitution with Structures

An alternative syntax for `usubs` is to specify the substituted values in a structure, whose field names are the names of the elements being substituted with values. For example, create a structure `NV` with fields `delta` and `eta`. Set the values of these fields to be the desired values for substitution. Then perform the substitution with `usubs`.

```NV.delta = 2.3; NV.eta = A.Uncertainty.rho; B4 = usubs(A,NV)```
```B4 = Uncertain matrix with 2 rows and 2 columns. The uncertainty consists of the following blocks: rho: Uncertain real, nominal = -1, variability = [-1,1], 4 occurrences Type "B4.NominalValue" to see the nominal value, "get(B4)" to see all properties, and "B4.Uncertainty" to interact with the uncertain elements. ```

Here, `B4` is the same as `B1` and `B2` above. Again, any superfluous fields are ignored. Therefore, adding an additional field `gamma` to `NV` does not alter the result of substitution.

```NV.gamma = 0; B5 = usubs(A,NV)```
```B5 = Uncertain matrix with 2 rows and 2 columns. The uncertainty consists of the following blocks: rho: Uncertain real, nominal = -1, variability = [-1,1], 4 occurrences Type "B5.NominalValue" to see the nominal value, "get(B5)" to see all properties, and "B5.Uncertainty" to interact with the uncertain elements. ```

`B5` is the same as `B4`.

Analysis commands such as `wcgain`, `robstab`, and `usample` all return substitutable values in this structure format.

### Nominal and Random Values

To fix specified elements to their nominal values, use the replacement value `'Nominal'`. To set an element to a random value, use `'Random'`. For example, create a numeric matrix by fixing uncertain parameters in `A`: Set `eta` to its nominal value, set `delta` to a random value, and set `rho` to 6.5.

`B6 = usubs(A,'eta','Nominal','delta','Random','rho',6.5) `
```B6 = 2×2 11.6294 0.4382 13.5000 22.2767 ```

In the structure format, to set an uncertain element to its nominal value, set the corresponding value in the structure.

```S = struct('eta',A.Uncertainty.eta.NominalValue,'rho',6.5); B7 = usubs(A,S)```
```B7 = Uncertain matrix with 2 rows and 2 columns. The uncertainty consists of the following blocks: delta: Uncertain real, nominal = 2, variability = [-1,1], 2 occurrences Type "B7.NominalValue" to see the nominal value, "get(B7)" to see all properties, and "B7.Uncertainty" to interact with the uncertain elements. ```

Use `usample` to set the remaining element to a random value.

`B8 = usample(B7,'delta',1)`
```B8 = 2×2 11.8116 0.4686 13.5000 23.3695 ```