usubs

Substitute given values for uncertain elements of uncertain objects

Syntax

B = usubs(M,ElementName1,value1,...,ElementNameN,valueN)

B = usubs(M,S)

B = usubs(M,___,"-once")

B = usubs(M,___,"-batch")

Description

B = usubs(M,ElementName1,value1,...,ElementNameN,valueN) sets the specified uncertain elements in an uncertain system or matrix M to the specified values. For instance, you can use usubs to replace uncertain parameters in a uss model by particular numeric values. You can also generate an array of instantiations of M by specifying an array of substitute values.

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. This syntax is useful when you when have multiple uncertain models that use the same set of parameters, and you want to evaluate all models at the same parameter values. It is also useful for substitution of values obtained with robustness analysis commands such as robstab, usample, or wcgain. To provide several replacement values, make S a struct array, where each struct contains one set of replacement values.

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:

• An array for each valueN that causes usubs to replace the uncertain element ElementNameN in M(:,:,k) 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 a 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

Evaluate Uncertain Model for Multiple Values of Uncertain Parameters

Evaluate an uncertain state-space model at several different values of its uncertain parameters.

Create a state-space model with two uncertain entries in its A matrix.

p1 = ureal("p1",-8);
p2 = ureal("p2",-2);
A = [p1 p2; -5 -12];
B = [7; -1];
C = [0 -2];
D = 0;
M = ss(A,B,C,D)

Uncertain continuous-time state-space model with 1 outputs, 1 inputs, 2 states.
The model uncertainty consists of the following blocks:
  p1: Uncertain real, nominal = -8, variability = [-1,1], 1 occurrences
  p2: Uncertain real, nominal = -2, variability = [-1,1], 1 occurrences
Model Properties

Type "M.NominalValue" to see the nominal value and "M.Uncertainty" to interact with the uncertain elements.

Evaluate the model at four different combinations of values for the uncertain parameters p1 and p2.

B = usubs(M,"p1",[-8.4;-8.2;-8.0;-7.8],"p2",[-2.2;-2.1;-2.0;-1.0]);

This command evaluates M for the four different (p1,p2) combinations (-8.4,-2.2), (-8.2,-2.1), and so on. Therefore, B is an array of four numeric state-space models.

size(B)

4x1 array of state-space models.
Each model has 1 outputs, 1 inputs, and 2 states.

Evaluate Uncertain Matrix over Grid of Uncertain Parameters

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.

p1 = ureal("p1",5);
p2 = ureal("p2",-3);
M = [p1 p2;0 p1*p2];

Build arrays of values for the uncertain parameters.

p1val = [1;2;3;4];
p2val = [10;20;30];
[p1s,p2s] = ndgrid(p1val,p2val);

This command builds two 4-by-3 grids of values, representing all possible combinations of values (p1val,p2val). Evaluate M over these parameter grids.

B = usubs(M,"p1",p1s,"p2",p2s);

The of evaluating the 2-by-2 matrix M over a 4-by-3 grid of values is a 4-by-3 array of values of M, that is, a 2-by-2-by-4-by-3 array.

size(B)

ans = 1×4

     2     2     4     3

Batch Substitute Uncertain Parameter with Array of Values

You can substitute an array of values for a parameter in an uncertain element, expanding the element into an array with as many entries as in the substitute array. For example, consider a 1-by-2 uncertain matrix with two uncertain parameters.

p1 = ureal("p1",5);
p2 = ureal("p2",-3);
M = [p1 p2;0 p1*p2];

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

M1 = usubs(M,"p1",[1;2;3;4])

4x1 array of uncertain matrices with 2 rows, 2 columns, and the following uncertain blocks:
  p2: Uncertain real, nominal = -3, variability = [-1,1], 1 occurrences
Model Properties

Type "M1.NominalValue" to see the nominal value and "M1.Uncertainty" to interact with the uncertain elements.

This command returns a 4-by-1 array of 1-by-2 uncertain matrices that contain one uncertain parameter, p2. Each entry in this array is M evaluated at one of the four entries [1;2;3;4].

For each model in the array M1, evaluate p2 at 10, 20, and 30.

B = usubs(M1,"p2",[10;20;30],"-batch");

The "-batch" flag again causes usubs to evaluate each of the four models in M1 at all three values of p2. Thus B is a 4-by-3 array of M values, that is, a 2-by-2-by-4-by-3 array.

size(B)

