# TuningGoal.MinLoopGain class

Package: TuningGoal

Minimum loop gain constraint for control system tuning

## Description

Use the `TuningGoal.MinLoopGain` object to enforce a minimum loop gain in a particular frequency band. Use this requirement with control system tuning commands such as `systune` or `looptune`.

This requirement imposes a minimum gain on the open-loop frequency response (L) at a specified location in your control system. You specify the minimum open-loop gain as a function of frequency (a minimum gain profile). For MIMO feedback loops, the specified gain profile is interpreted as a lower bound on the smallest singular value of L.

When you tune a control system, the minimum gain profile is converted to a minimum gain constraint on the inverse of the sensitivity function, inv(S)  = (I + L).

The following figure shows a typical specified minimum gain profile (dashed line) and a resulting tuned loop gain, L (blue line). The green region represents gain profile values that are forbidden by this requirement. The figure shows that when L is much larger than 1, imposing a minimum gain on inv(S) is a good proxy for a minimum open-loop gain.

`TuningGoal.MinLoopGain` and `TuningGoal.MaxLoopGain` specify only low-gain or high-gain constraints in certain frequency bands. When you use these requirements, `systune` and `looptune` determine the best loop shape near crossover. When the loop shape near crossover is simple or well understood (such as integral action), you can use `TuningGoal.LoopShape` to specify that target loop shape.

## Construction

`Req = TuningGoal.MinLoopGain(location,loopgain)` creates a tuning requirement for boosting the gain of a SISO or MIMO feedback loop. The requirement specifies that the open-loop frequency response (L) measured at the specified locations exceeds the minimum gain profile specified by `loopgain`.

You can specify the minimum gain profile as a smooth transfer function or sketch a piecewise error profile using an `frd` model or the `makeweight` command. Only gain values greater than 1 are enforced.

For MIMO feedback loops, the specified gain profile is interpreted as a lower bound on the smallest singular value of L.

`Req = TuningGoal.MinLoopGain(location,fmin,gmin)` specifies a minimum gain profile of the form `loopgain = K/s` (integral action). The software chooses `K` such that the gain value is `gmin` at the specified frequency, `fmin`.

### Input Arguments

 `location` Location at which the minimum open-loop gain is constrained, specified as a string or cell array of strings. These strings identify one or more loop-opening locations in the control system to tune. What loop-opening locations are available depends on what kind of system you are tuning:If you are tuning a Simulink® model of a control system, you can use any linear analysis point marked in the model, or any linear analysis point in an `slTuner` interface associated with the Simulink model. Use `addPoint` to add analysis points to the `slTuner` interface. Use `getPoints` to get the list of analysis points available in an `slTuner` interface to your model.If you are tuning a generalized state-space (`genss`) model of a control system, you can use any `AnalysisPoint` location in the control system model. For example, the following code creates a PI loop with an analysis point at the plant input `'u'`. ```AP = AnalysisPoint('u'); G = tf(1,[1 2]); C = ltiblock.pid('C','pi'); T = feedback(G*AP*C,1); ```You can use the string `'u'` to refer to the analysis point at the plant input. Use `getPoints` to get the list of analysis points available in a `genss` model. If `location` is a cell array of loop-opening locations, then the minimum gain requirement applies to the resulting MIMO loop. `loopgain` Minimum open-loop gain as a function of frequency. You can specify `loopgain` as a smooth SISO transfer function (`tf`, `zpk`, or `ss` model). Alternatively, you can sketch a piecewise gain profile using a `frd` model or the `makeweight` command. For example, the following `frd` model specifies a minimum gain of 100 (40 dB) below 0.1 rad/s, rolling off at a rate of –20 dB/dec at higher frequencies. ```loopgain = frd([100 100 10],[0 1e-1 1]); ``` When you use an `frd` model to specify `loopgain`, the software automatically maps your specified gain profile to a `zpk` model. The magnitude of this model approximates the desired gain profile. Use `viewSpec(Req)` to plot the magnitude of that `zpk` model. Only gain values larger than 1 are enforced. For multi-input, multi-output (MIMO) feedback loops, the gain profile is interpreted as a lower bound on the smallest singular value of `L`. For more information about singular values, see `sigma`. `fmin` Frequency of minimum gain `gmin`, specified as a scalar value in rad/s. Use this argument to specify a minimum gain profile of the form ```loopgain = K/s``` (integral action). The software chooses `K` such that the gain value is `gmin` at the specified frequency, `fmin`. `gmin` Value of minimum gain occurring at `fmin`, specified as a scalar absolute value. Use this argument to specify a minimum gain profile of the form ```loopgain = K/s``` (integral action). The software chooses `K` such that the gain value is `gmin` at the specified frequency, `fmin`.

