wcOptions
Option set for worst-case analysis
Description
returns the default option set for
worst-case analysis commands such as opts
= wcOptionswcgain
, 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 theinfo
output ofwcgain
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 someureal
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 R2016bR2016b: 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
.
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)