Description

sllin = slLinearizer(mdl) creates
an slLinearizer interface, sllin,
for linearizing the Simulink® model, mdl.
The interface adds the linear analysis points marked in the model
as analysis points of sllin.
The interface also adds the linear analysis points that imply an opening
as permanent openings.

sllin = slLinearizer(mdl,pt) adds
the specified point to the list of analysis points for sllin,
ignoring linear analysis points marked in the model.

sllin = slLinearizer(mdl,param) specifies
the parameters whose values you want to vary when linearizing the
model.

sllin = slLinearizer(mdl,blocksub) specifies
substitute linearizations of blocks and subsystems. Use this syntax,
for example, to specify a custom linearization for a block. You can
also use this syntax for blocks that do not linearize successfully,
such as blocks with discontinuities or triggered subsystems.

If you do not specify pt, the interface
adds the linear analysis points marked in the model as analysis points.
The interface also adds linear analysis points that imply an opening
as permanent openings.

Object Description

slLinearizer provides an interface between
a Simulink model and the linearization commands getIOTransfer, getLoopTransfer, getSensitivity, and getCompSensitivity. Use slLinearizer to
efficiently batch linearize a model. You can configure the slLinearizer interface
to linearize a model at a range of operating points and specify variations
for model parameter values. Use interface analysis points and permanent openings to
obtain linearizations for any open-loop or closed-loop transfer function
from a model. Analyze the stability, or time-domain or frequency-domain
characteristics of the linearized models.

If you changed any interface properties since the last linearization,
commands that extract linearizations from the slLinearizer interface
recompile the Simulink model. If you made calls to specific functions
since the last linearization, the commands also recompile the Simulink model.
These functions include addPoint, addOpening, removePoint, removeOpening, removeAllPoints,
and removeAllOpenings.

Examples

Create and Configure slLinearizer Interface for Batch Linear Analysis

Create an slLinearizer interface for the scdcascade model. Add analysis points to the interface to extract open- or closed-loop transfer functions from the model. Configure the interface to vary parameters and operating points.

Open the scdcascade model.

mdl = 'scdcascade';
open_system(mdl);

Create an slLinearizer interface for the model. Add the signals r, u1,|u2|, y1,|y2|, y1m, and y2m to the interface.

sllin = slLinearizer(mdl,{'r','u1','u2','y1','y2','y1m','y2m'});

scdcascade contains two PID Controller blocks, C1 and C2. Suppose you want to vary the proportional and integral gains of C2, Kp2 and Ki2, in the 10% range. Create a structure to specify the parameter variations.

params specifies a 3x5 parameter grid. Each point in this grid corresponds to a combination of the Kp2 and Ki2 parameter values.

Specify params as the Parameters property of sllin.

sllin.Parameters = params;

Now, when you use commands such as getIOTransfer, getLoopTransfer, getSensitivity, and getCompSensitivity, the software returns a linearization for each parameter grid point specified by sllin.Parameters.

Suppose you want to linearize the model at multiple snapshot times, for example at t = {0,1,2}. To do so, configure the OperatingPoints property of sllin.

sllin.OperatingPoints = [0 1 2];

You can optionally configure the linearization options and specify substitute linearizations for blocks and subsystems in your model. After fully configuring sllin, use the getIOTransfer, getLoopTransfer, getSensitivity, and getCompSensitivity commands to linearize the model as required.

The interface adds all the points specified by pt and
ignores their I/O types. The interface also adds all 'loopbreak' type
signals as permanent
openings.

param — Parameter samplesstructure | structure array

Parameter samples for linearizing mdl, specified
as:

Structure — Vary the value of a single parameter
by specifying param as a structure with the following
fields:

Name — Parameter name, specified
as a character vector or string. You can specify any model parameter
that is a variable in the model workspace, the MATLAB® workspace,
or a data dictionary. If the variable used by the model is not a scalar
variable, specify the parameter name as an expression that resolves
to a numeric scalar value. For example, to use the first element of
vector V as a parameter, use:

param.Name = 'V(1)';

Value — Parameter sample
values, specified as a double array.

For example, vary the value of parameter A in
the 10% range:

param.Name = 'A';
param.Value = linspace(0.9*A,1.1*A,3);

Structure array — Vary the value of multiple
parameters. For example, vary the values of parameters A and b in
the 10% range:

If param specifies tunable parameters only,
then the software batch linearizes the model using a single compilation.
If you also configure sllin.OperatingPoints with
operating point objects only, the software uses single model compilation.

To compute the offsets required by the LPV
System block, specify param, and set sllin.Options.StoreOffsets to true.
You can then return additional linearization information when calling
linearization functions such as getIOTransfer,
and extract the offsets using getOffsetsForLPV.

