usubs

Substitute given values for uncertain elements of uncertain objects

Syntax

```B = usubs(M,ElementName1,value1,ElementName2,value2,...) B = usubs(M,S) B = usubs(M,...,'-once') B = usubs(M,...,'-batch') ```

Description

Use `usubs` to substitute a specific value for an uncertain element of an uncertain model object. The value can itself be uncertain. It needs to be the correct size, but otherwise can be of any class, and can be an array. Hence, the result can be of any class. In this manner, uncertain elements act as symbolic placeholders, for which specific values (which can also contain other placeholders too) can be substituted.

`B = usubs(M,ElementName1,value1,ElementName2,value2,...)` sets the elements in `M`, identified by `ElementName1`, `ElementName2`, etc., to the values in `value1`, `value2`, etc. respectively.

You can also use the character vectors `'NominalValue'` or `'Random'` as any `value` argument. If you do so, the nominal value or a random instance of the uncertain element is used. You can partially specify these character vectors, instead of typing the full expression. For example, you can use `'Nom'` or `'Rand'`.

`B = usubs(M,S)` instantiates the uncertain elements of `M` to the values specified in the structure `S`. The field names of `S` are the names of the uncertain elements to replace. The values are the corresponding replacement values. To provide several replacement values, make `S` a struct array, where each struct contains one set of replacement values. A structure such as `S` typically comes from robustness analysis commands such as `robstab`, `usample`, or `wcgain`.

`B = usubs(M,...,'-once')` performs vectorized substitution in the uncertain model array `M`. Each uncertain element is replaced by a single value, but this value may change across the model array. To specify different substitute values for each model in the array `M`, use:

• A cell array for each `valueN` that causes the uncertain element `ElementNameN` in `M(:,:,k)` to be replaced by `valueN(k)`. For example, if `M` is a 2-by-3 array, then a 2-by-3 cell array `value1` replaces `ElementName1` of the model `M(:,:,k)` with the corresponding `value1(k)`.

• A struct array `S` that specifies one set of substitute values `S(k)` for each model `M(:,:,k)`.

Numeric array formats are also accepted for `value1,value2,...`. For example, `value1` can be a 2-by-3 array of LTI models, a numeric array of size `[size(name1) 2 3]`, or a 2-by-3 matrix when the uncertain element `name1` is scalar-valued. The array sizes of `M`, `S`, `value1,value2,...` must agree along non-singleton dimensions. Scalar expansion takes place along singleton dimensions.

Vectorized substitution (`'-once'`) is the default for model arrays when no substitution method is specified.

`B = usubs(M,...,'-batch')` performs batch substitution in the uncertain model array `M`. Each uncertain element is replaced by an array of values, and the same values are used for all models in `M`. In batch substitution, `B` is a model array of size `[size(M) VS]`, where `VS` is the size of the array of substitute values.

Examples

collapse all

Evaluate an uncertain matrix at several different values of the uncertain parameters of the matrix.

Create an uncertain matrix with two uncertain parameters.

```a = ureal('a',5); b = ureal('b',-3); M = [a b];```

Evaluate the matrix at four different combinations of values for the uncertain parameters `a` and `b`.

`B = usubs(M,'a',[1;2;3;4],'b',[10;11;12;13]);`

This command evaluates `M` for the four different (`a`, `b`) combinations (1,10), (2,11), and so on. Therefore, `B` is a 1-by-2-by-4 array of numeric values containing the four evaluated values of `M`.

Evaluate an uncertain matrix over a 3-by-4 grid of values of the uncertain parameters of the matrix.

Create a 2-by-2 uncertain matrix with two uncertain parameters.

```a = ureal('a',5); b = ureal('b',-3); M = [a b;0 a*b];```

Build arrays of values for the uncertain parameters.

```aval = [1;2;3;4]; bval = [10;20;30]; [as,bs] = ndgrid(aval,bval);```

This command builds two 4-by-3 grids of values.

Evaluate M over the parameter grids `A` and `B`.

`B = usubs(M,'a',as,'b',bs);`

This command evaluates `M` for each four different combination of values `(A(k),B(k))`. `B` is a 2-by-2-by-4-by-3 array of numeric values, which is a 4-by-3 array of values of `M`, i.e., `M` evaluated over the parameter grids.

Evaluate an array of uncertain models, substituting an array of values for an uncertain parameter.

Create a 1-by-2 uncertain matrix with two uncertain parameters.

```a = ureal('a',5); b = ureal('b',-3); M = [a b];```

Replace `a` by each of the values 1, 2, 3, and 4.

`Ma = usubs(M,'a',[1;2;3;4]);`

This command returns a 4-by-1 array of 1-by-2 uncertain matrices that contain one uncertain parameter `b`.

For each model in the array `Ma`, evaluate `b` at 10, 20, and 30.

`B = usubs(Ma,'b',[10;20;30],'-batch');`

The `'-batch'` flag causes `usubs` to evaluate each model in the array at all three values of `b`. Thus `B` is a 4-by-3 array of `M` values.

The `'-batch'` syntax here yields the same result as the parameter grid approach used in the previous example:

```aval = [1;2;3;4]; bval = [10;20;30]; [as,bs] = ndgrid(aval,bval); B = usubs(M,'a',as,'b',bs);```

Evaluate an array of uncertain models, substituting a different value for the uncertain parameter in each entry in the array.

Create a 1-by-2 uncertain matrix with two uncertain parameters.

```a = ureal('a',5); b = ureal('b',-3); M = [a b];```

Replace `a` by each of the values 1, 2, 3, and 4.

`Ma = usubs(M,'a',[1;2;3;4]);`

This command returns a 4-by-1 array of 1-by-2 uncertain matrices that contain one uncertain parameter `b`.

For each model in the array `Ma`, evaluate `b`. Use `b = 10` for the first entry in the array, `b = 20` for the second entry, and so on.

`B = usubs(Ma,'b',{10;20;30;40},'-once');`

The `'-once'` flag causes `usubs` to evaluate the first model in the array using the first specified value for `b`, the second model for the second specified value, etc.

Replace the uncertain parameters in an uncertain models by values specified in struct array form, as returned by `usample`.

This is useful, for example, when you have multiple uncertain models that use the same set of parameters, and you want to evaluate all models at the same parameter values.

Create two uncertain matrices that have the same uncertain parameters, `a` and `b`.

```a = ureal('a',5); b = ureal('b',-3); M1 = [a b]; M2 = [a b;0 a*b];```

Generate some random samples of `M1`.

`[M1rand,samples] = usample(M1,5);`

`M1rand` is an array of five values of `M1`, evaluated at randomly generated values of `a` and `b`. These `a` and `b` values are returned in the struct array `samples`.

Examine the struct array `samples`.

`samples`
```samples=5×1 struct array with fields: a b ```

The field names of `samples` correspond to the uncertain parameters of `M1`. The values are the parameter values used to generate `M1rand`. Because `M2` has the same parameters, you can use this structure to evaluate `M2` at the same set of values.

`M2rand = usubs(M2,samples);`

This command returns a 1-by-5 array of instantiations of `M2`.

Version History

Introduced before R2006a