slLinearizer

Interface for batch linearization of Simulink models

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. You can use analysis points and permanent openings to obtain linearizations for any open-loop or closed-loop transfer function from a model. You can then analyze the stability, or time-domain or frequency-domain characteristics of the linearized models.

If you add or remove any analysis points or openings or change any other interface properties, commands that extract linearizations from the slLinearizer interface recompile the Simulink model.

The model linearization is automatically updated when you change any properties of the slLinearizer interface. The update occurs when you call commands that query the linearization stored in the interface, such as getIOTransfer, getLoopTransfer, getSensitivity, and getCompsensitivity.

An slLinearizer interface linearizes your Simulink model using the algorithms described in Exact Linearization Algorithm.

Creation

Syntax

sllin = slLinearizer(model)

sllin = slLinearizer(model,pt)

sllin = slLinearizer(model,param)

sllin = slLinearizer(model,op)

sllin = slLinearizer(model,blocksub)

sllin = slLinearizer(model,opt)

sllin = slLinearizer(model,pt,op,param,blocksub,options)

Description

sllin = slLinearizer(model) returns an slLinearizer interface for linearizing the Simulink model model and sets the Model property. The interface adds the linear analysis points marked in the model as analysis points and also adds the linear analysis points that imply an opening as permanent openings.

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

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

sllin = slLinearizer(model,op) specifies the operating points for linearizing the model and sets the OperatingPoints property to op.

sllin = slLinearizer(model,blocksub) specifies substitute linearizations of blocks and subsystems and sets the BlockSubstitutions property to blocksub. 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.

sllin = slLinearizer(model,opt) configures the linearization algorithm options and sets the Options property to opt.

sllin = slLinearizer(model,pt,op,param,blocksub,options) creates an slLinearizer interface using any combination of pt, op, param, blocksub, and options in any order.

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.

Input Arguments

pt — Analysis points

character vector | string | cell array of character vectors | string array | vector of linearization I/O objects

Analysis points to add to the slLinearizer interface, specified as one of the following:

• Character vector or string — Analysis point identifier that can be any of the following:

  • Signal name, for example pt = 'torque'

  • Block path for a block with a single output port, for example pt = 'Motor/PID'

  • Block path and port originating the signal, for example pt = 'Engine Model/1'

• Cell array of character vectors or string array — Specifies multiple analysis point identifiers. For example:

  pt = {'torque','Motor/PID','Engine Model/1'}

• Vector of linearization I/O objects — Create pt using linio. For example:

  pt(1) = linio('scdcascade/setpoint',1,'input');
  pt(2) = linio('scdcascade/Sum',1,'output');

  Here, pt(1) specifies an input, and pt(2) specifies an output.

  The interface adds all the points specified by pt and ignores their I/O types. The interface also adds all signals that imply a loop opening as permanent openings.

For more information, see Analysis Points and Permanent Openings.

Properties

Model — Model name

string | character vector

Model name, specified as a character vector or string.

Options — Linearization algorithm options

linearizeOptions option set

Linearization algorithm options, specified as a linearizeOptions object.

OperatingPoints — Operating point for linearizing model

OperatingPoint object | array of OperatingPoint objects | vector of positive scalars | OperatingReport object | array of OperatingReport objects

Operating point for linearizing model, specified as:

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

• Array of OperatingPoint or OperatingReport objects, specifying multiple operating points.

  To create an array of OperatingPoint or OperatingReport objects, you can:

  • Extract operating points at multiple snapshot times using findop.

  • Batch trim your model using multiple operating point specifications. For more information, see Batch Compute Steady-State Operating Points for Multiple Specifications.

  • Batch trim your model using parameter variations. For more information, see Batch Compute Steady-State Operating Points for Parameter Variation.

• Vector of positive scalars, specifying simulation snapshot times.

If you configure the Parameters property, then specify OperatingPoints as one of the following:

• Single OperatingPoint or OperatingReport object.

