# systuneOptions

Set options for `systune`

## Description

Use `systuneOptions`

to create an option set for the
`systune`

function.

## Creation

returns the default
option set for the `options`

= systuneOptions`systune`

command.

creates an option set and sets Properties using one or more name-value arguments`options`

= systuneOptions(`Name,Value`

)

## Properties

`Display`

— Information to display

`'final'`

(default) | `'off'`

| `'iter'`

Amount of information to display during `systune`

runs, specified as one of these values:

`'final'`

— Display a one-line summary at the end of each optimization run. The display includes the best achieved values for the soft and hard constraints,`fSoft`

and`gHard`

. The display also includes the number of iterations for each run.Example:

Final: Soft = 1.09, Hard = 0.68927, Iterations = 58

`'sub'`

— Display the result of each optimization subproblem.When you use both soft and hard tuning goals, the software solves the optimization as a sequence of subproblems of the form:

$$\underset{x}{\mathrm{min}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\mathrm{max}\left(\alpha f\left(x\right),g\left(x\right)\right).$$

Here,

*x*is the vector of tunable parameters,*f*(*x*) is the largest normalized soft-constraint value, and*g*(*x*) is the largest normalized hard-constraint value. (See the “Algorithms” section of the`systune`

reference page for more information.) The software adjusts the multiplier*α*so that the solution of the subproblems converges to the solution of the original constrained optimization problem. When you select`'sub'`

, the report includes the results of each of these subproblems.Example:

alpha=0.1: Soft = 3.97, Hard = 0.68927, Iterations = 8 alpha=0.5036: Soft = 1.36, Hard = 0.68927, Iterations = 8 alpha=1.47: Soft = 1.09, Hard = 0.68927, Iterations = 42 Final: Soft = 1.09, Hard = 0.68927, Iterations = 58

`'iter'`

— Display optimization progress after each iteration. The display includes the value after each iteration of the objective parameter being minimized. The objective parameter is whichever is larger of*αf*(*x*) and*g*(*x*). The display also includes a progress value that indicates the percent change in the constraints from the previous iteration.Example:

Iter 1: Objective = 4.664, Progress = 93% Iter 2: Objective = 2.265, Progress = 51.4% Iter 3: Objective = 0.7936, Progress = 65% Iter 4: Objective = 0.7183, Progress = 9.48% Iter 5: Objective = 0.6893, Progress = 4.04% Iter 6: Objective = 0.6893, Progress = 0% Iter 7: Objective = 0.6893, Progress = 0% Iter 8: Objective = 0.6893, Progress = 0% alpha=0.1: Soft = 3.97, Hard = 0.68927, Iterations = 8 Iter 1: Objective = 1.146, Progress = 42.7% Iter 2: Objective = 1.01, Progress = 11.9% ... alpha=1.47: Soft = 1.09, Hard = 0.68927, Iterations = 42 Final: Soft = 1.09, Hard = 0.68927, Iterations = 58

`'off'`

— Run in silent mode, displaying no information during or after the run.

`MaxIter`

— Maximum number of iterations in each optimization run

300 (default) | positive scalar

Maximum number of iterations in each optimization run, when the run does not converge to within tolerance, specified as a positive scalar.

`RandomStart`

— Number of additional optimizations starting from random values

0 (default) | nonnegative scalar

Number of additional optimizations starting from random values of the free parameters in the controller, specified as a nonnegative scalar.

If `RandomStart = 0`

,
`systune`

performs a single optimization run starting
from the initial values of the tunable parameters. Setting
`RandomStart = N > 0`

runs
*N* additional optimizations starting from
*N* randomly generated parameter values.

`systune`

tunes by finding a local minimum of a gain
minimization problem. To increase the likelihood of finding parameter values
that meet your design requirements, set
`RandomStart > 0`

. You can then use the
best design that results from the multiple optimization runs.

Use with `UseParallel = true`

to distribute independent
optimization runs among MATLAB^{®} workers (requires Parallel Computing Toolbox™ software).

`UseParallel`

— Option to enable parallel computing

`false`

(default) | `true`

Option to enable parallel computing, specified as the comma-separated pair
consisting of `'UseParallel'`

and `false`

or `true`

.

When you use the `RandomStart`

option to run multiple
randomized optimization starts when tuning a structured controller, you can
also use parallel computing to distribute the optimization runs among
workers in a parallel pool. When you set this option to
`true`

, if there is an available parallel pool, then
the software performs independent optimization runs concurrently among
workers in that pool. If no parallel pool is available, one of the following
occurs:

If you select

**Automatically create a parallel pool**in your Parallel Computing Toolbox preferences (Parallel Computing Toolbox), then the software starts a parallel pool using the settings in those preferences.If you do not select

**Automatically create a parallel pool**in your preferences, then the software performs the optimization runs successively, without parallel processing.

Using parallel computing requires Parallel Computing Toolbox software.

`SkipModels`

— Models or design points to ignores

`[]`

(default) | array of linear indices

Models or design points to ignore, specified as an array of linear indices.

Use this option to skip specific models or ignore portions of the design
space when tuning gain-scheduled control systems. For example, you might
want to skip grid points outside the flight envelope of an airplane model,
or points outside the operating range for tuning. Identify the models to
skip by absolute index in the array of models to tune. Using
`SkipModels`

lets you narrow the scope of tuning
without reconfiguring each tuning goal. For more information, see
Change Requirements with Operating Condition.

`SoftTarget`

— Target value for soft constraints

`0`

(default) | scalar

Target value for soft constraints, specified as a scalar.

The optimization stops when the largest soft constraint value falls below
the specified `SoftTarget`

value. The default value
`SoftTarget = 0`

minimizes the soft
constrains subject to satisfying the hard constraints.

`SoftTol`

— Relative tolerance for termination

`0.001`

(default) | scalar

Relative tolerance for termination, specified as a scalar.

The optimization terminates when the relative decrease in the soft
constraint value decreases by less than `SoftTol`

over 10
consecutive iterations. Increasing `SoftTol`

speeds up
termination, and decreasing `SoftTol`

yields tighter final
values.

`SoftScale`

— A-priori estimate of best soft constraint value

`1`

(default) | scalar

A-priori estimate of best soft constraint value, specified as a scalar.

For problems that mix soft and hard constraints, providing a rough estimate of the optimal value of the soft constraints (subject to the hard constraints) helps to speed up the optimization.

`MinDecay`

— Minimum decay rate for closed-loop poles

`1e-7`

(default) | positive scalar

Minimum decay rate for stabilized dynamics, specified as a positive scalar.

Most tuning goals carry an implicit closed-loop stability or
minimum-phase constraint. *Stabilized dynamics* refers
to the poles and zeros affected by these constraints. The
`MinDecay`

option constrains all stabilized poles and
zeros to satisfy:

`Re(s) < -MinDecay`

(continuous time).`log(|z|) < -MinDecay`

(discrete time).

Adjust the minimum value if the optimization fails to meet the default
value, or if the default value conflicts with other requirements.
Alternatively, use `TuningGoal.Poles`

to control the decay
rate of a specific feedback loop.

For more information about implicit constraints for a particular tuning goal, see the reference page for that tuning goal.

`MaxRadius`

— Maximum spectral radius for stabilized dynamics

`1e8`

(default) | scalar

Maximum spectral radius for stabilized dynamics, specified as a scalar.

This option constrains all stabilized poles and zeros to satisfy
`|s| < MaxRadius`

. Stabilized dynamics are those
poles and zeros affected by implicit stability or minimum-phase constraints
of the tuning goals. The `MaxRadius`

constraint is useful
to prevent these poles and zeros from going to infinity as a result of
algebraic loops becoming singular or control effort growing unbounded.
Adjust the maximum radius if the optimization fails to meet the default
value, or if the default value conflicts with other requirements.

`MaxRadius`

is ignored for discrete-time tuning, where
stability constraints already impose `|z| < 1`

.

For more information about implicit constraints for a particular tuning goal, see the reference page for that tuning goal.

## Examples

### Create Options Set for systune

Create an options set for a `systune`

run using five random restarts. Also, set the display level to show the progress of each iteration, and increase the relative tolerance of the soft constraint value to 0.01.

options = systuneOptions('RandomStart',5,'Display','iter',... 'SoftTol',0.01);

Alternatively, use dot notation to set the values of `options`

.

```
options = systuneOptions;
options.RandomStart = 5;
options.Display = 'iter';
options.SoftTol = 0.01;
```

### Configure Option Set for Parallel Optimization Runs

Configure an option set for a `systune`

run using 20 random restarts. Execute these independent optimization runs
concurrently on multiple workers in a parallel pool.

If you have the Parallel Computing Toolbox software installed, you can use parallel computing to speed up
`systune`

tuning of fixed-structure control systems. When
you run multiple randomized `systune`

optimization starts,
parallel computing speeds up tuning by distributing the optimization runs among
workers.

If **Automatically create a parallel pool** is not
selected in your Parallel Computing Toolbox preferences (Parallel Computing Toolbox), manually start a parallel pool using
`parpool`

(Parallel Computing Toolbox). For example:

parpool;

If **Automatically create a parallel pool** is selected
in your preferences, you do not need to manually start a pool.

Create a `systuneOptions`

set that specifies 20 random
restarts to run in parallel.

options = systuneOptions('RandomStart',20,'UseParallel',true);

Setting `UseParallel`

to `true`

enables
parallel processing by distributing the randomized starts among available
workers in the parallel pool.

Use the `systuneOptions`

set when you call
`systune`

. For example, suppose you have already
created a tunable control system model, `CLO`

. For tuning
this system, you have created vectors `SoftReqs`

and
`HardReqs`

of `TuningGoal`

requirements objects. These vectors represent your soft and hard
constraints, respectively. In that case, the following command uses parallel
computing to tune the control system of `CL0`

.

[CL,fSoft,gHard] = systune(CL0,SoftReqs,HardReqs,options);

## Version History

**Introduced in R2016a**

### R2016a: Functionality moved from Robust Control Toolbox

Prior to R2016a, this functionality required a Robust Control Toolbox™ license.

## See Also

`systune`

| `systune (for slTuner)`

(Simulink Control Design)

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)