op — Operating point for linearizing mdloperating point object | array of operating point objects | vector of positive scalars

Operating point for linearizing mdl, specified
as:

Operating point object, created using findop with either a single operating
point specification, or a single snapshot time.

If you configure sllin.Parameters, then specify op as
one of the following:

Single operating point.

Array of operating point objects whose size matches
that of the parameter grid specified by the Parameters property.
When you batch linearize mdl, the software uses
only one model compilation. To obtain the operating points that correspond
to the parameter value combinations, batch trim your model using param before
linearization. For an example that uses the linearize command,
see Batch Linearize Model at Multiple Operating Points Derived from Parameter Variations.

Multiple snapshot times. When you batch linearize mdl,
the software simulates the model for each snapshot time and parameter
grid point combination. This operation can be computationally expensive.

Substitute linearizations for blocks and model subsystems, specified
as a structure or an n-by-1 structure array, where n is
the number of blocks for which you want to specify a linearization.
Use blocksub to specify a custom linearization
for a block or subsystem. For example, you can specify linearizations
for blocks that do not have analytic linearizations, such as blocks
with discontinuities or triggered subsystems.

You can batch linearize your model by specifying multiple substitute
linearizations for a block. Use this functionality, for example, to
study the effects of varying the linearization of a Saturation block
on the model dynamics.

Each substitute linearization structure has the following fields:

Name — Block path

Block path of the block for which you want to specify the linearization,
specified as a character vector or string.

Value — Substitute linearization

Substitute linearization for the block, specified as one of
the following:

Double — Specify the linearization of a SISO
block as a gain.

Array of doubles — Specify the linearization
of a MIMO block as an nu-by-ny array
of gain values, where nu is
the number of inputs and ny is
the number of outputs.

LTI model, uncertain state-space model, or uncertain
real object — The I/O configuration of the specified model
must match the configuration of the block specified by Name.
Using an uncertain model requires Robust Control Toolbox™ software.

Array of LTI models, uncertain state-space models,
or uncertain real objects — Batch linearize the model using
multiple block substitutions. The I/O configuration of each model
in the array must match the configuration of the block for which you
are specifying a custom linearization. If you:

Vary model parameters using param and
specify Value as a model array, the dimensions
of Value must match the parameter grid size.

Define block substitutions for multiple blocks, and
specify Value as an array of LTI models for more
than one block, the dimensions of the arrays must match.

Structure with the following fields:

Field

Description

Specification

Block linearization, specified as a character vector
that contains one of the following

The I/O configuration of the returned model must
match the configuration of the block specified by Name.

Type

Specification type, specified as one of the following:

'Expression'

'Function'

ParameterNames

Linearization function parameter names, specified as
a cell array of character vectors. Specify ParameterNames only
when Type = 'Function' and your block linearization
function requires input parameters. These parameters only impact the
linearization of the specified block.

You must also specify
the corresponding blocksub.Value.ParameterValues field.

ParameterValues

Linearization function parameter values, specified as
an vector of doubles. The order of parameter values must correspond
to the order of parameter names in blocksub.Value.ParameterNames.
Specify ParameterValues only when Type
= 'Function' and your block linearization function requires
input parameters.

options — Linearization algorithm optionslinearizeOptions option set

Properties

Parameter samples for linearizing mdl, specified
as a structure or a structure array.

Set this property using the param input
argument or dot notation (sllin.Parameters = param). param must
be one of the following:

Structure — Vary the value of a single parameter
by specifying param as a structure with the following
fields:

Name — Parameter name, specified
as a character vector or string. You can specify any model parameter
that is a variable in the model workspace, the MATLAB workspace,
or a data dictionary. If the variable used by the model is not a scalar
variable, specify the parameter name as an expression that resolves
to a numeric scalar value. For example, to use the first element of
vector V as a parameter, use:

param.Name = 'V(1)';

Value — Parameter sample
values, specified as a double array.

For example, vary the value of parameter A in
the 10% range:

param.Name = 'A';
param.Value = linspace(0.9*A,1.1*A,3);

Structure array — Vary the value of multiple
parameters. For example, vary the values of parameters A and b in
the 10% range:

If param specifies tunable parameters only,
then the software batch linearizes the model using a single compilation.
If you also configure sllin.OperatingPoints with
operating point objects only, the software uses single model compilation.

OperatingPoints

Operating points for linearizing mdl, specified
as an operating point object, array of operating point objects, or
array of positive scalars.

Set this property using the op input argument
or dot notation (sllin.OperatingPoints = op). op must
be one of the following:

Operating point object, created using findop with either a single operating
point specification, or a single snapshot time.

