# replaceBlock

Replace or update Control Design Blocks in Generalized LTI model

## Syntax

```Mnew = replaceBlock(M,Block1,Value1,...,BlockN,ValueN) Mnew = replaceBlock(M,blockvalues) Mnew = replaceBlock(...,mode) ```

## Description

`Mnew = replaceBlock(M,Block1,Value1,...,BlockN,ValueN)` replaces the Control Design Blocks `Block1,...,BlockN` of `M` with the specified values `Value1,...,ValueN`. `M` is a Generalized LTI model or a Generalized matrix.

`Mnew = replaceBlock(M,blockvalues)` specifies the block names and replacement values as field names and values of the structure `blockvalues`.

`Mnew = replaceBlock(...,mode)` performs block replacement on an array of models `M` using the substitution mode specified by `mode`.

## Input Arguments

 `M` Generalized LTI model, Generalized matrix, or array of such models. `Block1,...,BlockN` Names of Control Design Blocks in `M`. The `replaceBlock` command replaces each listed block of `M` with the corresponding values `Value1,...,ValueN` that you supply. If a specified `Block` is not a block of `M`, `replaceBlock` that block and the corresponding value. `Value1,...,ValueN` Replacement values for the corresponding blocks `Block1,...,BlockN`. The replacement value for a block can be any value compatible with the size of the block, including a different Control Design Block, a numeric matrix, or an LTI model. If any value is `[]`, the corresponding block is replaced by its nominal (current) value. `blockvalues` Structure specifying blocks of `M` to replace and the values with which to replace those blocks. The field names of `blockvalues` match names of Control Design Blocks of `M`. Use the field values to specify the replacement values for the corresponding blocks of `M`. The replacement values may be numeric values, Numeric LTI models, Control Design Blocks, or Generalized LTI models. `mode` Block replacement mode for an input array `M` of Generalized matrices or LTI models, specified as one of the following values: `'-once'` (default) — Vectorized block replacement across the model array `M`. Each block is replaced by a single value, but the value may change from model to model across the array. For vectorized block replacement, use a structure array for the input `blockvalues`, or cell arrays for the `Value1,...,ValueN` inputs. For example, if `M` is a 2-by-3 array of models:`Mnew = replaceBlock(M,blockvalues,'-once')`, where `blockvalues` is a 2-by-3 structure array, specifies one set of block values `blockvalues(k)` for each model `M(:,:,k)` in the array.`Mnew = replaceBlock(M,Block,Value,'-once')`, where `Value` is a 2-by-3 cell array, replaces `Block` by `Value{k}` in the model `M(:,:,k)` in the array.`'-batch'` — Batch block replacement. Each block is replaced by an array of values, and the same array of values is used for each model in `M`. The resulting array of model `Mnew` is of size ```[size(M) Asize]```, where `Asize` is the size of the replacement value. When the input `M` is a single model, `'-once'` and `'-batch'` return identical results. Default: `'-once'`

## Output Arguments

 `Mnew` Matrix or linear model or matrix where the specified blocks are replaced by the specified replacement values. `Mnew` is a numeric array or numeric LTI model when all the specified replacement values are numeric values or numeric LTI models.

## Examples

### Replace Control Design Block with Numeric Values

This example shows how to replace a tunable PID controller (`tunablePID`) in a Generalized LTI model by a pure gain, a numeric PI controller, or the current value of the tunable controller.

1. Create a Generalized LTI model of the following system:

where the plant $G\left(s\right)=\frac{\left(s-1\right)}{{\left(s+1\right)}^{3}}$, and C is a tunable PID controller.

```G = zpk(1,[-1,-1,-1],1); C = tunablePID('C','pid'); Try = feedback(G*C,1)```
2. Replace `C` by a pure gain of 5.

`T1 = replaceBlock(Try,'C',5);`

`T1` is a `ss` model that equals `feedback(G*5,1)`.

3. Replace `C` by a PI controller with proportional gain of 5 and integral gain of 0.1.

```C2 = pid(5,0.1); T2 = replaceBlock(Try,'C',C2);```

`T2` is a `ss` model that equals `feedback(G*C2,1)`.

4. Replace `C` by its current (nominal) value.

`T3 = replaceBlock(Try,'C',[]);`

`T3` is a `ss` model where `C` has been replaced by `getValue(C)`.

### Sample Tunable Model Over Grid of Values

Consider the second-order filter represented by:

`$F\left(s\right)=\frac{{\omega }_{n}^{2}}{{s}^{2}+2\zeta {\omega }_{n}s+{\omega }_{n}^{2}}.$`

Sample this filter at varying values of the damping constant $\zeta$ and the natural frequency ${\omega }_{n}$. Create a tunable model of the filter by using tunable elements for $\zeta$ and ${\omega }_{n}$.

```wn = realp('wn',3); zeta = realp('zeta',0.8); F = tf(wn^2,[1 2*zeta*wn wn^2])```
```F = Generalized continuous-time state-space model with 1 outputs, 1 inputs, 2 states, and the following blocks: wn: Scalar parameter, 5 occurrences. zeta: Scalar parameter, 1 occurrences. Type "ss(F)" to see the current value, "get(F)" to see all properties, and "F.Blocks" to interact with the blocks. ```

Create a grid of sample values.

```wnvals = [3;5]; zetavals = [0.6 0.8 1.0]; [wngrid,zetagrid] = ndgrid(wnvals,zetavals); Fsample = replaceBlock(F,'wn',wngrid,'zeta',zetagrid); size(Fsample)```
```2x3 array of state-space models. Each model has 1 outputs, 1 inputs, and 2 states. ```

The ndgrid command produces a full 2-by-3 grid of parameter combinations. Thus, `Fsample` is a 2-by-3 array of state-space models. Each entry in the array is a state-space model that represents `F` evaluated at the corresponding (`wn`, `zeta`) pair. For example, `Fsample(:,:,2,3)` has `wn` = 5 and `zeta` = 1.0.

`damp(Fsample(:,:,2,3))`
``` Pole Damping Frequency Time Constant (rad/seconds) (seconds) -5.00e+00 1.00e+00 5.00e+00 2.00e-01 -5.00e+00 1.00e+00 5.00e+00 2.00e-01 ```

## Tips

• Use `replaceBlock` to perform parameter studies by sampling Generalized LTI models across a grid of parameters, or to evaluate tunable models for specific values of the tunable blocks. See Examples.

• For additional options for sampling control design blocks, including concurrent sampling, use `sampleBlock`.

• To take random samples of control design blocks, see `rsampleBlock`