# looptuneOptions

Set options for `looptune`

## Description

Use `looptuneOptions`

to create an option set for the
`looptune`

function.

## Creation

returns the
default option set for the `options`

= looptuneOptions`looptune`

command.

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

= looptuneOptions(`Name,Value`

)

## Properties

`GainMargin`

— Target gain margin

`7.6`

(default) | scalar

Target gain margin, in decibels, specified as a scalar.
`GainMargin`

specifies the required gain margin for the
tuned control system. For MIMO control systems, the gain margin is the
multiloop disk margin. See Stability Analysis Using Disk Margins (Robust Control Toolbox) for the
definition of the multiloop disk margin.

`PhaseMargin`

— Target phase margin

45 (default) | scalar

Target phase margin, in degrees, specified as a scalar.
`PhaseMargin`

specifies the required phase margin for
the tuned control system. For MIMO control systems, the phase margin is the
multiloop disk margin. See Stability Analysis Using Disk Margins (Robust Control Toolbox) for the
definition of the multiloop disk margin.

`Display`

— Information to display

`'final'`

(default) | `'off'`

| `'iter'`

Amount of information to display during `looptune`

runs, specified as one of these values:

`'off'`

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

— Display optimization progress after each iteration. The display includes the value of the objective parameter`gam`

after each iteration. The display also includes a`Progress`

value, indicating the percent change in`gam`

from the previous iteration.`'final'`

— Display a one-line summary at the end of each optimization run. The display includes the minimized value of`gam`

and the number of iterations for each run.

`MaxIter`

— Maximum number of iterations in each optimization run

300 (default) | positive scalar

Maximum number of iterations in each optimization run, 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`

,
`looptune`

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.

`looptune`

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.

`TargetGain`

— Target value for objective parameter `gam`

1 (default) | scalar

Target value for the objective parameter `gam`

, specified
as a scalar.

The `looptune`

command converts your design
requirements into normalized gain constraints. The command then tunes the
free parameters of the control system to drive the objective parameter
`gam`

below 1 to enforce all requirements.

The default `TargetGain = 1`

ensures that the
optimization stops as soon as `gam`

falls below 1. Set
`TargetGain`

to a smaller or larger value to continue
the optimization or start sooner, respectively.

`TolGain`

— Relative tolerance for termination

0.001 (default) | scalar

Relative tolerance for termination, specified as a scalar.

The optimization terminates when the objective parameter
`gam`

decreases by less than `TolGain`

over 10 consecutive iterations. Increasing `TolGain`

speeds
up termination, and decreasing `TolGain`

yields tighter
final values.

`MaxFrequency`

— Maximum closed-loop natural frequency

`Inf`

(default) | positive scalar

Maximum closed-loop natural frequency, specified as a positive scalar.

Setting `MaxFrequency`

constrains the closed-loop poles
to satisfy `|p| < MaxFrequency`

.

To allow `looptune`

to choose the closed-loop poles
automatically, based upon the system's open-loop dynamics, set
`MaxFrequency = Inf`

. To prevent unwanted
fast dynamics or high-gain control, set `MaxFrequency`

to a
finite value.

Specify `MaxFrequency`

in units of
1/`TimeUnit`

, relative to the
`TimeUnit`

property of the system you are tuning.

`MinDecay`

— Minimum decay rate for closed-loop poles

`1e-7`

(default) | positive scalar

Minimum decay rate for closed-loop poles, specified as a positive scalar

Constrains the closed-loop poles to satisfy
`Re(p) < -MinDecay`

. Increase this value
to improve the stability of closed-loop poles that do not affect the
closed-loop gain due to pole/zero cancellations.

Specify `MinDecay`

in units of
1/`TimeUnit`

, relative to the
`TimeUnit`

property of the system you are tuning.

## Examples

### Create Options Set for looptune

Create an options set for a `looptune`

run using three random restarts. Also, set the target gain and phase margins to 6 dB and 50 degrees, respectively, and limit the closed-loop pole magnitude to 100.

options = looptuneOptions('RandomStart',3','GainMargin',6,... 'PhaseMargin',50,'SpecRadius',100);

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

.

options = looptuneOptions; options.RandomStart = 3; options.GainMargin = 6; options.PhaseMargin = 50; options.SpecRadius = 100;

### Configure Option Set for Parallel Optimization Runs

Configure an option set for a `looptune`

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
`looptune`

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

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 `looptuneOptions`

set that specifies 20 random
restarts to run in parallel.

options = looptuneOptions('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 `looptuneOptions`

set when you call
`looptune`

. For example, suppose you have already
created a plant model `G0`

and tunable controller
`C0`

. In this case, the following command uses parallel
computing to tune the control system of `G0`

and
`C0`

to the target crossover`wc`

.

[G,C,gamma] = looptune(G0,C0,wc,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

`looptune`

| `looptune (for slTuner)`

(Simulink Control Design) | `diskmargin`

(Robust Control Toolbox)

### Topics

- Stability Analysis Using Disk Margins (Robust Control Toolbox)

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## 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)