# systune

Tune control system parameters in Simulink using `slTuner` interface

## Syntax

• ```[st,fSoft] = systune(st0,SoftGoals)``` example
• ```[st,fSoft,gHard] = systune(st0,SoftGoals,HardGoals)```
• ```[st,fSoft,gHard] = systune(___,opt)```
• ```[st,fSoft,gHard,info] = systune(___)```

## Description

example

``````[st,fSoft] = systune(st0,SoftGoals)``` tunes the free parameters of the control system in Simulink®. The Simulink model, tuned blocks, and analysis points of interest are specified by the `slTuner` interface, `st0`. `systune` tunes the control system parameters to best meet the performance goals, `SoftGoals`. The command returns a tuned version of `st0` as `st`, and the best achieved values as `fSoft` for the objectives, `SoftGoals`.Tuning is performed at the sample time specified by the `Ts` property of `st0`.This command requires a Robust Control Toolbox™ license.```
``````[st,fSoft,gHard] = systune(st0,SoftGoals,HardGoals)``` tunes the control system to best meet the soft goals, subject to satisfying the hard goals. It returns the best achieved values, `fSoft` and `gHard`, for the soft and hard goals. A goal is met when its achieved value is less than 1.```
``````[st,fSoft,gHard] = systune(___,opt)``` specifies options for the optimization for any of the input argument combinations in previous syntaxes.```
``````[st,fSoft,gHard,info] = systune(___)``` also returns detailed information about each optimization run for any of the input argument combinations in previous syntaxes.```

## Examples

collapse all

### Tune Control System to Soft Constraints

Tune the control system in the `rct_airframe2` model to soft goals for tracking, roll off, stability margin, and disturbance rejection.

Create and configure an `slTuner` interface to the model.

```open_system('rct_airframe2') st0 = slTuner('rct_airframe2','MIMO Controller'); ```

`st0` is an `slTuner` interface to the `rct_aircraft2` model with the ```MIMO Controller``` block specified as the tunable portion of the control system.

The model already has linearization input points on the signals ```az ref```, `delta fin`, `az`, `q`, and `e`. These signals are therefore available as analysis points for tuning goals and linearization.

Specify the tracking requirement, roll-off requirement, stability margins, and disturbance rejection requirement.

```req1 = TuningGoal.Tracking('az ref','az',1); req2 = TuningGoal.Gain('delta fin','delta fin',tf(25,[1 0])); req3 = TuningGoal.Margins('delta fin',7,45); max_gain = frd([2 200 200],[0.02 2 200]); req4 = TuningGoal.Gain('delta fin','az',max_gain); ```

`req1` constrains `az` to track `az ref`. The next requirement, `req2`, imposes a roll-off requirement by specifying a gain profile for the open-loop, point-to-point transfer function measured at ```delta fin```. The next requirement, `req3`, imposes open-loop gain and phase margins on that same point-to-point transfer function. Finally, `req4` rejects disturbances to `az` injected at `delta fin`, by specifying a maximum gain profile between those two points.

Tune the model using these tuning goals.

```opt = systuneOptions('RandomStart',3); rng(0); [st,fSoft,~,info] = systune(st0,[req1,req2,req3,req4],opt);```
```Final: Soft = 1.15, Hard = -Inf, Iterations = 72 Final: Soft = 1.53, Hard = -Inf, Iterations = 86 Final: Soft = 1.15, Hard = -Inf, Iterations = 89 Final: Failed to enforce closed-loop stability (max Re(s) = 0)```

`st` is a tuned version of `st0`.

The `RandomStart` option specifies that `systune` must perform three independent optimization runs that use different (random) initial values of the tunable parameters. These three runs are in addition to the default optimization run that uses the current value of the tunable parameters as the initial value. The call to `rng` seeds the random number generator to produce a repeatable sequence of numbers.

`systune` displays the final result for each run. The displayed value, `Soft`, is the maximum of the values achieved for each of the four performance goals. The software chooses the best run overall, which is the run yielding the lowest value of `Soft`. The last run fails to achieve closed-loop stability, which corresponds to `Soft = Inf`.

Examine the best achieved values of the soft constraints.

```fSoft ```
```fSoft = 1.1460 1.1460 0.5434 1.1460```

Only `req3`, the stability margin requirement, is met for all frequencies. The other values are close to, but exceed, 1, indicating violations of the goals for at least some frequencies.

Use `viewSpec` to visualize the tuned control system performance against the goals and to determine whether the violations are acceptable. To evaluate specific open-loop or closed-loop transfer functions for the tuned parameter values, you can use linearization commands such as `getIOTransfer` and `getLoopTransfer`. After validating the tuned parameter values, if you want to apply these values to the Simulink model, you can use `writeBlockValue`.

