# musynOptions

Options for `musyn`

## Description

## Examples

### Specify Algorithm Options for Mu Synthesis

Create an options set for `musyn`

that turns on mixed-*μ* analysis for real uncertainty, restricts the *D* and *G* scalings for repeated `ureal`

blocks so they are diagonal, and limits the maximum number of D-K iterations to 20.

opts = musynOptions('MixedMU','on','FullDG',false,'MaxIter',20)

opts = musyn with properties: Display: 'short' MaxIter: 20 TargetPerf: 0 TolPerf: 0.0100 MixedMU: 'on' FullDG: [0 0] FitOrder: [5 2] FrequencyGrid: [0x1 double] AutoScale: 'on' Regularize: 'on' LimitGain: 'on' RandomStart: 0 UseParallel: 0 MinDecay: 1.0000e-07 MaxFrequency: Inf

Alternatively, start with the default options set, and use dot notation to change option values.

```
opts = musynOptions;
opts.MixedMu = 'on';
opts.FullDG = false;
opts.MaxIter = 20;
```

You can now use `opts`

as an input argument to `musyn`

to perform *μ* synthesis using the specified options.

## Input Arguments

### Name-Value Arguments

Specify optional pairs of arguments as
`Name1=Value1,...,NameN=ValueN`

, where `Name`

is
the argument name and `Value`

is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.

*
Before R2021a, use commas to separate each name and value, and enclose*
`Name`

*in quotes.*

**Example: **`opts = musynOptions('MaxIter',20,'MixedMU','on')`

creates an
option set for `musyn`

to specify that the function take into account the
presence of real uncertainty and to stop the D-K iteration process after at most 20
iterations.

**General Options**

`Display`

— Flag to display progress of iterations

`'short'`

(default) | `'full'`

| `'off'`

Flag to display progress of D-K iterations and generate report in the command
window, specified as the comma-separated pair consisting of
`'Display'`

and `'short'`

,
`'full'`

, or `'off'`

.

`'short'`

— Display a brief summary after each iteration.`'full'`

— Pause after each iteration and display detailed results, including plots of*D*and*G*scaling data and the frequency dependence of*μ*.`'off'`

— Turn off the display.

For details on how to interpret the default `'short'`

display and
the `'full'`

display, see Robust Performance Measure for Mu Synthesis.

**Example: **`opts = musynOptions('Display','off')`

creates an option
set for `musyn`

that turns the display off.

`MaxIter`

— Maximum number of D-K iterations

10 (default) | positive integer

Maximum number of D-K iterations, specified as the comma-separated pair consisting
of `'MaxIter'`

and a positive integer. `musyn`

stops after the specified number of iterations or when the stopping tolerance
specified by the '`TolPerf`

' option is reached, whichever is
fewer.

**Example: **`opts = musynOptions('MaxIter',20)`

creates an option set
for `musyn`

that specifies a maximum of 20 iterations.

`TargetPerf`

— Target robust *H*_{∞} performance

0 (default) | nonnegative scalar

Target robust *H*_{∞} performance, specified
as the comma-separated pair consisting of `'TargetPerf'`

and a
nonnegative scalar. By default, `musyn`

tries to drive the robust
*H*_{∞} performance (`PeakMu`

in the default display) to zero in each iteration. If you set
`'TargetPerf'`

to a nonzero value, then D-K iteration terminates
when the robust *H*_{∞} performance drops below
this target value. If you know your system can tolerate worse values of this
performance metric, increasing this value can speed up the
*H*_{∞} part of the D-K iteration. For details
about this performance metric, see `musynperf`

.

**Example: **`opts = musynOptions('TargetPerf',1)`

creates an option
set for `musyn`

that specifies a target
*H*_{∞} performance value of 1.

`TolPerf`

— Stopping tolerance

0.01 (default) | 0 | nonnegative scalar

Stopping tolerance, specified as the comma-separated pair consisting of
`'TolPerf'`

and a nonnegative scalar. The
`musyn`

computation terminates when the robust
*H*_{∞} performance improves by less than this
value over two consecutive iterations. Because of the limited accuracy of fitting the
*D* and *G* scalings, reducing
`'TolPerf'`

below the default does not necessarily yield more
precise results.

If `'TolPerf'`

= 0, then `musyn`

always
performs the number of iterations specified by '`MaxIter`

',
regardless changes in the robust performance from iteration to iteration.

**Example: **`opts = musynOptions('TolPerf',0)`

creates an option set
for `musyn`

that causes the function to always perform the number
of iterations specified by `MaxIter`

