Linear approximation of Simulink model or subsystem
linsys = linearize(sys,blocksub,io)
linsys = linearize(sys,blocksub,io,op)
linsys = linearize(sys,blocksub,io,tsnapshot)
linsys = linearize(___,param)
linsys = linearize(___,'StateOrder',stateorder)
linsys = linearize(___,options)
[linsys,linop]
= linearize(___)
[linsys,linop,info]
= linearize(___)
specifies
the order of the states in the linearized model.linsys
= linearize(___,'StateOrder',stateorder
)
Open the Simulink model.
sys = 'watertank';
open_system(sys)
Specify a linearization input at the output of the PID Controller block, which is the input signal for the WaterTank System block.
io(1) = linio('watertank/PID Controller',1,'input');
Specify a linearization output point at the output of the WaterTank System block. Specifying the output point as openloop removes the effects of the feedback signal on the linearization without changing the model operating point.
io(2) = linio('watertank/WaterTank System',1,'openoutput');
Linearize the model using the specified I/O set.
linsys = linearize(sys,io);
linsys
is the linear approximation of the plant at the model operating point.
Open the Simulink model.
sys = 'magball';
open_system(sys)
Find a steadystate operating point at which the ball height is 0.05
. Create a default operating point specification, and set the height state to a known value.
opspec = operspec(sys); opspec.States(5).Known = 1; opspec.States(5).x = 0.05;
Trim the model to find the operating point.
options = findopOptions('DisplayReport','off'); op = findop(sys,opspec,options);
Specify linearization input and output signals to compute the closedloop transfer function.
io(1) = linio('magball/Desired Height',1,'input'); io(2) = linio('magball/Magnetic Ball Plant',1,'output');
Linearize the model at the specified operating point using the specified I/O set.
linsys = linearize(sys,io,op);
Open the Simulink model.
sys = 'watertank';
open_system(sys)
Specify the full block path for the block you want to linearize.
blockpath = 'watertank/WaterTank System';
Linearize the specified block at the model operating point.
linsys = linearize(sys,blockpath);
Open Simulink model.
sys = 'magball';
open_system(sys)
Find a steadystate operating point at which the ball height is 0.05
. Create a default operating point specification, and set the height state to a known value.
opspec = operspec(sys); opspec.States(5).Known = 1; opspec.States(5).x = 0.05;
options = findopOptions('DisplayReport','off'); op = findop(sys,opspec,options);
Specify the block path for the block you want to linearize.
blockpath = 'magball/Magnetic Ball Plant';
Linearize the specified block and the specified operating point.
linsys = linearize(sys,blockpath,op);
Open the Simulink model.
sys = 'scdpwm';
open_system(sys)
Extract linearization input and output from the model.
io = getlinio(sys);
Linearize the model at the model operating point.
linsys = linearize(sys,io)
linsys = D = Step Plant Model 0 Static gain.
The discontinuities in the Voltage to PWM block cause the model to linearize to zero. To treat this block as a unit gain during linearization, specify a substitute linearization for this block.
blocksub.Name = 'scdpwm/Voltage to PWM';
blocksub.Value = 1;
Linearize the model using the specified block substitution.
linsys = linearize(sys,blocksub,io)
linsys = A = State Space( State Space( State Space( 0.9999 0.0001 State Space( 0.0001 1 B = Step State Space( 0.0001 State Space( 5e09 C = State Space( State Space( Plant Model 0 1 D = Step Plant Model 0 Sample time: 0.0001 seconds Discretetime statespace model.
Open the Simulink model.
sys = 'watertank';
open_system(sys)
To compute the closedloop transfer function, first specify the linearization input and output signals.
io(1) = linio('watertank/PID Controller',1,'input'); io(2) = linio('watertank/WaterTank System',1,'output');
Simulate sys
for 10
seconds and linearize the model.
linsys = linearize(sys,io,10);
Open the Simulink model.
sys = 'scdcascade';
open_system(sys)
Specify parameter variations for the outerloop controller gains, Kp1
and Ki1
. Create parameter grids for each gain value.
Kp1_range = linspace(Kp1*0.8,Kp1*1.2,6); Ki1_range = linspace(Ki1*0.8,Ki1*1.2,4); [Kp1_grid,Ki1_grid] = ndgrid(Kp1_range,Ki1_range);
Create a parameter value structure with fields Name
and Value
.
params(1).Name = 'Kp1'; params(1).Value = Kp1_grid; params(2).Name = 'Ki1'; params(2).Value = Ki1_grid;
params
is a 6by4 parameter value grid, where each grid point corresponds to a unique combination of Kp1
and Ki1
values.
Define linearization input and output points for computing the closedloop response of the system.
io(1) = linio('scdcascade/setpoint',1,'input'); io(2) = linio('scdcascade/Sum',1,'output');
Linearize the model at the model operating point using the specified parameter values.
linsys = linearize(sys,io,params);
Open the Simulink model.
sys = 'magball';
open_system(sys)
Linearize the plant at the model operating point.
blockpath = 'magball/Magnetic Ball Plant';
linsys = linearize(sys,blockpath);
View the default state order for the linearized plant.
linsys.StateName
ans = 3×1 cell array 'height' 'Current' 'dhdt'
Linearize the plant and reorder the states in the linearized model. Set the rate of change of the height as the second state.
stateorder = {'magball/Magnetic Ball Plant/height';... 'magball/Magnetic Ball Plant/dhdt';... 'magball/Magnetic Ball Plant/Current'}; linsys = linearize(sys,blockpath,'StateOrder',stateorder);
View the new state order.
linsys.StateName
ans = 3×1 cell array 'height' 'dhdt' 'Current'
Open the Simulink model.
sys = 'watertank';
open_system(sys)
Specify the block path of the plant.
blockpath = 'watertank/WaterTank System';
Create a linearization option set, and specify the sample time for the linearized model.
options = linearizeOptions('SampleTime',0.1);
Linearize the plant using the specified options.
linsys = linearize(sys,blockpath,options)
linsys = A = H H 0.995 B = WaterTank S H 0.02494 C = H WaterTank S 1 D = WaterTank S WaterTank S 0 Sample time: 0.1 seconds Discretetime statespace model.
The linearized plant is a discretetime statespace model with a sample time of 0.1
.
Open the Simulink model.
sys = 'watertank';
open_system(sys)
To compute the closedloop transfer function, first specify the linearization input and output signals.
io(1) = linio('watertank/PID Controller',1,'input'); io(2) = linio('watertank/WaterTank System',1,'output');
Simulate sys
and linearize the model at 0
and 10
seconds. Return the operating points that correspond to these snapshot times; that is, the operating points at which the model was linearized.
[linsys,linop] = linearize(sys,io,[0,10]);
Open the Simulink model.
sys = 'watertank';
open_system(sys)
Vary parameters A
and b
within 10% of their nominal values.
[A_grid,b_grid] = ndgrid(linspace(0.9*A,1.1*A,3),...
linspace(0.9*b,1.1*b,4));
Create a parameter structure array, specifying the name and grid points for each parameter.
params(1).Name = 'A'; params(1).Value = A_grid; params(2).Name = 'b'; params(2).Value = b_grid;
Create a default operating point specification for the model.
opspec = operspec(sys);
Trim the model using the specified operating point specification, parameter grid. Suppress the display of the operating point search report.
opt = findopOptions('DisplayReport','off'); [op,opreport] = findop(sys,opspec,params,opt);
op
is a 3by4 array of operating point objects that correspond to the specified parameter grid points.
Specify the block path for the plant model.
blockpath = 'watertank/Desired Water Level';
To store offsets during linearization, create a linearization option set and set StoreOffsets
to true
.
options = linearizeOptions('StoreOffsets',true);
Batch linearize the plant at the trimmed operating points, using the specified I/O points and parameter variations.
[linsys,linop,info] = linearize(sys,blockpath,op,params,options);
You can use the offsets in info.Offsets
when configuring an LPV System block.
info.Offsets
ans = 3×4 struct array with fields: x dx u y StateName InputName OutputName Ts
sys
— Simulink model nameSimulink model name, specified as a character vector.
io
— Linearization I/O setLinearization I/O set that contains inputs, outputs, and openings,
specified as a linearization I/O object or a vector of linearization
I/O objects. To create io
:
Define the inputs, outputs, and openings using linio
.
If the inputs, outputs, and openings are specified
in the Simulink model, extract these points from the model using getlinio
.
Each linearization I/O object in io
must
correspond to the Simulink model sys
or
some normal mode model reference in the model hierarchy.
If you omit io
, then linearize
uses
the root level inports and outports of the model as linearization
I/Os.
For more information on specifying linearization inputs, outputs, and openings, see Specifying Portion of Model to Linearize.
op
— Operating pointOperating point for linearization, specified as one of the following:
Operating point object, created using findop
with either a single operating
point specification, or a single snapshot time.
Array of operating point objects, specifying multiple operating points. To create an array of operating point 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 SteadyState Operating Points for Multiple Specifications.
Batch trim your model using parameter variations. For more information, see Batch Compute SteadyState Operating Points for Parameter Variation.
If you specify parameter variations using param
,
and the parameters:
Affect the model operating point, then specify op
as
an array of operating points with the same dimensions as the parameter
value grid. To obtain the operating points that correspond to the
parameter value combinations, batch trim your model using param
before
linearization. For more information, see Batch Linearize Model at Multiple Operating Points Derived from Parameter Variations.
Do not affect the model operating point, then specify op
as
a single operating point.
blockpath
— Block or subsystemBlock or subsystem to linearize, specified as a character vector that contains its full block path.
The software treats the inports and outports of the specified block as openloop inputs and outputs, which isolates it from the rest of the model before linearization.
blocksub
— Substitute linearizations for blocks and subsystemsSubstitute linearizations for blocks and subsystems, specified
as a structure or an nby1 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.
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.
Each substitute linearization structure has the following fields:
Name
— Block pathBlock path of the block for which you want to specify the linearization, specified as a character vector.
Value
— Substitute linearizationSubstitute 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}byn_{y} array of gain values, where n_{u} is the number of inputs and n_{y} is the number of outputs.
LTI model, uncertain statespace 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 statespace 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.
Specify op
as an array of operating
points and Value
as a model array, the dimensions
of Value
must match the size of op
.
Define block substitutions for multiple blocks, and
specify Value
as an array of LTI models for one
or more of these blocks, 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 specified expression or function must return one of the following:
The I/O configuration of the returned model must
match the configuration of the block specified by 
Type  Specification type, specified as one of the following:

ParameterNames  Linearization function parameter names, specified as
a cell array of character vectors. Specify You must also specify
the corresponding 
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 
param
— Parameter samplesParameter samples for linearization, specified as 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. 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:
[A_grid,b_grid] = ndgrid(linspace(0.9*A,1.1*A,3),... linspace(0.9*b,1.1*b,3)); params(1).Name = 'A'; params(1).Value = A_grid; params(2).Name = 'b'; params(2).Value = b_grid;
For more information, see Specify Parameter Samples for Batch Linearization.
If param
specifies tunable parameters only,
the software batch linearizes the model using a single model compilation.
To compute the offsets required by the LPV
System block, specify param
, and set options.StoreOffsets
to true
.
You can then return additional linearization information in info
,
and extract the offsets using getOffsetsForLPV
.
tsnapshot
— Simulation snapshot timesSimulation snapshot times at which to linearize the model, specified
as a scalar for a single snapshot, or a vector for multiple snapshots.
The software simulates sys
and linearizes the
model at the specified snapshot times.
If you also specify parameter variations using param
,
the software simulates the model for each snapshot time and parameter
grid point combination. This operation can be computationally expensive.
stateorder
— State order in linearization resultsState order in linearization results, specified as a cell array
of block paths or state names. The order of the block paths and states
in stateorder
indicates the order of the states
in linsys
.
You can specify block paths for any blocks in sys
that
have states, or any named states in sys
.
You do not have to specify every block and state from sys
in stateorder
.
The states you specify appear first in linsys
,
followed by the remaining states in their default order.
options
— Linearization algorithm optionslinearizeOptions
option setLinearization algorithm options, specified as a linearizeOptions
option set.
linsys
— Linearization resultLinearization result, returned as a statespace model or an
array of statespace models. The dimensions of linsys
depend
on the specified parameter variations and block substitutions, and
the operating points or snapshots at which you linearize the model.
Note:
If you specify more than one of 
Parameter Variation  Block Substitution  Linearize at...  Resulting linsys Dimensions 

No parameter variation  No block substitution  Model operating point  Single statespace model 
Single operating point, specified by op  
Single snapshot, specified by tsnapshot  
N_{1}by... byN_{m} array
of operating points, specified by op  N_{1}by... byN_{m}  
N_{s} snapshots, specified
by tsnapshot  Column vector of length N_{s}  
N_{1}by... byN_{m} model
array for at least one block, specified by blocksub.Value  Model operating point  N_{1}by... byN_{m}  
Single operating point, specified by op  
Single snapshot, specified by tsnapshot  
N_{1}by... byN_{m} array
of operating points, specified by op  
N_{s} snapshots, specified
by tsnapshot  N_{s}byN_{1}by... byN_{m}  
N_{1}by... byN_{m} parameter
grid, specified by param  Either no block substitution or an N_{1}by... byN_{m} model
array for at least one block, specified by blocksub.Value  Model operating point  N_{1}by... byN_{m} 
Single operating point, specified by op  
Single snapshot, specified by tsnapshot  
N_{1}by... byN_{m} array
of operating points, specified by op  
N_{s} snapshots, specified
by tsnapshot  N_{s}byN_{1}by... byN_{m} 
For example, suppose:
op
is a 4by3 array of operating
point objects and you do not specify parameter variations or block
substitutions. In this case, linsys
is a 4by3
model array.
op
is a single operating point
object and param
specifies a 3by4by2 parameter
grid. In this case, linsys
is a 3by4by2 model
array.
tsnapshot
is a row vector with
two elements and you do not specify param
. In
this case, linsys
is a column vector with two
elements.
tsnapshot
is a column vector
with three elements and param
specifies a 5by6
parameter grid. In this case, linsys
is a 3by5by6
model array.
op
is a single operating point
object, you do not specify parameter variations, and blocksub.Value
is
a 2by3 model array for one block in the model. In this case, linsys
is
a 2by3 model array.
tsnapshot
is a column vector
with four elements, you do not specify parameter variations, and blocksub.Value
is
a 1by2 model array for one block in the model. In this case, linsys
is
a 4by1by2 model array.
For more information on model arrays, see Model Arrays.
linop
— Operating pointOperating point at which the model was linearized, returned
as an operating point object or an array of operating point objects
with the same dimensions as linsys
. Each element
of linop
is the operating point at which the
corresponding linsys
model was obtained.
If you specify an operating point or operating point array using op
,
then linop
is a copy of op
.
If you specify op
as a single operating point
and also specify parameter variations using param
,
then linop
is an array with the same dimensions
as the parameter grid. In this case, the elements of linop
are
scalar expanded copies of op
.
To determine whether the model was linearized at a reasonable
operating point, view the states and inputs in linop
.
info
— Linearization informationLinearization information, returned as a structure with the following field:
Offsets
— Linearization offsets[]
(default)  structure  structure arrayLinearization offsets that correspond to the operating point
at which the model was linearized, returned as []
if options.StoreOffsets
is false
.
Otherwise, Offsets
is returned as one of the following:
If linsys
is a single statespace
model, then Offsets
is a structure.
If linsys
is an array of statespace
models, then Offsets
is a structure array with
the same dimensions as linsys
.
Each offset structure has the following fields:
Field  Description 

x  State offsets used for linearization, returned as a column
vector of length n_{x}, where n_{x} is
the number of states in linsys . 
y  Output offsets used for linearization, returned as a column
vector of length n_{y}, where n_{y} is
the number of outputs in linsys . 
u  Input offsets used for linearization, returned as a column
vector of length n_{u}, where n_{u} is
the number of inputs in linsys . 
dx  Derivative offsets for continuous time systems, or updated state values for discretetime systems, returned as a column vector of length n_{x}. 
StateName  State names, returned as a cell array that contains n_{x} elements
that match the names in linsys.StateName . 
InputName  Input names, returned as a cell array that contains n_{u} elements
that match the names in linsys.InputName . 
OutputName  Output names, returned as a cell array that contains n_{y} elements
that match the names in linsys.OutputName . 
Ts  Sample time of the linearized system, returned as a scalar
that matches the sample time in sys.Ts . For continuoustime
systems, Ts is 0 . 
If Offsets
is a structure array, you can
configure an LPV System block using
the offsets. To do so, first convert them to the required format using getOffsetsForLPV
. For an example, see Approximating Nonlinear Behavior using an Array of LTI Systems.
As an alternative to the linearize
function,
you can linearize models using one of the following methods:
To interactively linearize models, use the Linear Analysis Tool. For an example, see Linearize Simulink Model at Model Operating Point.
To obtain multiple transfer functions without modifying
the model or creating a linearization I/O set for each transfer function,
use an slLinearizer
interface.
For an example, see Vary Parameter Values and Obtain Multiple Transfer Functions.
Although both Simulink Control Design™ software and the Simulink linmod
function
perform blockbyblock 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.
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 input argument, BlockData
,
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:
 
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
statespace 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 Dmatrix
Control System Toolbox LTI model object
Uncertain statespace 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 = currentSys*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.Specification = '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];
By default, linearize
automatically sets
the following Simulink model properties:
BufferReuse = 'off'
RTWInlineParameters = 'on'
BlockReductionOpt = 'off'
SaveFormat = 'StructureWithTime'
After linearization, Simulink restores the original model properties.
Simulink Control Design software linearizes models using a blockbyblock approach. The software individually linearizes each block in your Simulink model and produces the linearization of the overall system by combining the individual block linearizations.
The software determines the input and state levels for each block from the operating point, and requests the Jacobian for these levels from each block.
For some blocks, the software cannot compute an analytical linearization. For example:
Some nonlinearities do not have a defined Jacobian.
Some discrete blocks, such as state charts and triggered subsystems, tend to linearize to zero.
Some blocks do not implement a Jacobian.
Custom blocks, such as SFunction blocks and MATLAB Function blocks, do not have analytical Jacobians.
You can specify a custom linearization for any such blocks for which you know the expected linearization. If you do not specify a custom linearization, the software linearizes the model by perturbing the block inputs and states and measuring the response to these perturbations. For each input and state, the default perturbation level is $${10}^{5}\left(1+\leftx\right\right)$$, where x is the value of the corresponding input or state at the operating point. For information on how to change perturbation levels for individual blocks, see Change Perturbation Level of Blocks Perturbed During Linearization.
For more information, see Linearizing Nonlinear Models and Exact Linearization Algorithm
You can also linearize your system using fullmodel numerical
perturbation. To do so, create a linearizeOptions
set
and set the LinearizationAlgorithm
to 'numericalpert'
.
The software computes the linearization of the full model by perturbing
the values of the rootlevel inports and states of the model. This
algorithm ignores linear analysis points set in the model and uses
rootlevel inports and outports instead.
For each inport and state, the software perturbs the model and
measures the model response to these perturbations. You can configure
the state and input perturbation levels using the NumericalPertRel
linearization
options.
Blockbyblock linearization has several advantages over fullmodel numerical perturbation:
Many Simulink blocks have a preprogrammed linearization that provides an exact linearization of the block.
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
When linearizing multirate models, you can use different rate conversion methods. Fullmodel numerical perturbation can only use zeroorderhold rate conversion.
For more information, see Linearizing Nonlinear Models and Exact Linearization Algorithm.
findop
 Linear Analysis Tool  linearizeOptions
 slLinearizer
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
You can also select a location from the following list: