Main Content

robOptions

Option set for robustness analysis

Description

example

opts = robOptions returns the default option set for robustness analysis commands robstab and robgain, and for musynperf.

example

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

Examples

collapse all

Create an options set for a robstab, robgain, or musynperf calculation that displays the progress of the underlying mussv calculation. Also, turn on the element-by-element sensitivity calculation.

opts = robOptions('Display','on','Sensitivity','on');

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

opts = robOptions;
opts.Display = 'on';
opts.Sensitivity = 'on';

Use opts as an input argument to robstab, robgain, or musynperf.

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: 'Display','on','Sensitivity','on'

Display progress and summary of the robustness 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.

    points completed (of 28) ... 28
    System is robustly stable for the modeled uncertainty.
     -- It can tolerate up to 116% of the modeled uncertainty.
     -- There is a destabilizing perturbation amounting to 117% of the modeled uncertainty.
     -- This perturbation causes an instability at the frequency 5.9 rad/seconds.

This setting overrides the silent ('s') option in the MussvOptions option.

Return robustness margin as a function of frequency, specified as the comma-separated pair consisting of 'VaryFrequency' and one of these values:

  • 'off' — Only return margins at frequencies where robustness is weakest.

  • 'on' — Compute robustness margins 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 margin is weakest. Access the frequency values and corresponding margins in the info output of robstab and robgain.

This option is ignored for ufrd and genfrd models.

Calculate the sensitivity of the robustness margin 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 stability margin 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 for robustness. Access the sensitivity estimates in the info output of robstab and robgain.

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 robustness, 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 underlying mussv calculation that robstab and robgain perform, 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 robustness-margin 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 upper bound for robustness margins. This option can reduce the gap between the lower bound and upper bound on the robustness margins. N is the number of restarts. For example, setting 'MussvOptions' to 'm3' causes three restarts.

See mussv for the remaining available options and corresponding characters. The default, '', uses the default options for mussv.

Output Arguments

collapse all

Options for robustness commands robstab, robgain, and musynperf, returned as a robOptions object. Use the options as an input argument to robstab, robgain, or musynperf. For example:

[stabmarg,wcu,info] = robstab(usys,opts)

Version History

Introduced in R2016b

expand all