ans = 1×4

     2     2     4     3

The "-batch" syntax here yields the same result as the parameter grid approach used in the previous example.

p1val = [1;2;3;4];
p2val = [10;20;30];
[p1s,p2s] = ndgrid(p1val,p2val);
B = usubs(M,"p1",p1s,"p2",p2s);

Elementwise Substitution of Uncertain Parameters

Evaluate an array of uncertain models, substituting a different value for the uncertain parameters for each entry in the array, rather than expanding the array .

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

p1 = ureal("p1",5);
p2 = ureal("p2",-3);
M = [p1 p2];

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

M1 = usubs(M,"p1",[1;2;3;4]);
size(M1)

4x1 array of uncertain matrices.
Each matrix has 1 rows, 2 columns, and 1 blocks.

Because M is a single matrix, replacing an uncertain parameter in the model expands the matrix into an array of four matrices. Thus, M1 is a 4-by-1 array of 1-by-2 uncertain matrices that contain one uncertain parameter p2.

Next, for each model in the array M1, evaluate p2. Use p2 = 10 for the first entry in the array, p2 = 20 for the second entry, and so on.

M2 = usubs(M1,'p2',[10;20;30;40],"-once");

The "-once" flag causes usubs to evaluate the first model in the array using the first specified value for p2, the second model for the second specified value, etc. The result is still a 4-by-1 array of 1-by-2 matrices. When you use the "-once" flag, the array of substitute values must match at least a subset of the dimensions of the input array.

Replace Uncertain Parameters with Sampled Values

Replace the uncertain parameters in an uncertain models by sampled values specified in an array of structures as returned by usample. This type of substitution can be 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, p1 and p2.

p1 = ureal("p1",5);
p2 = ureal("p2",-3);
M1 = [p1 p2];
M2 = [p1 p2;0 p1*p2];

Generate some random samples of M1.

[M1r,samples] = usample(M1,5);

M1r is an array of five values of M1, evaluated at randomly generated values of p1 and p2. The samples p1 and p2 values are returned in the structure array samples.

samples

samples=5×1 struct array with fields:
    p1
    p2

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

M2r = usubs(M2,samples);

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

Input Arguments

M — Uncertain matrix or system

uss | ufrd | umat | genss | genfrd | genmat

Uncertain matrix or system, specified as an uncertain state-space model (uss), uncertain frequency response data model (ufrd), or uncertain matrix (umat), or as a generalized state-space model (genss), generalized frequency response data model (genfrd), or generalized matrix (genmat) with uncertain elements. M can also be an array of uncertain models or matrices.

ElementName — Uncertain element to substitute

string | character vector

Uncertain element to substitute, specified as a string or character vector corresponding to the Name property of an uncertain element of M. If M does not contain an element with name ElementName, then usubs ignores that name. You can specify multiple element names by supplying multiple ElementName,value pairs. For instance, usubs(M,"A",3,"B",5) returns M with all instances of the uncertain parameter A replaced by the value 3 and all instances of B replaced by the value 5.

value — Value to substitute

scalar | array | dynamic system model | "NominalValue""Random" | ...

Value to substitute for the corresponding uncertain element in M, specified by a scalar, array, a dynamic system model (when the uncertain element represents uncertain dynamics), or any other value that represents a meaningful possible value for the uncertain element to take.

If you specify an array of substitute values for an element:

• For scalar M, the function generates an array of instantiations of M, with each entry in the array consisting of M evaluated at the corresponding entry in value.

• For array M with the "-once" flag or no flag specified, usubs performs vectorized (element-by-element) replacement, instantiating each entry of M with a different entry in value.

• For array M with the "-batch" flag, usubs expands M into a larger array, replacing the uncertain element with the full array of specified values.

For any uncertain element, you can use the strings "NominalValue" or "Random" to replace the element by its nominal value or a random value, respectively.

S — Elements and values to substitute

structure | structure array

Elements and values to substitute, specified as a structure or structure array whose fields are the names of the uncertain elements to substitute and whose values are the substitutions.

Output Arguments

B — Evaluated matrix or model

uncertain matrix | uncertain dynamic system model | numeric array | numeric LTI model

Evaluated matrix or model, returned as an uncertain matrix, uncertain dynamic system, numeric LTI model, or an array of any of these data types. The type and dimensions of B depend on the dimensions of input M, the uncertain elements you replace, and the dimensions of the specified replacement values.

Version History

Introduced before R2006a