.

**Options for D Step (**

*μ*Analysis)`MixedMU`

— Option to specify real or complex *μ* analysis

`'off'`

(default) | `'on'`

Option to specify real or complex *μ* analysis, specified as the
comma-separated pair consisting of `'MixedMU'`

and
`'off'`

or `'on'`

. By default,
`musyn`

treats all uncertainties as complex, which can result in
overly conservative estimates for the upper bound on *μ*. If your
plant has real uncertain parameters, try setting `'MixedMu'`

to
`'on'`

to see if `musyn`

returns a controller
with better performance.

For more information, see Improve Results of Mu Synthesis.

**Example: **`opts = musynOptions('MixedMU','on')`

creates an option
set for `musyn`

that causes the function to take into account the
presence of real uncertainty.

`FullDG`

— Structure of D and G scalings

`true`

(default) | `false`

| `[true false]`

| `[false true]`

Structure of D and G scalings, specified as the comma-separated pair consisting of
`'FullDG'`

and `true`

, `false`

,
`[true false]`

, or `[false true]`

.

By default, `musyn`

uses full scalings for uncertain blocks
that appear multiple times in the control system. Full scaling matrices can have
frequency-dependent entries both on and off the diagonal. The alternative, diagonal
scaling, is equivalent to treating each repeated block as an independent instance of
the uncertain parameter. Therefore, full scaling is less conservative than diagonal
scaling, and can yield better robust performance.

However, when blocks are repeated more than about four or five times, full scaling
can be impractical, leading to lengthy computation, undesirably high-order
controllers, or both. In such cases, restricting scalings to diagonal can improve
results. To do so, set `'FullDG'`

to:

`false`

to limit both*D*and*G*scalings to diagonal.`[true false]`

to use full*D*scaling but diagonal*G*scaling. This option is useful because fitting full*G*scalings is more likely to cause high-order controllers than full*D*scaling.`[false true]`

to use full*G*scaling but diagonal*D*scaling. This option is useful if you need full*G*scaling to get a good fit, but observe that full*D*scaling does not improve`musyn`

results.

For details about how the `musyn`

algorithm uses
*D* and *G* scalings, see Robust Performance Measure for Mu Synthesis.

**Example: **`opts = musynOptions('FullDG',false)`

creates an option
set for `musyn`

that causes the function to use diagonal scalings
for both D and G.

`FitOrder`

— Maximum order for fitting D and G scaling data

`[5 2]`

(default) | vector of two positive integers

Maximum order for fitting *D* and *G* scaling
data, specified as the comma-separated pair consisting of
`'FitOrder'`

and a vector of two positive integers. The integers
specify the maximum fit orders for the *D* and *G*
scalings, respectively. (For details about how the `musyn`

algorithm uses and fits scalings, see Robust Performance Measure for Mu Synthesis.)

For each iteration, `musyn`

fits each entry in the
*D* and *G* scaling matrices by a rational
function whose order is automatically selected. By default, the maximum order is 5 for
*D* scaling and 2 for *G* scaling.
(*G* scaling is for dynamics in addition to dynamics needed to
capture sign changes, so the final order of the *G* fit can be
higher.) In general, the higher the order of these functions, the higher the order of
the resulting controller.

To see whether you need to increase the maximum order, examine the
`musyn`

command-line display for a rough indication of fit
quality. The `Peak MU`

and `DG Fit`

columns of the
display give the best obtained robust performance before and after fitting,
respectively. If the value for any given iteration increases drastically after
fitting, you might obtain better results by increasing the maximum order.

Conversely, if the default maximum scaling order yields a good result, you can try
lowering the maximum order to see if `musyn`

returns a lower-order
controller with similar performance.

**Example: **`opts = musynOptions('FitOrder',[3 2])`

creates an option
set for `musyn`

that reduces the maximum fit order to 3 for the
*D* scaling and 2 for the *G*
scaling.

`FrequencyGrid`

— Frequency grid used for *μ* analysis

`[]`

(default) | vector of frequencies

Frequency grid used for *μ* analysis, specified as the
comma-separated pair consisting of `'FrequencyGrid'`

and an empty
vector or a vector of frequencies in radians per second. By default,
`musyn`

computes an appropriate frequency grid based on system
dynamics and the frequency dependence of the *D* and
*G* scaling data. This default generally yields better results than
a custom frequency grid, which restricts the computation to the specified frequencies
regardless of the actual frequency dependence of the scaling data. Therefore,
specifying frequencies is not recommended unless you know the frequency range in which
*D* and *G* vary.