## Properties

 `MinGain` Minimum open-loop gain as a function of frequency, specified as a SISO `zpk` model. The software automatically maps the input argument `loopgain` onto a `zpk` model. The magnitude of this `zpk` model approximates the desired gain profile. Alternatively, if you use the `fmin` and `gmin` arguments to specify the gain profile, this property is set to `K/s`. The software chooses `K` such that the gain value is `gmin` at the specified frequency, `fmin`. Use `viewSpec(Req)` to plot the magnitude of the open-loop minimum gain profile. `Focus` Frequency band in which tuning requirement is enforced, specified as a row vector of the form `[min,max]`. Set the `Focus` property to limit enforcement of the requirement to a particular frequency band. Express this value in the frequency units of the control system model you are tuning (rad/`TimeUnit`). For example, suppose `Req` is a requirement that you want to apply only between 1 and 100 rad/s. To restrict the requirement to this band, use the following command:`Req.Focus = [1,100];` Default: `[0,Inf]` for continuous time; `[0,pi/Ts]` for discrete time, where `Ts` is the model sample time. `Stabilize` Stability requirement on closed-loop dynamics, specified as 1 (`true`) or 0 (`false`). When `Stabilize` is `true`, this requirement stabilizes the specified feedback loop, as well as imposing gain or loop-shape requirements. Set `Stabilize` to `false` if stability for the specified loop is not required or cannot be achieved. Default: 1 (`true`) `LoopScaling` Toggle for automatically scaling loop signals, specified as `'on'` or `'off'`. In multi-loop or MIMO control systems, the feedback channels are automatically rescaled to equalize the off-diagonal terms in the open-loop transfer function (loop interaction terms). Set `LoopScaling` to `'off'` to disable such scaling and shape the unscaled open-loop response. Default: `'on'` `Location` Location at which minimum loop gain is constrained, specified as a string or cell array of strings. These strings identify one or more loop-opening locations in the control system to tune. The value of the `Location` property is set by the `location` input argument when you create the `TuningGoal.Sensitivity` requirement. `Models` Models to which the tuning requirement applies, specified as a vector of indices. Use the `Models` property when tuning an array of control system models with `systune`, to enforce a tuning requirement for a subset of models in the array. For example, suppose you want to apply the tuning requirement, `Req`, to the second, third, and fourth models in a model array passed to `systune`. To restrict enforcement of the requirement, use the following command: `Req.Models = 2:4;` When `Models = NaN`, the tuning requirement applies to all models. Default: `NaN` `Openings` Feedback loops to open when evaluating the requirement, specified as a cell array of strings that identify loop-opening locations. The tuning requirement is evaluated against the open-loop configuration created by opening feedback loops at the locations you identify. If you are using the requirement to tune a Simulink model of a control system, then `Openings` can include any linear analysis point marked in the model, or any linear analysis point in an `slTuner` interface associated with the Simulink model. Use `addPoint` to add analysis points and loop openings to the `slTuner` interface. Use `getPoints` to get the list of analysis points available in an `slTuner` interface to your model. If you are using the requirement to tune a generalized state-space (`genss`) model of a control system, then `Openings` can include any `AnalysisPoint` location in the control system model. Use `getPoints` to get the list of analysis points available in the `genss` model. Default: `{}` `Name` Name of the requirement object, specified as a string. For example, if `Req` is a requirement: `Req.Name = 'LoopReq';` Default: `[]`

## Algorithms

When you tune a control system using a `TuningGoal` object to specify a tuning requirement, the software converts the requirement into a normalized scalar value f(x). Here, x is the vector of free (tunable) parameters in the control system. The software then adjusts the parameter values to minimize f(x) or to drive f(x) below 1 if the tuning requirement is a hard constraint.

For the `TuningGoal.MinLoopGain` requirement, f(x) is given by:

$f\left(x\right)={‖{W}_{S}\left({D}^{-1}SD\right)‖}_{\infty }.$

WS is the minimum loop gain profile, `MaxGain`. D is a diagonal scaling (for MIMO loops). S is the sensitivity function at `Location`.

Although S is a closed-loop transfer function, driving f(x) < 1 is equivalent to enforcing a lower bound on the open-loop transfer function, L, in a frequency band where the gain of L is greater than 1. To see why, note that S = 1/(1 + L). For SISO loops, when |L| >> 1, |S | ≈ 1/|L|. Therefore, enforcing the open-loop minimum gain requirement, |L| > |WS|, is roughly equivalent to enforcing |WsS| < 1. For MIMO loops, similar reasoning applies, with ||S|| ≈ 1/σmin(L), where σmin is the smallest singular value.

