# tunableGain

Tunable static gain block

## Syntax

```blk = tunableGain(name,Ny,Nu) blk = tunableGain(name,G) ```

## Description

Model object for creating tunable static gains. `tunableGain` lets you parametrize tunable static gains for parameter studies or for automatic tuning with tuning commands such as `systune` or `looptune`.

`tunableGain` is part of the Control Design Block family of parametric models. Other Control Design Blocks include `tunablePID`, `tunableSS`, and `tunableTF`.

## Construction

`blk = tunableGain(name,Ny,Nu)` creates a parametric static gain block named `name`. This block has `Ny` outputs and `Nu` inputs. The tunable parameters are the gains across each of the `Ny`-by-`Nu` I/O channels.

`blk = tunableGain(name,G)` uses the double array `G` to dimension the block and initialize the tunable parameters.

### Input Arguments

 `name` Block `Name`, specified as a character vector such as `'K'` or `'gain1'`. (See Properties.) `Ny` Non-negative integer specifying the number of outputs of the parametric static gain block `blk`. `Nu` Non-negative integer specifying the number of inputs of the parametric static gain block `blk`. `G` Double array of static gain values. The number of rows and columns of `G` determine the number of inputs and outputs of `blk`. The entries `G` are the initial values of the parametric gain block parameters.

## Properties

`Gain`

Parametrization of the tunable gain.

`blk.Gain` is a `param.Continuous` object. For general information about the properties of the `param.Continuous` (Simulink Design Optimization) object `blk.Gain`, see the `param.Continuous` object reference page.

The following fields of `blk.Gain` are used when you tune `blk` using `hinfstruct`:

FieldDescription
`Value`

Current value of the gain matrix. For a block that has `Ny` outputs and `Nu` inputs, `blk.Gain.Value` is a `Ny`-by-`Nu` matrix.

If you use the `G` input argument to create `blk`, `blk.Gain.Value` initializes to the values of `G`. Otherwise, all entries of `blk.Gain.Value` initialize to zero.

`hinfstruct` (Robust Control Toolbox) tunes all entries in `blk.Gain.Value` except those whose values are fixed by `blk.Gain.Free`.

Default: Array of zero values

`Free`

Array of logical values determining whether the gain entries in `blk.Gain.Value` are fixed or free parameters.

• If `blk.Gain.Free(i,j) = 1`, then `blk.Gain.Value(i,j)` is a tunable parameter.

• If `blk.Gain.Free(i,j) = 0`, then `blk.Gain.Value(i,j)` is fixed.

Default: Array of 1 (`true`) values

`Minimum`

Minimum value of the parameter. This property places a lower bound on the tuned value of the parameter. For example, setting `blk.Gain.Minimum = 1` ensures that all entries in the gain matrix have gain greater than 1.

Default: `-Inf`

`Maximum`

Maximum value of the parameter. This property places an upper bound on the tuned value of the parameter. For example, setting ```blk.Gain.Maximum = 100``` ensures that all entries in the gain matrix have gain less than 100.

Default: `Inf`

`Ts`

Sample time. For continuous-time models, `Ts = 0`. For discrete-time models, `Ts` is a positive scalar representing the sampling period. This value is expressed in the unit specified by the `TimeUnit` property of the model. To denote a discrete-time model with unspecified sample time, set ```Ts = -1```.

Changing this property does not discretize or resample the model.

Default: `0` (continuous time)

`TimeUnit`

Units for the time variable, the sample time `Ts`, and any time delays in the model, specified as one of the following values:

• `'nanoseconds'`

• `'microseconds'`

• `'milliseconds'`

• `'seconds'`

• `'minutes'`

• `'hours'`

• `'days'`

• `'weeks'`

• `'months'`

• `'years'`

Changing this property has no effect on other properties, and therefore changes the overall system behavior. Use `chgTimeUnit` to convert between time units without modifying system behavior.

Default: `'seconds'`

`InputName`

Input channel names, specified as one of the following:

• Character vector — For single-input models, for example, `'controls'`.

• Cell array of character vectors — For multi-input models.

Alternatively, use automatic vector expansion to assign input names for multi-input models. For example, if `sys` is a two-input model, enter:

`sys.InputName = 'controls';`

The input names automatically expand to `{'controls(1)';'controls(2)'}`.

You can use the shorthand notation `u` to refer to the `InputName` property. For example, `sys.u` is equivalent to `sys.InputName`.

Input channel names have several uses, including:

• Identifying channels on model display and plots

• Extracting subsystems of MIMO systems

• Specifying connection points when interconnecting models

Default: `''` for all input channels

`InputUnit`

Input channel units, specified as one of the following:

