# wcOptions

Option set for worst-case analysis

## Description

returns the default option set for
worst-case analysis commands such as `opts`

= wcOptions`wcgain`

, `wcdiskmargin`

,
or `wcsigmaplot`

.

creates
an option set with the options specified by one or more `opts`

= wcOptions(`Name,Value`

,...)`Name,Value`

pair
arguments.

## Examples

### Options for Worst-Case Gain Calculation

Create an options set to calculate the worst-case gain while allowing the uncertain parameters to vary by 20% more than the range specified in the model. Also, configure the options to include the element-by-element sensitivity in the calculation.

opts = wcOptions('ULevel',1.2,'Sensitivity','on');

Alternatively, create a default option set, and use dot notation to set the values of particular options.

```
opts = wcOptions;
opts.ULevel = 1.2;
opts.Sensitivity = 'on';
```

Use `opts`

as an input argument to a worst-case analysis command such as `wcgain`

.

### Improve Worst-Case Perturbation

Specifying certain options for the structured-singular-value computation that underlies the worst-gain computation can yield better results in some cases. For example, consider a sample plant and controller.

`load('wcgExampleData.mat')`

This command loads `gPlant`

, a MIMO plant with 10 outputs, 8 inputs, and 11 uncertain elements. It also loads `Kmu`

, a state-space controller model. Form a closed-loop system with these models, and examine the worst-case gain.

CL = lft(gPlant,Kmu); [wcg,wcu] = wcgain(CL); wcg

`wcg = `*struct with fields:*
LowerBound: 10.8742
UpperBound: 11.2135
CriticalFrequency: 6.6794

There is a large difference between the lower and upper bounds on the worst-case gain. To get a better estimate of the actual worst-case gain, increase the number of restarts that `wcgain`

uses for computing of the worst-case perturbation and associated lower bound. Doing so can result in a tighter lower bound. This option does not affect the upper-bound calculation.

opt = wcOptions('MussvOptions','m3'); [wcg,wcu] = wcgain(CL,opt); wcg

`wcg = `*struct with fields:*
LowerBound: 10.8742
UpperBound: 11.2135
CriticalFrequency: 6.6794

The difference between the lower bound and upper bound on the worst-case gain is much smaller. The critical frequency is different as well.

## 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: **`'ULevel','1.5','Sensitivity','on'`

`ULevel`

— Uncertainty level

1 (default) | positive scalar

Uncertainty level to use for the worst-case computation, specified
as the comma-separated pair consisting of `'ULevel'`

and
a positive scalar value. This option scales the normalized uncertainty
by the factor you specify. Such scaling lets you examine the effect
of smaller or larger uncertainty range without changing the uncertainty
levels in your model. For instance, to see the effect of doubling
the ranges of all uncertain parameters, set `'ULevel'`

to
2. To see the effect of shrinking the ranges, set `'ULevel'`

to
0.5. The default value, 1, corresponds to the amount of uncertainty
specified in the model.

`Display`

— Display progress of computation and summary report

`'off'`

(default) | `'on'`

Display progress and summary report of the worst-case gain computation,
specified as the comma-separated pair consisting of `'Display'`

and
one of these values:

`'off'`

— Do not display progress and report.`'on'`

— Display progress and report. When you use this option, a progress indicator and summary of results is displayed in the command window, similar to the following.The worst-case gain is at most 11.2. -- There is a bad perturbation amounting to 100% of the modeled uncertainty. -- This perturbation causes a gain of 9.03 at the frequency 5.5 rad/seconds.

This setting overrides the silent (`'s'`

) option
in the `MussvOptions`

option.

`VaryFrequency`

— Compute worst-case gain as function of frequency

`'off'`

(default) | `'on'`

Return worst-case gain as a function of frequency, specified
as the comma-separated pair consisting of `'VaryFrequency'`

and
one of these values:

`'off'`

— Only return worst-case gains at frequencies where the worst values occur.`'on'`

— Compute worst-case gains over a frequency grid suitable for plotting. The frequency grid is chosen automatically based on system dynamics. This calculation is done in addition to identifying the critical frequency where the gain peaks. Access the frequency values and corresponding gains in the`info`

output of`wcgain`

or other worst-case analysis command.

This option is ignored for `ufrd`

and `genfrd`

models.

`Sensitivity`

— Calculate sensitivity of worst-case gains

`'off'`

(default) | `'on'`

Calculate the sensitivity of the worst-case gain to each uncertain
element in the model, specified as the comma-separated pair consisting
of `'Sensitivity'`

and either `'off'`

or `'on'`

.

Each uncertain element contributes to the overall worst case
in a coupled manner. Set this option to `'on'`

to
estimate the sensitivity of the margin to each element. This element-by-element
sensitivity provides an indication of which elements are most problematic.
Access the sensitivity estimates in the `info`

output
of the worst-case computation command.

`SensitivityPercent`

— Percentage variation of uncertainty for computing sensitivity

25 (default) | positive scalar value

Percentage variation of uncertainty level for computing sensitivity,
specified as the comma-separated pair consisting of `'SensitivityPercent'`

and
a positive scalar value. The sensitivity to a particular uncertain
element is estimated using a finite difference calculation. This calculation
increases the (normalized) amount of uncertainty on this element by
some percentage, computes the resulting worst-case gain, and computes
the ratio of percent variations. This option specifies the percentage
increase in uncertainty level applied to each element. The default
value is 25%.

`MussvOptions`

— Options for `mussv`

calculation

`''`

(default) | character vector

Options for the `mussv`

calculation that
underlies the worst-case calculations, specified as the comma-separated
pair consisting of `'MussvOptions'`

and a character
vector such as `'sm3'`

or `'ad'`

.

Some `MussvOptions`

values that are especially
useful for improving worst-case calculations include:

`'a'`

— Force the use of LMI optimization to compute the*μ*upper bound, which yields better results in general but can be expensive when some`ureal`

elements are repeated multiple times.`'mN'`

— Use multiple restarts when computing the*μ*lower bound, which corresponds to the lower bound for the worst-case gain. This option can reduce the gap between the lower bound and upper bound on the worst-case gains.`N`

is the number of restarts. For example, setting`'MussvOptions'`

to`'m3'`

causes three restarts. See Improve Worst-Case Perturbation for an example.

See `mussv`

for the remaining
available options and corresponding characters. The default, `''`

,
uses the default options for `mussv`

.

## Output Arguments

`opts`

— Options for worst-case calculations

`wcOptions`

object

Options for worst-case calculations, returned as a `wcOptions`

object. Use
the options as an input argument to any of the worst-case analysis functions, such as
`wcgain`

and `wcsigmaplot`

. For example:

[wcgain,wcu,info] = wcgain(usys,opts)

## Version History

**Introduced in R2016b**

### R2016b: `wcOptions`

replaces `wcgainOptions`

and `wcmarginOptions`

`wcOptions`

replaces `wcgainOptions`

and
`wcmarginOptions`

, which are no longer recommended. To define options
for commands such as `wcgain`

and `wcmargin`

, use
`wcOptions`

.

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