Main Content

wcOptions

Option set for worst-case analysis

collapse all in page

Syntax

opts = wcOptions
opts = wcOptions(Name,Value,...)

Description

opts = wcOptions returns the default option set for worst-case analysis commands such as wcgain, wcdiskmargin, or wcsigmaplot.

example

opts = wcOptions(Name,Value,...) creates an option set with the options specified by one or more Name,Value pair arguments.

example

Examples

collapse all

Open Live Script

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.

Open Live Script

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

collapse all

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'

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

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.

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.

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

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

collapse all

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

expand all

See Also

| |

Topics