• Array of OperatingPoint or OperatingReport 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.

If you do not specify OperatingPoints, the slLinearizer interface uses the model initial condition.

Parameters — Parameter samples

structure | structure array

Parameter samples for linearizing model, specified as one of the following:

• Structure — Vary the value of a single parameter by specifying parameters 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, use the first element of vector V as a parameter.

    parameters.Name = 'V(1)';

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

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

  parameters.Name = 'A';
  parameters.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.

  [A_grid,b_grid] = ndgrid(linspace(0.9*A,1.1*A,3),...
                           linspace(0.9*b,1.1*b,3));
  parameters(1).Name = 'A';
  parameters(1).Value = A_grid;
  parameters(2).Name = 'b';
  parameters(2).Value = b_grid;

For more information, see Specify Parameter Samples for Batch Linearization.

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

For an example showing how batch linearization with parameter sampling works, see Vary Parameter Values and Obtain Multiple Transfer Functions.

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

BlockSubstitutions — Substitute linearizations for blocks and model subsystems

structure | structure array

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 BlockSubstitutions 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.

To study the effects of varying the linearization of a block on the model dynamics, you can batch linearize your model by specifying multiple substitute linearizations for a block.

If you substitute a linearization with a sample time that differs from that of the original block or subsystem, it is best practice to set the overall linearization sample time (Options.SampleTime) to a nondefault value.

Each substitute linearization structure has the following fields.

Name — Block path

character vector | string

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

Value — Substitute linearization

double | double array | LTI model | model array | structure

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 n_u-by-n_y array of gain values, where n_u is the number of inputs and n_y 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 theParameters property 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: MATLAB expression Name of a Custom Linearization Function in your current working directory or on the MATLAB path. The specified expression or function must return one of the following: Linear model in the form of a D-matrix Control System Toolbox™ LTI model object Uncertain state-space model or uncertain real object (requires Robust Control Toolbox software) 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 ParameterValues field.
  ParameterValues	Linearization function parameter values, specified as a vector of doubles. The order of parameter values must correspond to the order of parameter names in the ParameterNames field. Specify ParameterValues only when Type = 'Function' and your block linearization function requires input parameters.

TimeUnit — Time units for linearized models

'seconds' (default) | 'minutes' | 'hours' | 'milliseconds' | 'microseconds' | ...

Time units for linearized models computed by getIOTransfer, getLoopTransfer, getSensitivity, and getCompSensitivity, specified as one of the following values.

• 'nanoseconds'

• 'microseconds'

• 'milliseconds'

• 'seconds'

• 'minutes'

• 'hours'

• 'days'

• 'weeks'

• 'months'

• 'years'

Object Functions

addPoint	Add signal to list of analysis points for slLinearizer or slTuner interface
addOpening	Add signal to list of openings for slLinearizer or slTuner interface
addPoint	Add signal to list of analysis points for slLinearizer or slTuner interface
getPoints	Get list of analysis points for slLinearizer or slTuner interface
getOpenings	Get list of openings for slLinearizer or slTuner interface
getIOTransfer	Transfer function for specified I/O set using slLinearizer or slTuner interface
getLoopTransfer	Open-loop transfer function at specified point using slLinearizer or slTuner interface
getSensitivity	Sensitivity function at specified point using slLinearizer or slTuner interface
getCompSensitivity	Complementary sensitivity function at specified point using slLinearizer or slTuner interface
removePoint	Remove point from list of analysis points in slLinearizer or slTuner interface
removeAllPoints	Remove all points from list of analysis points in slLinearizer or slTuner interface
removeAllOpenings	Remove all openings from list of permanent openings in slLinearizer or slTuner interface
refresh	Resynchronize slLinearizer or slTuner interface with current model state

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-loop 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 that you want to vary the proportional and integral gains of C2, Kp2 and Ki2, in the 10% range. Create a structure and specify the parameter variations.