**Options for K Step with Unstructured Controller (**

`hinfsyn`

Controller Design)`AutoScale`

— Automatic plant scaling

`'on'`

(default) | `'off'`

Automatic plant scaling, specified as the comma-separated pair consisting of
`'AutoScale'`

and one of the following:

`'on'`

— The underlying`hinfsyn`

computation in the*K*step automatically scales the plant states, controls, and measurements to improve numerical accuracy.`musyn`

always returns the controller in the original unscaled coordinates.`'off'`

—`hinfsyn`

does not change the plant scaling. Turning off scaling when you know your plant is well scaled can speed up the computation.

**Example: **`opts = musynOptions('AutoScale','off')`

creates an
option set for `musyn`

that turns off automatic scaling for the
underlying `hinfsyn`

computation.

`Regularize`

— Automatic regularization

`'on'`

(default) | `'off'`

Automatic regularization of the plant, specified as the comma-separated pair
consisting of `'Regularize'`

and one of the following:

`'on'`

— The underlying`hinfsyn`

computation in the*K*step automatically regularizes the plant to enforce certain nonsingularity requirements (see`hinfsyn`

). Regularization is a process of adding extra disturbances and errors to handle singular problems.`'off'`

—`hinfsyn`

does not regularize the plant. Turning off regularization can speed up the computation when you know your problem is far enough from singular.

**Example: **`opts = musynOptions('Regularize','off')`

creates an
option set for `musyn`

that turns off regularization for the
underlying `hinfsyn`

computation.

`LimitGain`

— Limit on controller gains

`'on'`

(default) | `'off'`

Limit on controller gains, specified as the comma-separated pair consisting of
`'LimitGain'`

and either `'on'`

or
`'off'`

. For continuous-time plants, regularization of plant
feedthrough matrices *D*_{12} or
*D*_{21} (see `hinfsyn`

) can result in controllers with large coefficients and fast
dynamics. Use this option to automatically seek a controller with the same performance
but lower gains and better conditioning.

**Options for K Step with Structured Controller (**

`hinfstruct`

Controller Design)`RandomStart`

— Number of starts with randomized parameter values

`0`

(default) | positive integer

Number of additional optimization starts with randomized values of tunable
controller parameters, specified as the comma-separated pair consisting of
`'RandomStart'`

and 0 or a positive integer.

By default, the underlying `hinfstruct`

computation performs a
single optimization run starting from the initial values of the tunable parameters.
`hinfstruct`

finds a local minimum of the gain minimization
problem. To mitigate the risk of premature termination due to a local minimum that is
not the best performing controller, you can perform multiple independent D-K iteration
runs initialized from different values of controller parameters. Setting
`RandomStart = N > 0`

runs
*N* additional `musyn`

optimizations starting
from *N* randomly generated parameter values.

Randomization only affects the initialization of the overall D-K iteration run. It
does not affect each call to `hinfstruct`

within a D-K iteration
run.

When all runs are complete, `musyn`

uses the best design that
results from the multiple runs.

Use with `'UseParallel' = true`

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

**Example: **`opts = musynOptions('RandomStart',5)`

creates an option
set for `musyn`

that runs the underlying
`hinfstruct`

computation a total of six times, using randomized
initial values for the tunable parameters.

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

**Example: **`opts = musynOptions('RandomStart',8,'UseParallel',true)`

creates an option set for `musyn`

that performs eight additional
randomized optimization runs, and turns on parallel computing for the underlying
`hinfstruct`

computation.

`MinDecay`

— Minimum decay rate for closed-loop poles

`1e-7`

(default) | positive scalar

Minimum decay rate for closed-loop poles, specified as the comma-separated pair
consisting of `'MinDecay'`

and a positive scalar value. The poles of
the closed-loop system are constrained 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.

`MaxFrequency`

— Maximum closed-loop natural frequency

`Inf`

(default) | positive scalar

Maximum closed-loop natural frequency, specified as the comma-separated pair
consisting of `'MaxFrequency'`

and `Inf`

or a
positive scalar value. Setting `MaxFrequency`

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

. To
let `musyn`

choose the closed-loop poles without such constraint,
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.

## Output Arguments

`opts`

— Options for `musyn`

`musyn`

options object

Options for the `musyn`

computation, returned as a
`musyn`

options object. Use the object as an input argument to
`musyn`

. For example:

[K,CLperf,info] = musyn(P,nmeas,ncont,opts);

## Version History

**Introduced in R2019b**

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