If you configure sllin.Parameters, then specify op as
one of the following:

Single operating point.

Array of operating point objects whose size matches
that of the parameter grid specified by the Parameters property.
When you batch linearize mdl, the software uses
only one model compilation. To obtain the operating points that correspond
to the parameter value combinations, batch trim your model using param before
linearization. For an example that uses the linearize command,
see Batch Linearize Model at Multiple Operating Points Derived from Parameter Variations.

Multiple snapshot times. When you batch linearize mdl,
the software simulates the model for each snapshot time and parameter
grid point combination. This operation can be computationally expensive.

BlockSubstitutions

Substitute linearizations for blocks and model subsystems, specified
as a structure or structure array.

Use this property to specify a custom linearization for a block
or subsystem. You also can use this syntax for blocks that do not
have analytic linearizations, such as blocks with discontinuities
or triggered subsystems.

Set this property using the blocksub input
argument or dot notation (sllin.BlockSubstitutions = blocksubs).
For information about the required structure, see blocksub.

Options

Linearization algorithm options, specified as an option set
created using linearizeOptions.

Set this property using the options input
argument or dot notation (sllin.Options = options).

Model

Name of the Simulink model to be linearized, specified
as a character vector by the input argument mdl.

More About

Analysis Points

Analysis points, used
by the slLinearizer and slTuner interfaces,
identify locations within a model that are relevant for linear analysis
and control system tuning. You use analysis points as inputs to the
linearization commands, such as getIOTransfer, getLoopTransfer, getSensitivity, and getCompSensitivity. As inputs to the
linearization commands, analysis points can specify any open-loop
or closed-loop transfer function in a model. You can also use analysis
points to specify design requirements when tuning control systems
using commands such as systune.

Location refers to a specific block output
port within a model or to a bus element in such an output port. For
convenience, you can use the name of the signal that originates from
this port to refer to an analysis point.

You can add analysis points to an slLinearizer or slTuner interface, s,
when you create the interface. For example:

To view all the analysis points of s, type s at
the command prompt to display the interface contents. For each analysis
point of s, the display includes the block name
and port number and the name of the signal that originates at this
point. You can also programmatically obtain a list of all the analysis
points using getPoints.

Permanent Openings

Permanent openings,
used by the slLinearizer and slTuner interfaces,
identify locations within a model where the software breaks the signal
flow. The software enforces these openings for linearization and tuning.
Use permanent openings to isolate a specific model component. Suppose
that you have a large-scale model capturing aircraft dynamics and
you want to perform linear analysis on the airframe only. You can
use permanent openings to exclude all other components of the model.
Another example is when you have cascaded loops within your model
and you want to analyze a specific loop.

Location refers to a specific block output
port within a model. For convenience, you can use the name of the
signal that originates from this port to refer to an opening.

You can add permanent openings to an slLinearizer or slTuner interface, s,
when you create the interface or by using the addOpening command. To remove a location
from the list of permanent openings, use the removeOpening command.

To view all the openings of s, type s at
the command prompt to display the interface contents. For each permanent
opening of s, the display includes the block name
and port number and the name of the signal that originates at this
location. You can also programmatically obtain a list of all the permanent
loop openings using getOpenings.

Custom Linearization Function

You can specify a substitute linearization
for a block or subsystem in your Simulink model
using a custom function on the MATLAB path.

Your custom linearization function must have one BlockData input
argument, which is a structure that the software creates and passes
to the function. BlockData has the following fields:

Field

Description

BlockName

Name of the block for which you are specifying a custom linearization.

Parameters

Block parameter values, specified as a structure array with Name and Value fields. Parameters contains
the names and values of the parameters you specify in the blocksub.Value.ParameterNames and blocksub.Value.ParameterValues fields.

Inputs

Input signals to the block for which you are defining a linearization,
specified as a structure array with one structure for each block input.
Each structure in Inputs has the following fields:

Field

Description

BlockName

Full block path of the block whose output connects to the corresponding
block input.

PortIndex

Output port of the block specified by BlockName that
connects to the corresponding block input.

Values

Value of the signal specified by BlockName and PortIndex.
If this signal is a vector signal, then Values is
a vector with the same dimension.

ny

Number of output channels of the block linearization.

nu

Number of input channels of the block linearization.

BlockLinearization

Current default linearization of the block, specified as a
state-space model. You can specify a block linearization that depends
on the default linearization using BlockLinearization.

Your custom function must return a model with nu inputs
and ny outputs. This model must be one of the following:

For example, the following function multiplies the current default
block linearization by a delay of Td = 0.5 seconds.
The delay is represented by a Thiran filter with sample time Ts
= 0.1. The delay and sample time are parameters stored in BlockData.