Main Content

systuneOptions

Set options for systune

collapse all in page

Syntax

options = systuneOptions
options = systuneOptions(Name,Value)

Description

options = systuneOptions returns the default option set for the systune command.

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

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.

systuneOptions takes the following Name arguments:

Display

Amount of information to display during systune runs.

Display takes the following values:

  • 'final' — Display a one-line summary at the end of each optimization run. The display includes the best achieved values for the soft and hard constraints, fSoft and gHard. The display also includes the number of iterations for each run.

    Example:

    Final: Soft = 1.09, Hard = 0.68927, Iterations = 58

  • 'sub' — Display the result of each optimization subproblem.

    When you use both soft and hard tuning goals, the software solves the optimization as a sequence of subproblems of the form:

    minx  max(αf(x),g(x)).

    Here, x is the vector of tunable parameters, f(x) is the largest normalized soft-constraint value, and g(x) is the largest normalized hard-constraint value. (See the “Algorithms” section of the systune reference page for more information.) The software adjusts the multiplier α so that the solution of the subproblems converges to the solution of the original constrained optimization problem. When you select 'sub', the report includes the results of each of these subproblems.

    Example:

    alpha=0.1: Soft = 3.97, Hard = 0.68927, Iterations = 8
alpha=0.5036: Soft = 1.36, Hard = 0.68927, Iterations = 8
alpha=1.47: Soft = 1.09, Hard = 0.68927, Iterations = 42
Final: Soft = 1.09, Hard = 0.68927, Iterations = 58

  • 'iter' — Display optimization progress after each iteration. The display includes the value after each iteration of the objective parameter being minimized. The objective parameter is whichever is larger of αf(x) and g(x). The display also includes a progress value that indicates the percent change in the constraints from the previous iteration.

    Example:

    Iter 1: Objective = 4.664, Progress = 93%
Iter 2: Objective = 2.265, Progress = 51.4%
Iter 3: Objective = 0.7936, Progress = 65%
Iter 4: Objective = 0.7183, Progress = 9.48%
Iter 5: Objective = 0.6893, Progress = 4.04%
Iter 6: Objective = 0.6893, Progress = 0%
Iter 7: Objective = 0.6893, Progress = 0%
Iter 8: Objective = 0.6893, Progress = 0%
alpha=0.1: Soft = 3.97, Hard = 0.68927, Iterations = 8
Iter 1: Objective = 1.146, Progress = 42.7%
Iter 2: Objective = 1.01, Progress = 11.9%
...
alpha=1.47: Soft = 1.09, Hard = 0.68927, Iterations = 42
Final: Soft = 1.09, Hard = 0.68927, Iterations = 58

  • 'off' — Run in silent mode, displaying no information during or after the run.

Default: 'final'

MaxIter

Maximum number of iterations in each optimization run, when the run does not converge to within tolerance.

Default: 300

RandomStart

Number of additional optimizations starting from random values of the free parameters in the controller.

If RandomStart = 0, systune performs a single optimization run starting from the initial values of the tunable parameters. Setting RandomStart = N > 0 runs N additional optimizations starting from N randomly generated parameter values.

systune tunes by finding a local minimum of a gain minimization problem. To increase the likelihood of finding parameter values that meet your design requirements, set RandomStart > 0. You can then use the best design that results from the multiple optimization runs.

Use with UseParallel = true to distribute independent optimization runs among MATLAB® workers (requires Parallel Computing Toolbox™ software).

Default: 0

UseParallel

Parallel processing flag.

When you use the RandomStart option to run multiple randomized optimization starts, you can also use parallel computing to speed up tuning by distributing the optimization runs among workers in a parallel pool. Set this flag to true to enable parallel processing. 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 Automatically create a parallel pool is selected in your Parallel Computing Toolbox preferences (Parallel Computing Toolbox), then the software starts a parallel pool using the settings in those preferences.

  • If Automatically create a parallel pool is not selected in your preferences, then the software performs the optimization runs successively, without parallel processing.

If Automatically create a parallel pool is not selected in your preferences, you can manually start a parallel pool using parpool (Parallel Computing Toolbox) before running the tuning command.

Using parallel processing requires Parallel Computing Toolbox software.

Default: false

SkipModels

Models or design points to ignore, specified as an array of linear indices.

