simulink-linearize

name	simulink-linearize
description	Linearize Simulink models. Use when obtaining linear time invariant or linear parameter varying models from Simulink models.
license	https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md
metadata	{"author":"MathWorks","version":"1.0"}

Simulink Linearization

Extract linear time invariant (LTI) or linear parameter varying (LPV) models from Simulink using linearize and related APIs from Simulink Control Design.

When to Use

• Obtaining a linear model (tf, ss, zpk) from a Simulink model
• Batch linearization across operating points and parameter variations
• Building LPV models with ssInterpolant
• Debugging linearization results (zero gain, unexpected dynamics)
• Extracting multiple LTI systems with a single model compile

When NOT to Use

• Frequency response estimation from simulation — use simulink-frequency-response for frestimate-based fallback
• No Simulink model is involved

Workflow

The linearization pipeline has four stages. Not every task requires all stages.

1. Define I/O Points 2. Operating Point  →  3. Linearize  →  4. Debug  
    (root level/linio)   (findop/operspec)     (linearize)     (advisor) 

Stage 1: Define Linearization I/O Points

Determine I/O points using this decision sequence. Use the first case that applies:

Case A — IO points can be inferred from prompt or model context:

Use the first sub-case that matches:

1. User specifies explicit I/O signals or blocks (e.g., "from r to y") → define linio points. All linio points must reference a block's output port. If a candidate block has no output ports (Outport, Terminator, Scope) → trace upstream to find the source block and port with model_read.

   io = [linio(sprintf("%s/InputBlock", mdl), 1, "input"); ...
         linio(sprintf("%s/OutputBlock", mdl), 1, "output")];
   

2. User targets a specific block or subsystem (e.g., "linearize the Controller") → Use the block path as the io argument signaling linearize to perform open-loop linearization of the block

   io = sprintf("%s/Controller", mdl);
   

3. Model has existing linearization points → io = getlinio(mdl); — use if non-empty.

4. Root-level Inport/Outport blocks exist → omit linio. The linearize command will linearize about the model's root-level I/Os. Use model_read at root scope (depth "0") to confirm root-level Inport/Outport blocks exist.

Case B — Cannot determine IO points:

If none of the above apply → do not guess. Ask the user which signals to use as linearization inputs and outputs. Present the available blocks/signals from the model to help them decide.

Block path rules:

• Use sprintf for block names containing special characters (newlines, commas):

  blkPath = sprintf("%s/Integrator,\nSecond-Order", mdl);
  io = linio(blkPath, 1, "output");
  
  sub.Name = sprintf("%s/My\nBlock",mdl);
  sub.Value = replacement_lti;
  
  sys = linearize(mdl, io, sub);  
  

Stage 2: Operating Point

Determine where to linearize. Choose one:

Situation	Approach
Model ICs	Skip — linearize uses model initial conditions
Steady-state trim	operspec → configure → findop(mdl, opSpec, findopOptions(DisplayReport="off"))
Need snapshot from simulation	linearize(mdl, tSnapshot)
Batch over parameter grid	Array of operspec objects → findop(mdl, specArray, params)
Operating points known	Array of operpoint objects → configure

For batch workflows, use copy to create the operating point array:

% assign varied variable to workspace
myvar = 0;
% create base spec
opBase = operspec(mdl);
opBase.States(1).Known = true;
% define param to vary
nPts = 5;
params.Name = "myvar";
params.Value = linspace(-pi, pi, nPts);
for i = nPts:-1:1
    opArray(i) = copy(opBase);
    opArray(i).States(1).x = params.Value(i);
end
ops = findop(mdl, opArray, params, findopOptions());

Stage 3: Linearize

sys = linearize(mdl, OPTIONAL_ARGS);

Each input argument to linearize is optional (beside mdl).

sys = linearize(mdl, io, op, params, blocksub, opts);

Argument	Required	Behavior if Provided	Behavior if Omitted
mdl	Y	Model to linearize	NA
io	N	linearize at I/O points	Linearize at root level I/Os
op	N	Operating points OR times to linearize	Linearize at model IC
params	N	Vary parameters for each linearization	No variation
blocksub	N	User specified block linearizations	Blocks have Simulink linearization
opts	N	User specified linearizeOptions	Default options

Multi-rate models default to the LCM sample time. Use the SampleTime option to specify linear model sample time:

opts = linearizeOptions(SampleTime=0);
sys = linearize(mdl, io, opts);

Batch linearization for LPV:

