# 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`

## Version History

Introduced in R2011a
{"extraction_info": {"found_math": true, "script_math_tex": 0, "script_math_asciimath": 0, "math_annotations": 0, "math_alttext": 0, "mathml": 6, "mathjax_tag": 0, "mathjax_inline_tex": 0, "mathjax_display_tex": 0, "mathjax_asciimath": 0, "img_math": 0, "codecogs_latex": 0, "wp_latex": 0, "mimetex.cgi": 0, "/images/math/codecogs": 0, "mathtex.cgi": 0, "katex": 0, "math-container": 0, "wp-katex-eq": 0, "align": 0, "equation": 0, "x-ck12": 0, "texerror": 0, "math_score": 0.5727974772453308, "perplexity": 1783.15020599894}, "config": {"markdown_headings": true, "markdown_code": true, "boilerplate_config": {"ratio_threshold": 0.18, "absolute_threshold": 20, "end_threshold": 15, "enable": true}, "remove_buttons": true, "remove_image_figures": true, "remove_link_clusters": true, "table_config": {"min_rows": 2, "min_cols": 3, "format": "plain"}, "remove_chinese": true, "remove_edit_buttons": true, "extract_latex": true}, "warc_path": "s3://commoncrawl/crawl-data/CC-MAIN-2022-27/segments/1656104628307.87/warc/CC-MAIN-20220705205356-20220705235356-00386.warc.gz"}