## Input Arguments

collapse all

### `st0` — Interface for tuning control systems modeled in Simulink`slTuner` interface

Interface for tuning control systems modeled in Simulink, specified as an `slTuner` interface.

### `SoftGoals` — Soft goals (objectives)vector of `TuningGoal` objects

Soft goals (objectives) for tuning the control system described by `st0`, specified as a vector of `TuningGoal` objects. For a complete list, see Tuning Goals.

`systune` tunes the tunable parameters of the control system to minimize the maximum value of the soft tuning goals, subject to satisfying the hard tuning goals (if any).

### `HardGoals` — Hard goals (constraints)vector of `TuningGoal` objects

Hard goals (constraints) for tuning the control system described by `st0`, specified as a vector of `TuningGoal` objects. For a complete list, see Tuning Goals.

A hard goal is satisfied when its value is less than 1. `systune` tunes the tunable parameters of the control system to minimize the maximum value of the soft tuning goals, subject to satisfying all the hard tuning goals.

### `opt` — Tuning algorithm optionsoptions set created using `systuneOptions`

Tuning algorithm options, specified as an options set created using `systuneOptions`.

Available options include:

• Number of additional optimizations to run starting from random initial values of the free parameters

• Tolerance for terminating the optimization

• Flag for using parallel processing

## Output Arguments

collapse all

### `st` — Tuned interface`slTuner` interface

Tuned interface, returned as an `slTuner` interface.

### `fSoft` — Best achieved values of soft goalsvector

Best achieved values of soft goals, returned as a vector.

Each tuning goal evaluates to a scalar value, and `systune` minimizes the maximum value of the soft goals, subject to satisfying all the hard goals.

`fSoft` contains the value of each soft goal for the best overall run. The best overall run is the run that achieved the smallest value for `max(fSoft)`, subject to `max(gHard)<1`.

### `gHard` — Achieved values of hard goalsvector

Achieved values of hard goals, returned as a vector.