opts = linearizeOptions(BatchConsistency="on", StoreOffsets="system");
sysArray = linearize(mdl, io, ops, params, opts);
lpvSys = ssInterpolant(sysArray);

When StoreOffsets="system", offsets are embedded in each model of the array. Call ssInterpolant(sysArray) with no offset argument.

Define SamplingGrid if one is not generated from linearize (params argument is omitted).

Multiple transfer functions (single compile) with slLinearizer:

sllin = slLinearizer(mdl);
addPoint(sllin, ["r", "y", "e", "u"]);
T = getIOTransfer(sllin, "r", "y");
S = getSensitivity(sllin, "e");
L = getLoopTransfer(sllin, "u", sign);

Stage 4: Debug (Linearization Advisor)

Use when linearization returns zero gain or unexpected results.

opts = linearizeOptions(StoreAdvisor=true);
[sys, ~, info] = linearize(mdl, io, opts);
advisorResult = advise(info.Advisor);

Always capture the output of advise — calling without an output argument launches the UI.

Inspect problematic blocks:

problematic = find(advisorResult, linqueryHasDiagnostics());
for i = 1:numel(problematic.BlockDiagnostics)
    diag = problematic.BlockDiagnostics(i);
    fprintf('%s: %s\n', diag.BlockPath, join(string(diag.DiagnosticMessages), newline));
end

Common advisor findings and resolutions:

• "linearization has zero input/output pair" → Change operating point, or use block substitution if reasonable to do so
• Block with hard discontinuity (PWM, relay, dead zone, non-floating point signals) → Analytical linearization will be zero. Fall back to frequency response estimation
• Reference diagnostic message for other potential fixes

Convert if needed

tfSys = tf(sys);      % Transfer function
zpkSys = zpk(sys);    % Zero-pole-gain

LPV Validation

For LPV models, simulate and compare against Simulink:

[y, t] = lsim(lpvSys, u, tVec, x0, paramTrajectory);

Key Functions

Function	Purpose	Available From
linearize	Linearize Simulink model	R2006a
linearizeOptions	Configure linearization algorithm	R2006a
linio	Define linearization I/O points	R2006a
getlinio	Get I/O points defined in model	R2006a
operpoint	Create operating point with manual state values	R2006a
operspec	Create operating point specification	R2006a
findop	Trim or snapshot operating point	R2006a
slLinearizer	Batch/multi-transfer-function interface	R2013b
getIOTransfer	Closed-loop transfer function from slLinearizer	R2013b
getSensitivity	Sensitivity function from slLinearizer	R2013b
getCompSensitivity	Complementary sensitivity from slLinearizer	R2013b
getLoopTransfer	Open-loop transfer from slLinearizer	R2013b
advise	Run linearization advisor	R2017b
ssInterpolant	Build gridded LPV/LTV model	R2023a

Common Mistakes

Mistake	Why It's Wrong	Correct Approach
Using linmod, linmod2, linmodv5 or dlinmod	Legacy API, limited features	Use linearize or slLinearizer
Not using advise when result is zero	Leads to trial-and-error	Enable StoreAdvisor="on", call result = advise(info.Advisor)
Using Outport/Terminator/Scope as linio point	Blocks without output ports cannot be specified as linearization I/O — errors	Trace upstream to find the source block that feeds it
opSpec(i) = opSpecBase in a loop	operspec is a handle class — this aliases, not copies	Use opArray(i) = copy(opBase)
Omitting BatchConsistency in batch	State ordering may vary across operating points	Always set BatchConsistency="on"
Calling ssInterpolant without offsets	LPV model requires offsets	Use StoreOffsets="system"
Calling advise without output arg	Launches Model Linearizer UI (hangs in non-interactive sessions)	Always use result = advise(advisor)
Repeated linearize calls for different I/Os	Recompiles model each time	Use slLinearizer for single compile
Manual trial-and-error for zero results	Wastes time, may not find root cause	Use advisor diagnostics — identify the problematic blocks

Conventions

• Always: Capture the output of advise() to prevent UI launch
• Always: Use copy(opSpec) for batch operating point arrays, not assignment
• Always: Set BatchConsistency="on" for batch linearization destined for LPV
• Always: Set StoreOffsets="system" when building LPV models with ssInterpolant
• Prefer: slLinearizer when extracting multiple transfer functions from one model
• Never: Place linio on blocks without output ports (Outport, Terminator, Scope) — trace upstream to find the source block
• Never: Use linmod, linmod2, linmodv5 or dlinmod — these are legacy

---

Copyright 2026 The MathWorks, Inc.

---