Use this option to skip specific models or ignore portions of the design space when tuning gain-scheduled control systems. For example, you might want to skip grid points outside the flight envelope of an airplane model, or points outside the operating range for tuning. Identify the models to skip by absolute index in the array of models to tune. Using SkipModels lets you narrow the scope of tuning without reconfiguring each tuning goal. For more information, see Change Requirements with Operating Condition.

Default: []

SoftTarget

Target value for soft constraints.

The optimization stops when the largest soft constraint value falls below the specified SoftTarget value. The default value SoftTarget = 0 minimizes the soft constrains subject to satisfying the hard constraints.

Default: 0

SoftTol

Relative tolerance for termination.

The optimization terminates when the relative decrease in the soft constraint value decreases by less than SoftTol over 10 consecutive iterations. Increasing SoftTol speeds up termination, and decreasing SoftTol yields tighter final values.

Default: 0.001

SoftScale

A priori estimate of best soft constraint value.

For problems that mix soft and hard constraints, providing a rough estimate of the optimal value of the soft constraints (subject to the hard constraints) helps to speed up the optimization.

Default: 1

MinDecay

Minimum decay rate for stabilized dynamics.

Most tuning goals carry an implicit closed-loop stability or minimum-phase constraint. Stabilized dynamics refers to the poles and zeros affected by these constraints. The MinDecay option constrains all stabilized poles and zeros to satisfy:

  • Re(s) < -MinDecay (continuous time).

  • log(|z|) < -MinDecay (discrete time).

Adjust the minimum value if the optimization fails to meet the default value, or if the default value conflicts with other requirements. Alternatively, use TuningGoal.Poles to control the decay rate of a specific feedback loop.

For more information about implicit constraints for a particular tuning goal, see the reference page for that tuning goal.

Default: 1e-7

MaxRadius

Maximum spectral radius for stabilized dynamics.

This option constrains all stabilized poles and zeros to satisfy |s| < MaxRadius. Stabilized dynamics are those poles and zeros affected by implicit stability or minimum-phase constraints of the tuning goals. The MaxRadius constraint is useful to prevent these poles and zeros from going to infinity as a result of algebraic loops becoming singular or control effort growing unbounded. Adjust the maximum radius if the optimization fails to meet the default value, or if the default value conflicts with other requirements.

MaxRadius is ignored for discrete-time tuning, where stability constraints already impose |z| < 1.

For more information about implicit constraints for a particular tuning goal, see the reference page for that tuning goal.

Default: 1e8

Output Arguments

options

Option set containing the specified options for the systune command.

Examples

collapse all

Open Live Script

Create an options set for a systune run using five random restarts. Also, set the display level to show the progress of each iteration, and increase the relative tolerance of the soft constraint value to 0.01. 

options = systuneOptions('RandomStart',5,'Display','iter',...
                         'SoftTol',0.01);

Alternatively, use dot notation to set the values of options. 

options = systuneOptions;
options.RandomStart = 5;
options.Display = 'iter';
options.SoftTol = 0.01;

Configure an option set for a systune run using 20 random restarts. Execute these independent optimization runs concurrently on multiple workers in a parallel pool.

If you have the Parallel Computing Toolbox software installed, you can use parallel computing to speed up systune tuning of fixed-structure control systems. When you run multiple randomized systune optimization starts, parallel computing speeds up tuning by distributing the optimization runs among workers.

If Automatically create a parallel pool is not selected in your Parallel Computing Toolbox preferences (Parallel Computing Toolbox), manually start a parallel pool using parpool (Parallel Computing Toolbox). For example:

parpool;

If Automatically create a parallel pool is selected in your preferences, you do not need to manually start a pool.

Create a systuneOptions set that specifies 20 random restarts to run in parallel.

options = systuneOptions('RandomStart',20,'UseParallel',true);

Setting UseParallel to true enables parallel processing by distributing the randomized starts among available workers in the parallel pool.

Use the systuneOptions set when you call systune. For example, suppose you have already created a tunable control system model, CLO. For tuning this system, you have created vectors SoftReqs and HardReqs of TuningGoal requirements objects. These vectors represent your soft and hard constraints, respectively. In that case, the following command uses parallel computing to tune the control system of CL0. 

[CL,fSoft,gHard] = systune(CL0,SoftReqs,HardReqs,options);

Version History

Introduced in R2016a

expand all

See Also

| (Simulink Control Design)