`gHard` contains the value of each hard goal for the best overall run (the run that achieved the smallest value for `max(fSoft)`, subject to `max(gHard)<1`. All entries of `gHard` are less than 1 when all hard goals are satisfied. Entries greater than 1 indicate that `systune` could not satisfy one or more design constraints.

### `info` — Detailed information about each optimization runstructure

Detailed information about each optimization run, returned as a structure.

In addition to examining detailed results of the optimization, you can use `info` as an input to `viewSpec` when validating a tuned MIMO system. `info` contains scaling data that `viewSpec` needs for correct evaluation of MIMO open-loop goals, such as loop shapes and stability margins.

The fields of `info` are:

### `Run` — Run numberscalar

Run number, returned as a scalar. If you use the `RandomStart` option of `systuneOptions` to perform multiple optimization runs, `info` is a struct array, and `info.Run` is the index.

### `Iterations` — Total number of iterations performed during runscalar

Total number of iterations performed during run, returned as a scalar.

### `fBest` — Best overall soft constraint valuescalar

Best overall soft constraint value, returned as a scalar. `systune` converts the soft goals to a function of the free parameters of the control system. The command then tunes the parameters to minimize that function subject to the hard constraints. (See Algorithms.) `info.fBest` is the maximum soft constraint value at the final iteration. This value is only meaningful when the hard constraints are satisfied.

### `gBest` — Best overall hard constraint valuescalar

Best overall hard constraint value, returned as a scalar. `systune` converts the hard goals to a function of the free parameters of the control system. The command then tunes the parameters to drive those values below 1. (See Algorithms.) `info.gBest` is the maximum hard constraint value at the final iteration. This value must be less than 1 for the hard constraints to be satisfied.

### `fSoft` — Individual soft constraint valuesvector

Individual soft constraint values, returned as a vector. `systune` converts each soft requirement to a normalized value that is a function of the free parameters of the control system. The command then tunes the parameters to minimize that value subject to the hard constraints. (See Algorithms.) `info.fSoft` contains the individual values of the soft constraints at the end of each run. These values appear in `fSoft` in the same order that the constraints are specified in `SoftGoals`.

### `gHard` — Individual hard constraint valuesvector

Individual hard constraint values, returned as a vector. `systune` converts each hard requirement to a normalized value that is a function of the free parameters of the control system. The command then tunes the parameters to minimize those values. A hard requirement is satisfied if its value is less than 1. (See Algorithms.) `info.gHard` contains the individual values of the hard constraints at the end of each run. These values appear in `gHard` in the same order that the constraints are specified in `HardGoals`.

### `MinDecay` — Minimum decay rate of closed-loop polesvector

Minimum decay rate of closed-loop poles, returned as a vector.

By default, closed-loop pole locations of the tuned system are constrained to satisfy Re(p) < –10–7. Use the `MinDecay` option of `systuneOptions` to change this constraint.

### `Blocks` — Tuned values of tunable blocks and parametersstructure

Tuned values of tunable blocks and parameters, returned as a structure.

In case of multiple runs, you can try the results of any particular run other than the best run. To do so, you can use either `getBlockValue` or `showTunable` to access the tuned parameter values. For example, to use the results from the third run, type `getBlockValue(st,Info(3).Blocks)`.

### `LoopScaling` — Optimal diagonal scaling for evaluating MIMO tuning goalsstate-space model

Optimal diagonal scaling for evaluating MIMO tuning goals, returned as a state-space model.

When applied to multiloop control systems, `TuningGoal.LoopShape` and `TuningGoal.Margins` goals can be sensitive to the scaling of the individual loop transfer functions to which they apply. `systune` automatically corrects scaling issues and returns the optimal diagonal scaling matrix `d` as a state-space model in `info.LoopScaling`.

The loop channels associated with each diagonal entry of `D` are listed in `info.LoopScaling.InputName`. The scaled loop transfer is `D\L*D`, where `L` is the open-loop transfer measured at the locations `info.LoopScaling.InputName`.

collapse all

### Tuned Blocks

Tuned blocks, used by the `slTuner` interface, identify blocks in a Simulink model whose parameters are to be tuned to satisfy tuning goals. You can tune most Simulink blocks that represent linear elements such as gains, transfer functions, or state-space models. (For the complete list of blocks that support tuning, see How Tuned Simulink Blocks Are Parameterized.) You can also tune more complex blocks such as SubSystem or S-Function blocks by specifying an equivalent tunable linear model.

Use commands such as `systune` and `looptune` to tune the parameters of tuned blocks.

You must specify tuned blocks (for example, C1 and C2) when you create an `slTuner` interface:

`st = slTuner('scdcascade',{'C1','C2'})`

You can modify the list of tuned blocks using `addBlock` and `removeBlock`. Use commands such as `setBlockParam`, `getBlockValue`, and `writeBlockValue` to interact with and manipulate tuned blocks.

### Analysis Points

Analysis points, used by the `slLinearizer` and `slTuner` interfaces, identify locations within a model that are relevant for linear analysis and control system tuning. You use analysis points as inputs to the linearization commands, such as `getIOTransfer`, `getLoopTransfer`, `getSensitivity`, and `getCompSensitivity`. As inputs to the linearization commands, analysis points can specify any open- or closed-loop transfer function in a model. You can also use analysis points to specify design requirements when tuning control systems using commands such as `systune` (requires a Robust Control Toolbox license).

Location refers to a specific block output port within a model. For convenience, you can use the name of the signal that originates from this port to refer to an analysis point.

You can add analysis points to an `slLinearizer` or `slTuner` interface, `s`, when you create the interface. For example:

`s = slLinearizer('scdcascade',{'u1','y1'});`

Alternatively, you can use the `addPoint` command.

To view all the analysis points of `s`, type `s` at the command prompt to display the interface contents. For each analysis point of `s`, the display includes the block name and port number and the name of the signal that originates at this point. You can also use `getPoints` to programmatically obtain a list of all the analysis points.

For more information about how you can use analysis points, see Marking Signals of Interest for Control System Analysis and Design.

### Algorithms

x is the vector of tunable parameters in the control system to tune. `systune` converts each soft and hard tuning requirement, `SoftReqs(i)` and `HardReqs(j)`, into normalized values fi(x) and gj(x), respectively. `systune` then solves the minimization problem:

Minimize $\underset{i}{\mathrm{max}}{f}_{i}\left(x\right)$ subject to $\underset{j}{\mathrm{max}}{g}_{j}\left(x\right)<1$, for ${x}_{\mathrm{min}}.

xmin and xmax are the minimum and maximum values of the free parameters.

`systune` returns a control system, `st`, with parameters tuned to the values that best solve the minimization problem. `systune` also returns the best achieved values of fi(x) and gj(x), as `fSoft` and `gHard`.

For information about the functions fi(x) and gj(x) for each type of constraint, see the reference pages for each `TuningGoal` requirement object.

For information about the optimization algorithms, see [1].

`systune` computes the H norm using the algorithm of [2] and structure-preserving eigensolvers from the SLICOT library. For information about the SLICOT library, see http://slicot.org.

## References

[1] P. Apkarian and D. Noll, "Nonsmooth H-infinity Synthesis." IEEE Transactions on Automatic Control, Vol. 51, Number 1, 2006, pp. 71–86.

[2] Bruisma, N.A. and M. Steinbuch, "A Fast Algorithm to Compute the H-Norm of a Transfer Function Matrix," System Control Letters, 14 (1990), pp. 287-293.