Main Content

linearizeOptions

Set linearization options

collapse all in page

Syntax

options = linearizeOptions
options = linearizeOptions(Name,Value)

Description

options = linearizeOptions returns the default linearization option set.

example

options = linearizeOptions(Name,Value) returns an option set with additional options specified by one or more Name,Value pair arguments.

Examples

collapse all

Open Live Script

Create a linearization option set that sets the rate conversion method to the Tustin method with prewarping at a frequency of 10 rad/s. Additionally, instruct the linearization not to omit blocks outside the linearization path.

options = linearizeOptions('RateConversionMethod','prewarp',...
                           'PreWarpFreq',10,...
                           'BlockReduction','off');

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

options = linearizeOptions;
options.RateConversionMethod = 'prewarp';
options.PreWarpFreq = 10;
options.BlockReduction = 'off';

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: 'RateConversionMethod','prewarp' sets the rate conversion method to the Tustin method with prewarping.

Algorithm used for linearization, specified as the comma-separated pair consisting of 'LinearizationAlgorithm' and one of the following:

  • 'blockbyblock' — Individually linearize each block in the model, and combine the results to produce the linearization of the specified system.

  • 'numericalpert' — Full-model numerical-perturbation linearization in which root-level inports and states are perturbed using forward differences; that is, by adding perturbations to the input and state values. This perturbation method is typically faster than the 'numericalpert2' method.

  • 'numericalpert2' — Full-model numerical-perturbation linearization in which root-level inports and states are numerically perturbed using central differences; that is, by perturbing the input and state values in both positive and negative directions. This perturbation method is typically more accurate than the 'numericalpert' method.

The numerical perturbation linearization methods ignore linear analysis points set in the model and use root-level inports and outports instead.

Block-by-block linearization has several advantages over full-model numerical perturbation:

  • Many Simulink® blocks have a preprogrammed exact linearization.

  • You can use linear analysis points to specify a portion of the model to linearize.

  • You can configure blocks to use custom linearizations without affecting your model simulation.

  • Structurally nonminimal states are automatically removed.

  • You can specify linearizations that include uncertainty (requires Robust Control Toolbox™ software).

  • You can obtain detailed diagnostic information about the linearization.

Sample time of linearization result, specified as the comma-separated pair consisting of 'SampleTime' and one of the following:

  • -1 — Set the sample time to the least common multiple of the nonzero sample times in the model.

  • 0 — Create a continuous-time model.

  • Positive scalar — Specify the sample time for discrete-time systems.

Flag indicating whether to truncate names of I/Os and states in the linearized model, specified as the comma-separated pair consisting of 'UseFullBlockNameLabels' and either:

  • 'off' — Use truncated names for the I/Os and states in the linearized model.

  • 'on' — Use the full block path to name the I/Os and states in the linearized model.

Flag indicating whether to use bus signal channel numbers or names to label the I/Os in the linearized model, specified as the comma-separated pair consisting of 'UseBusSignalLabels' and one of the following:

  • 'off' — Use bus signal channel numbers to label I/Os on bus signals in the linearized model.

  • 'on' — Use bus signal names to label I/Os on bus signals in the linearized model. Bus signal names appear in the results when the I/O points are located at the output of the following blocks:

    • Root-level inport block containing a bus object

    • Bus creator block

    • Subsystem block whose source traces back to the output of a bus creator block

    • Subsystem block whose source traces back to a root-level inport by passing through only virtual or nonvirtual subsystem boundaries

Flag indicating whether to compute linearization offsets for inputs, outputs, states, and state derivatives or updated states, specified as the comma-separated pair consisting of 'StoreOffsets' and one of the following:

  • false — Do not compute linearization offsets.

  • true — Compute linearization offsets.

You can configure an LPV System block using linearization offsets. For an example, see Approximate Nonlinear Behavior Using Array of LTI Systems

Flag indicating whether to store diagnostic information during linearization, specified as the comma-separated pair consisting of 'StoreAdvisor' and one of the following:

  • false — Do not store linearization diagnostic information.

  • true — Store linearization diagnostic information.

Linearization commands store and return diagnostic information in a LinearizationAdvisor object. For an example of troubleshooting linearization results using a LinearizationAdvisor object, see Troubleshoot Linearization Results at Command Line.

Flag indicating whether to omit blocks that are not in the linearization path, specified as the comma-separated pair consisting of 'BlockReduction' and one of the following:

  • 'on' — Return a linearized model that does not include states from noncontributing linearization paths.

  • 'off' — Return a linearized model that includes all the states of the model.

Dead linearization paths can include:

  • Blocks that linearize to zero.

  • Switch blocks that are not active along the path.

  • Disabled subsystems.

  • Signals marked as open-loop linearization points.

For example, if this flag set to 'on', the linearization result of the model shown in the following figure includes only two states. It does not include states from the two blocks outside the linearization path. These states do not appear because these blocks are on a dead linearization path with a block that linearizes to zero (the zero gain block).

