simulink-linearize

# 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`. ```matlab 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 ```matlab 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): ```matlab 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: ```matlab % 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 ```matlab sys = linearize(mdl, OPTIONAL_ARGS); ``` Each input argument to linearize is optional (beside `mdl`). ```matlab 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: ```matlab opts = linearizeOptions(SampleTime=0); sys = linearize(mdl, io, opts); ``` **Batch linearization for LPV:** ```matlab 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`:** ```matlab 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. ```matlab 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: ```matlab 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 ```matlab tfSys = tf(sys); % Transfer function zpkSys = zpk(sys); % Zero-pole-gain ``` ### LPV Validation For LPV models, simulate and compare against Simulink: ```matlab [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. ----