# rsampleBlock

Randomly sample Control Design blocks in generalized model

## Syntax

``Msamp = rsampleBlock(M,names,N)``
``Msamp = rsampleBlock(M,names1,N1,names2,N2,...,namesM,NM)``
``````[Msamp,samples] = rsampleBlock(___)``````

## Description

example

````Msamp = rsampleBlock(M,names,N)` randomly samples a subset of the Control Design blocks in the generalized model `M`. The `names` argument specifies which blocks to sample, and `N` specifies how many samples to take. The result `Msamp` is a model array of size `[size(M) N]` obtained by replacing the sampled blocks with their randomized values.```

example

````Msamp = rsampleBlock(M,names1,N1,names2,N2,...,namesM,NM)` takes `N1` samples of the blocks listed in `names1`, `N2` samples of the blocks listed in `names2`, and so on. The result `Msamp` is a model array of size ```[size(M) N1 N2 ... NM]```.```
``````[Msamp,samples] = rsampleBlock(___)``` 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

collapse all

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]);```

Restrain `tau` to nonnegative values only.

`G.Blocks.tau.Minimum = 0;`

Generate 20 random samples of `G`. The result is a 20-by-1 array of first-order models with random values of `tau` taken from the range of `tau`.

```Gs = rsampleBlock(G,'tau',20); size(Gs)```
```20x1 array of state-space models. Each model has 1 outputs, 1 inputs, and 1 states. ```

Take random samples of a model with both tunable and uncertain blocks. Using uncertain blocks requires Robust Control Toolbox™. Random sampling of tunable blocks works the same way as shown in this example.

Create an uncertain model of $G\left(s\right)=a/\left(\tau s+1\right)$, where a is an uncertain parameter that varies in the interval [3,5], and $\tau$ = 0.5 +/- 30%. Also, create a tunable PI controller, and form a closed-loop system from the tunable controller and uncertain system.

```a = ureal('a',4); tau = ureal('tau',.5,'Percentage',30); G = tf(a,[tau 1]); C = tunablePID('C','pi'); T = feedback(G*C,1);```

T is a generalized state-space model with two uncertain blocks, `a` and `tau`, and one tunable block, `C`. Sample `T` at 20 random `(a,tau)` pairs.

`[Ts,samples] = rsampleBlock(T,{'a','tau'},20);`

`Ts` is a 20-by-1 array of `genss` models. The tunable block `C`, which is not sampled, is preserved in `Ts`. The structure `samples` has fields `samples.a` and `samples.tau` that contain the values at which those blocks are sampled.

Grouping `a` and `tau` into a cell array causes `rsampleBlock` to sample them together, as `(a,tau)` pairs. Sampling the blocks independently generates a higher-dimensionality arrays. For example, independently taking 10 random samples of `a` and 5 samples of `tau` generates a 10-by-5 model array.

```[TsInd,samples] = rsampleBlock(T,'a',10,'tau',5); TsInd```
```TsInd = 10x5 array of generalized continuous-time state-space models. Each model has 1 outputs, 1 inputs, 2 states, and the following blocks: C: Tunable PID controller, 1 occurrences. Type "ss(TsInd)" to see the current value, "get(TsInd)" to see all properties, and "TsInd.Blocks" to interact with the blocks. ```

In this array, `a` varies along one dimension and `tau` varies along the other.

## Input Arguments

collapse all

Model to sample, specified as a:

Control Design blocks to sample, specified as a character vector or cell array of character vectors. The entries in `names` 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 `names`.

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

`Msamp = rsampleBlock(M,{'t1','u2'},10);`

To sample parameters independently, do not group them. For example, the following code generates a 10-by-20 array of models, where `t1` varies along the first dimension and `u2` varies along the second dimension.

`Msamp = rsampleBlock(M,'t1',10,'u2',20);`

`rsampleBlock` ignores any entry in `names` that does not appear in `M`.

Number of samples to take of the preceding block or blocks, specified as a positive integer.

## Output Arguments

collapse all

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 = rsampleBlock(M,'u1',10);`

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

`Msamp2 = rsampleBlock(M,{'u1','u2'},10);`

`rsampleBlock` uses values that fall within the uncertainty range when sampling uncertain blocks, and within the maximum and minimum parameter values when sampling tunable blocks.

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 random values used to generate the entries in `Msamp`. For instance, suppose that you run the following command, where `M` is a `genss` model with tunable blocks `t1` and `t2`.

`[Msamp,samples] = rsampleBlock(M,{'t1','t2'},10);`

Then, `samples.t1` contains the 10 values of `t1` and `samples.t2` contains the 10 values of `t2`. If you sample a block that is not scalar valued, the corresponding field of `samples` contains values compatible with the block. For instance, if you sample a `tunablePID` block, `samples` contains an array of state-space models that represent PID controllers.

## Version History

Introduced in R2016a