# ltiblock.gain

Tunable static gain block

## Syntax

`blk = ltiblock.gain(name,Ny,Nu)blk = ltiblock.gain(name,G)`

## Description

Model object for creating tunable static gains. `ltiblock.gain` lets you parametrize tunable static gains for parameter studies or for automatic tuning with Robust Control Toolbox™ tuning commands such as `systune` or `looptune`.

`ltiblock.gain` is part of the Control Design Block family of parametric models. Other Control Design Blocks include`ltiblock.pid`, `ltiblock.ss`, and `ltiblock.tf`.

## Construction

`blk = ltiblock.gain(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 = ltiblock.gain(name,G)` uses the double array `G` to dimension the block and initialize the tunable parameters.

### Input Arguments

 `name` String specifying the block `Name`. (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` object `blk.Gain`, see the param.Continuousparam.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` 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. Use `c2d` and `d2c` to convert between continuous- and discrete-time representations. Use `d2d` to change the sample time of a discrete-time system.

Default: `0` (continuous time)

`TimeUnit`

String representing the unit of the time variable. This property specifies the units for the time variable, the sample time `Ts`, and any time delays in the model. Use any 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. Set `InputName` to a string for single-input model. For a multi-input model, set `InputName` to a cell array of strings.

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: Empty string `''` for all input channels

`InputUnit`

Input channel units. Use `InputUnit` to keep track of input signal units. For a single-input model, set `InputUnit` to a string. For a multi-input model, set `InputUnit` to a cell array of strings. `InputUnit` has no effect on system behavior.

Default: Empty string `''` 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. Set `OutputName` to a string for single-output model. For a multi-output model, set `OutputName` to a cell array of strings.

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: Empty string `''` for all output channels

`OutputUnit`

Output channel units. Use `OutputUnit` to keep track of output signal units. For a single-output model, set `OutputUnit` to a string. For a multi-output model, set `OutputUnit` to a cell array of strings. `OutputUnit` has no effect on system behavior.

Default: Empty string `''` 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. Set `Name` to a string to label the system.

Default: `''`

`Notes`

Any text that you want to associate with the system. Set `Notes` to a string or a cell array of strings.

Default: `{}`

`UserData`

Any type of data you wish to associate with system. Set `UserData` to 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 = ltiblock.gain('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 = ltiblock.gain('gainblock',G);```

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

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

collapse all

### 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 an `ltiblock.gain` parametric model to a numeric (non-tunable) model object, use model commands such as `tf`, `zpk`, or `ss`.