This option applies only when LinearizationAlgorithm is 'blockbyblock'. BlockReduction is always treated as 'on' when LinearizationAlgorithm is 'numericalpert' or 'numericalpert2'.

Flag indicating whether to remove discrete-time states from the linearization, specified as the comma-separated pair consisting of 'IgnoreDiscreteStates' and one of the following:

  • 'off' — Always include discrete-time states.

  • 'on' — Remove discrete states from the linearization. Use this option when performing continuous-time linearization (SampleTime = 0) to accept the D value for all blocks with discrete-time states.

This option applies only when LinearizationAlgorithm is 'blockbyblock'.

Method used for rate conversion when linearizing a multirate system, specified as the comma-separated pair consisting of 'RateConversionMethod' and one of the following:

  • 'zoh' — Zero-order hold rate conversion method

  • 'tustin' — Tustin (bilinear) method

  • 'prewarp' — Tustin method with frequency prewarp. When you use this method, set the PreWarpFreq option to the desired prewarp frequency.

  • 'upsampling_zoh' — Upsample discrete states when possible, and use 'zoh' otherwise.

  • 'upsampling_tustin' — Upsample discrete states when possible, and use 'tustin' otherwise.

  • 'upsampling_prewarp' — Upsample discrete states when possible, and use 'prewarp' otherwise. When you use this method, set the PreWarpFreq option to the desired prewarp frequency.

For more information on rate conversion and linearization of multirate models, see:

Note

If you use a rate conversion method other than 'zoh', the converted states no longer have the same physical meaning as the original states. As a result, the state names in the resulting LTI system change to '?'.

This option applies only when LinearizationAlgorithm is 'blockbyblock'.

Prewarp frequency in rad/s, specified as the comma-separated pair consisting of 'PreWarpFreq' and a nonnegative scalar. This option applies only when RateConversionMethod is either 'prewarp' or 'upsampling_prewarp'.

Flag indicating whether to compute linearization with exact delays, specified as the comma-separated pair consisting of 'UseExactDelayModel' and one of the following:

  • 'off' — Return a linear model with approximate delays.

  • 'on' — Return a linear model with exact delays.

This option applies only when LinearizationAlgorithm is 'blockbyblock'.

Flag indicating whether to recompile the model when varying parameter values for linearization, specified as the comma-separated pair consisting of 'AreParamsTunable' and one of the following:

  • true — Do not recompile the model when all varying parameters are tunable. If any varying parameters are not tunable, recompile the model for each parameter grid point, and issue a warning message.

  • false — Recompile the model for each parameter grid point. Use this option when you vary the values of nontunable parameters.

For more information about model compilation when you linearize with parameter variation, see Batch Linearization Efficiency When You Vary Parameter Values.

Numerical perturbation level, specified as the comma-separated pair consisting of 'NumericalPertRel' and a positive scalar. This option applies only when LinearizationAlgorithm is 'numericalpert' or 'numericalpert2'.

The perturbation levels for the system states are:

NumericalPertRel+10−3×NumericalPertRel×|x|

The perturbation levels for the system inputs are:

NumericalPertRel+10−3×NumericalPertRel×|u|

You can override these values using the NumericalXPert or NumericalUPert options.

State perturbation levels, specified as the comma-separated pair consisting of 'NumericalXPert' and an operating point object. This option applies only when LinearizationAlgorithm is 'numericalpert' or 'numericalpert2'.

To set individual perturbation levels for each state:

  1. Create an operating point object for the model using the operpoint command.

    xPert = operpoint('watertank');

  2. Set the state values in the operating point object to the perturbation levels.

    xPert.States(1).x = 2e-3;
xPert.States(2).x = 3e-3;

  3. Set the value of the NumericalXPert option to the operating point object.

    opt = linearizeOptions('LinearizationAlgorithm','numericalpert');
opt.NumericalXPert = xPert;

If NumericalXPert is empty, [], the linearization algorithm derives the state perturbation levels using NumericalPertRel.

Input perturbation levels, specified as the comma-separated pair consisting of 'NumericalUPert' and an operating point object. This option applies only when LinearizationAlgorithm is 'numericalpert' or 'numericalpert2'.

To set individual perturbation levels for each input:

  1. Create an operating point object for the model using the operpoint command.

    uPert = operpoint('watertank');

  2. Set the input values in the operating point object to the perturbation levels.

    uPert.Inputs(1).x = 3e-3;

  3. Set the value of the NumericalUPert option to the operating point object.

    opt = linearizeOptions('LinearizationAlgorithm','numericalpert');
opt.NumericalUPert = uPert;

If NumericalUPert is empty, [], the linearization algorithm derives the input perturbation levels using NumericalPertRel.

Output Arguments

collapse all

Linearization options, returned as a linearizeOptions option set.

Version History

Introduced in R2013b

See Also

| | (Robust Control Toolbox) |