Kp2_range = linspace(0.9*Kp2,1.1*Kp2,3);
Ki2_range = linspace(0.9*Ki2,1.1*Ki2,5);

[Kp2_grid,Ki2_grid] = ndgrid(Kp2_range,Ki2_range);

params(1).Name = "Kp2";
params(1).Value = Kp2_grid;

params(2).Name = "Ki2";
params(2).Value = Ki2_grid;

params specifies a 3-by-5 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;

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 that 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 also 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. For example, extract the transfer function between the reference signal r and the output y1m for each parameter variation and plot their step responses.

T = getIOTransfer(sllin,"r","y1m");
stepplot(T)

Limitations

• Linearization is not supported for model hierarchies that contain referenced models configured to use a local solver.

• Linearization is not supported for Simscape™ networks configured to use a local solver.

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:

s = slLinearizer('scdcascade',{'u1','y1'});

Alternatively, you can use the addPoint command.

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.

For more information about how you can use analysis points, see Mark Signals of Interest for Control System Analysis and Design and Mark Signals of Interest for Batch Linearization.

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:

• Linear model in the form of a D-matrix

• Control System Toolbox LTI model object

• Uncertain state-space model or uncertain real object (requires Robust Control Toolbox software)

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.

function sys = myCustomFunction(BlockData)
    Td = BlockData.Parameters(1).Value;
    Ts = BlockData.Parameters(2).Value;
    sys = BlockData.BlockLinearization*Thiran(Td,Ts);
end 

Save this function to a location on the MATLAB path.

To use this function as a custom linearization for a block or subsystem, specify the blocksub.Value.Specification and blocksub.Value.Type fields.

blocksub.Value.Specification = 'myCustomFunction';
blocksub.Value.Type = 'Function';

To set the delay and sample time parameter values, specify the blocksub.Value.ParameterNames and blocksub.Value.ParameterValues fields.

blocksub.Value.ParameterNames = {'Td','Ts'};
blocksub.Value.ParameterValues = [0.5 0.1];

Alternatives

As an alternative to an slLinearizer interface, you can linearize models using one of the following methods. For examples, see Linearize Simulink Model at Model Operating Point.

• To interactively linearize models, use the Model Linearizer app.

• To obtain a linear model, you can use the linearize function.

Although both Simulink Control Design™ software and the Simulink linmod function perform block-by-block linearization, Simulink Control Design linearization functionality has a more flexible user interface and uses Control System Toolbox numerical algorithms. For more information, see Linearization Using Simulink Control Design Versus Simulink.

Version History

Introduced in R2013b

R2020b: Linearize Simulink model to a sparse state-space model

You can linearize and obtain a sparse model from a Simulink model that contains a Sparse Second Order or Descriptor State-Space block.

• mechss model when you use a Sparse Second Order in your Simulink model.

• sparss model when you use a Descriptor State-Space block and select the Linearize to sparse model block parameter.

For more information, see Sparse Model Basics. For an example, see Linearize Simulink Model to a Sparse Second-Order Model Object.

R2016b: Compute operating point offsets for model inputs, outputs, states, and state derivatives during linearization

You can compute operating point offsets for model inputs, outputs, states, and state derivatives when linearizing Simulink models. Thee offsets streamline the creation of linear parameter-varying (LPV) systems.

To obtain operating point offsets, first create a linearizeOptions object and set the StoreOffsets option to true. Then, create an slLinearizer interface for the model.

You can extract the offsets from the info output argument of linearization function like getIOTransfer and convert them into the required format for the LPV System block using the getOffsetsForLPV function.

R2016a: Time unit property

You can specify time units for an slLinearizer interface using the TimeUnit property. This property specifies the time units for linearized models returned by getIOTransfer, getLoopTransfer, getSensitivity, and getCompSensitivity.

R2014a: Block substitution property

You can specify a substitute linearization for a Simulink block or subsystem using the BlockSubstitutions property of an slLinearizer interface.