sampleBlock

Sample Control Design blocks in generalized model

Syntax

Msamp = sampleBlock(M,name,vals)

Msamp = sampleBlock(M,nameset,valset)

Msamp = sampleBlock(M,nameset1,valset1,nameset2,valset2,...,namesetM,valsetM)

[Msamp,samples] = sampleBlock(___)

Description

Msamp = sampleBlock(M,name,vals) samples one Control Design block in the generalized model M. The result Msamp is a model array of size [size(M) N] obtained by replacing the block with the specified values, where N is the number of values in vals.

Msamp = sampleBlock(M,nameset,valset) concurrently samples multiple blocks specified as a cell array of block names. valset is a cell array of N sample values for each block. The result Msamp is a model array of size [size(M) N].

Msamp = sampleBlock(M,nameset1,valset1,nameset2,valset2,...,namesetM,valsetM) independently samples multiple blocks. nameset1,nameset2,...,namesetM can each be a single block name (see name) or a cell array of names (see nameset). The model M is sampled over a grid of size [N1 N2 ... NM], where N1 is the number of values in valset1, N2 is the number of values in valset2, and so on. The resulting Msamp is an array of size [size(M) N1 N2 ... NM].

[Msamp,samples] = sampleBlock(___) also returns a data structure containing the block replacement values for each sampling point. You can use this syntax with any of the preceding input argument combinations.

Examples

Sample Real Parameter in Tunable Model

Create the first-order model $$G\left(s\right)=1/\left(\tau s+1\right)$$, where $$\tau$$ is a tunable real parameter.

tau = realp('tau',5);
G = tf(1,[tau 1]);

Evaluate this transfer function for $$\tau$$ = 3,4,..,7. The result is a 5-by-1 array of first-order models.

Gs = sampleBlock(G,'tau',3:7);
size(Gs)

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

Sample Multiple Parameters in Tunable Model

Create a model with a pole at s = a and a gain of b*c, where a, b, and c are tunable scalars.

a = realp('a',1);  
b = realp('b',3);  
c = realp('c',1);
G = tf(b*c,[1 a]);

Pick 5 samples for a and 3 samples for (b,c) pairs. Evaluate G over the corresponding 5-by-3 grid of (a,b,c) combinations.

as = 0.8:0.1:1.2;
bs = 2:4;
cs = [0.5 1 1.5];
Gs = sampleBlock(G,'a',as,{'b','c'},{bs,cs});

Grouping the values for b and c in cell arrays causes sampleBlock to treat them as the (b,c) pairs, (2,0.5), (3,1), and (1,5). Gs is a 5-by-3 array of state-space models, in which a varies along the first dimension and (b,c) varies along the second dimension. Thus, for example, Gs(:,:,3,2) corresponds to a = 1, (b,c) = (3,1).

A step plot shows a set of responses for each of the three (b,c) pairs. Each set contains a response for each of the five a values.

stepplot(Gs)

If you do not group the values, sampleBlock replaces all values independently, resulting in a 5-by-3-by-3 model array.

GsInd = sampleBlock(G,'a',as,'b',bs,'c',cs);
size(GsInd)

5x3x3 array of state-space models.
Each model has 1 outputs, 1 inputs, and 1 states.

For example, in GsInd, Gs(:,:,3,2,1) is a model with a = 1, b = 3, and c = 0.5.

Input Arguments

M — Model to sample

generalized model | uncertain model | generalized matrix | uncertain matrix

Model to sample, specified as a:

• Generalized model (genss or genfrd)

• Generalized matrix (genmat)

• Uncertain model (uss (Robust Control Toolbox) or ufrd (Robust Control Toolbox))

• Uncertain matrix (umat (Robust Control Toolbox))

name — Control Design block

character vector

Control Design block to sample, specified as a character vector. For example, suppose that M is a genss model with tunable blocks t1 and t2. Then, either 't1' or 't2' is a possible value for name.

vals — Sample block values

numeric array | model array

Sample block values, specified as a numeric array or a model array. Values must be compatible with the block type. For example, if name is a tunable real parameter (realp), then vals is a numerical array of length N, the number of samples. If name is a tunable PID controller (tunablePID), then vals is an array of LTI models compatible with PID structure.

nameset — Control Design blocks

cell array of character vectors

Control Design blocks to sample concurrently, specified as cell array of character vectors. The entries in nameset correspond to the names of at least a subset of the Control Design blocks in M. For example, suppose that M is a genss model with tunable blocks t1 and t2, and uncertain blocks u1 and u2. Then, {'t1','u2'} is one possible value for nameset.

Grouping block names together in a cell array generates samples of the group rather than independent samples. For example, the following code generates a 10-by-1 array of models, where each entry in the array has the corresponding value for the pair (t1,u2).

t1s = 1:10;
u2s = 2:2:20;
valset = {t1s,t2s};
Msamp = sampleBlock(M,{'t1','u2'},valset);

sampleBlock ignores any entry in nameset that does not appear in M.

valset — Sample block values

cell array

Sample block values, specified as a cell array. Each entry in the cell array is itself an array of N sample values for each block in nameset. For example, the following code samples a model M at the (t1,u2) pairs (1,2), (2,4), ... (10,20).

t1s = 1:10;
u2s = 2:2:20;
valset = {t1s,t2s};
Msamp = sampleBlock(M,{'t1','u2'},valset);

Values in valset must be compatible with the corresponding block type.

Output Arguments

Msamp — Array of model samples

generalized model array | ss array | frd array | numeric array

Array of model samples, returned as a generalized model array, ss array, frd array, or numeric array. Msamp is of the same type as M, unless all blocks are sampled. In that case, Msamp is a numeric array, ss array, or frd array. For example, suppose that M is a uss model with uncertain blocks u1 and u2. The following command returns an array of uss models, with uncertain block u2.

Msamp1 = sampleBlock(M,'u1',1:10);

The following command samples both blocks and returns an array of ss models.

Msamp2 = sampleBlock(M,{'u1','u2'},{1:10,2:20});

samples — Block sample values

structure

Block sample values, returned as a structure. The fields of samples are the names of the sampled blocks. The values are arrays containing the corresponding values used to generate the entries in Msamp.

Version History

Introduced in R2016a