For an example illustrating the constraint on S, see Minimum Loop Gain as Constraint on Sensitivity Function.

## Examples

### Minimum Loop Gain Requirement

Create a requirement that boosts the open-loop gain of a feedback loop to greater than a specified profile.

Suppose that you are tuning a control system that has a loop-opening location identified by `PILoop`. Specify that the open-loop gain measured at that location exceed a minimum gain of 10 (20 dB) below 0.1 rad/s, rolling off at a rate of -20 dB/dec at higher frequencies. Use an `frd` model to sketch this gain profile.

```loopgain = frd([10 10 0.1],[0 1e-1 10]); Req = TuningGoal.MinLoopGain('PILoop',loopgain); ```

The software converts `loopgain` into a smooth function of frequency that approximates the piecewise-specified requirement. Display the requirement using `viewSpec`.

```viewSpec(Req) ```

The green region indicates where the requirement is violated, except that gain values less than 1 are not enforced. Therefore, this requirement only specifies a minimum gain at frequencies below 1 rad/s.

You can use `Req` as an input to `looptune` or `systune` when tuning the control system.

### Integral Minimum Gain Specified as Gain Value at Single Frequency

Create a requirement that specifies a minimum loop gain profile of the form L = K / s. The gain profile attains the value of -20 dB (0.01) at 100 rad/s.

```Req = TuningGoal.MinLoopGain('X',100,0.01); viewSpec(Req) ```

`viewSpec` confirms that the requirement is correctly specified. You can use this requirement to tune a control system that has a loop-opening location identified as `'X'`. Since loop gain values less than 1 are ignored, this requirement specifies minimum gain only below 1 rad/s, with no restriction on loop gain at higher frequency.

### Minimum Loop Gain as Constraint on Sensitivity Function

Examine a minimum loop gain requirement against the tuned loop gain. A minimum loop gain requirement is converted to a constraint on the gain of the sensitivity function at the requirement location.

To see this relationship between the requirement and the sensitivity function, tune the following closed-loop system with analysis points at `X1` and `X2`. The control system has tunable PID controllers `C1` and `C2`.

Create a model of the control system.

```G2 = zpk([],-2,3); G1 = zpk([],[-1 -1 -1],10); C20 = ltiblock.pid('C2','pi'); C10 = ltiblock.pid('C1','pid'); X1 = AnalysisPoint('X1'); X2 = AnalysisPoint('X2'); InnerLoop = feedback(X2*G2*C20,1); CL0 = feedback(G1*InnerLoop*C10,X1); CL0.InputName = 'r'; CL0.OutputName = 'y'; ```

Specify some tuning requirements, including a minimum loop gain requirement. Tune the control system to these requirements.

```Rtrack = TuningGoal.Tracking('r','y',10,0.01); Rreject = TuningGoal.Gain('X2','y',0.1); Rgain = TuningGoal.MinLoopGain('X2',100,10000); Rgain.Openings = 'X1'; [CL,fSoft] = systune(CL0,[Rtrack,Rreject,Rgain]); ```
```Final: Soft = 1.07, Hard = -Inf, Iterations = 82 ```

Examine the `TuningGoal.MinLoopGain` requirement against the corresponding tuned response.

```viewSpec(Rgain,CL) ```

The plot shows the achieved loop gain for the loop at `X2` (blue line). The plot also shows the inverse of the achieved sensitivity function, `S`, at the location `X2` (green line). The inverse sensitivity function at this location is given by `inv(S) = I+L`. Here, `L` is the open-loop point-to-point loop transfer measured at `X2`.

The minimum loop gain requirement `Rgain` is constraint on `inv(S)`, represented in the plot by the green shaded region. The constraint on `inv(S)` can be thought of as a minimum gain constraint on `L` that applies where the gain of `L` (or the smallest singular value of `L`, for MIMO loops) is greater than 1.

### Requirement without Stability Constraint on Inner Loop

Create a requirement that specifies a minimum loop gain of 20 dB (100) at 50 rad/s on the inner loop of the following control system.

```Req = TuningGoal.MinLoopGain('X2',50,100); ```

Configure the requirement to apply to the loop gain of the inner loop measured with the outer loop open.

`Req.Openings = 'X2';`

Setting `Req.Openings` tells the tuning algorithm to enforce this requirement with loops open at the specified location.

By default, tuning using `TuningGoal.MinLoopGain` imposes a stability requirement as well as the minimum loop gain requirement. Practically, in some control systems it is not possible to achieve a stable inner loop. When this occurs, remove the stability requirement for the inner loop by setting the `Stabilize` property to `false`.

`Req.Stabilize = false;`

The tuning algorithm still imposes a stability requirement on the overall tuned control system, but not on the inner loop alone.