• Character vector — For single-input models, for example, `'seconds'`.

• Cell array of character vectors — For multi-input models.

Use `InputUnit` to keep track of input signal units. `InputUnit` has no effect on system behavior.

Default: `''` for all input channels

`InputGroup`

Input channel groups. The `InputGroup` property lets you assign the input channels of MIMO systems into groups and refer to each group by name. Specify input groups as a structure. In this structure, field names are the group names, and field values are the input channels belonging to each group. For example:

```sys.InputGroup.controls = [1 2]; sys.InputGroup.noise = [3 5];```

creates input groups named `controls` and `noise` that include input channels 1, 2 and 3, 5, respectively. You can then extract the subsystem from the `controls` inputs to all outputs using:

`sys(:,'controls')`

Default: Struct with no fields

`OutputName`

Output channel names, specified as one of the following:

• Character vector — For single-output models. For example, `'measurements'`.

• Cell array of character vectors — For multi-output models.

Alternatively, use automatic vector expansion to assign output names for multi-output models. For example, if `sys` is a two-output model, enter:

`sys.OutputName = 'measurements';`

The output names automatically expand to `{'measurements(1)';'measurements(2)'}`.

You can use the shorthand notation `y` to refer to the `OutputName` property. For example, `sys.y` is equivalent to `sys.OutputName`.

Output channel names have several uses, including:

• Identifying channels on model display and plots

• Extracting subsystems of MIMO systems

• Specifying connection points when interconnecting models

Default: `''` for all output channels

`OutputUnit`

Output channel units, specified as one of the following:

• Character vector — For single-output models. For example, `'seconds'`.

• Cell array of character vectors — For multi-output models.

Use `OutputUnit` to keep track of output signal units. `OutputUnit` has no effect on system behavior.

Default: `''` for all output channels

`OutputGroup`

Output channel groups. The `OutputGroup` property lets you assign the output channels of MIMO systems into groups and refer to each group by name. Specify output groups as a structure. In this structure, field names are the group names, and field values are the output channels belonging to each group. For example:

```sys.OutputGroup.temperature = [1]; sys.InputGroup.measurement = [3 5];```

creates output groups named `temperature` and `measurement` that include output channels 1, and 3, 5, respectively. You can then extract the subsystem from all inputs to the `measurement` outputs using:

`sys('measurement',:)`

Default: Struct with no fields

`Name`

System name, specified as a character vector. For example, `'system_1'`.

Default: `''`

`Notes`

Any text that you want to associate with the system, stored as a string or a cell array of character vectors. The property stores whichever data type you provide. For instance, if `sys1` and `sys2` are dynamic system models, you can set their `Notes` properties as follows:

```sys1.Notes = "sys1 has a string."; sys2.Notes = 'sys2 has a character vector.'; sys1.Notes sys2.Notes```
```ans = "sys1 has a string." ans = 'sys2 has a character vector.' ```

Default: `[0×1 string]`

`UserData`

Any type of data you want to associate with system, specified as any MATLAB® data type.

Default: `[]`

## Examples

Create a 2-by-2 parametric gain block of the form

`$\left[\begin{array}{cc}{g}_{1}& 0\\ 0& {g}_{2}\end{array}\right]$`

where g1 and g2 are tunable parameters, and the off-diagonal elements are fixed to zero.

```blk = tunableGain('gainblock',2,2); % 2 outputs, 2 inputs blk.Gain.Free = [1 0; 0 1]; % fix off-diagonal entries to zero```

All entries in `blk.Gain.Value` initialize to zero. Initialize the diagonal values to 1 as follows.

```blk.Gain.Value = eye(2); % set diagonals to 1 ```

Create a two-input, three-output parametric gain block and initialize all the parameter values to 1.

To do so, create a matrix to dimension the parametric gain block and initialize the parameter values.

```G = ones(3,2); blk = tunableGain('gainblock',G);```

Create a 2–by-2 parametric gain block and assign names to the inputs.

```blk = tunableGain('gainblock',2,2) % 2 outputs, 2 inputs blk.InputName = {'Xerror','Yerror'} % assign input names ```

## Tips

• Use the `blk.Gain.Free` field of `blk` to specify additional structure or fix the values of specific entries in the block. To fix the gain value from input `i` to output `j`, set `blk.Gain.Free(i,j) = 0`. To allow `hinfstruct` to tune this gain value, set `blk.Gain.Free(i,j) = 1`.

• To convert a `tunableGain` parametric model to a numeric (non-tunable) model object, use model commands such as `tf`, `zpk`, or `ss`.

## Version History

Introduced in R2016a

expand all

Behavior changed in R2016a