it.grypho.scala.leonardo.control
Members list
Type members
Classlikes
The information criterion an ARX order search ranks by (F_0301), always named (the c2d method rule): with N scored equations, d coefficients and V the determinant of the residual covariance (1/N)·Σ e·eᵀ (the mean squared residual for one output), AIC = N·ln V + 2d, BIC = N·ln V + d·ln N and FPE = V·(1 + d/N)/(1 − d/N) (Ljung, System Identification, §16.4). Lower is better.
The information criterion an ARX order search ranks by (F_0301), always named (the c2d method rule): with N scored equations, d coefficients and V the determinant of the residual covariance (1/N)·Σ e·eᵀ (the mean squared residual for one output), AIC = N·ln V + 2d, BIC = N·ln V + d·ln N and FPE = V·(1 + d/N)/(1 − d/N) (Ljung, System Identification, §16.4). Lower is better.
Attributes
- Supertypes
-
trait Enumtrait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
Why an ARX call declined (F_0052 Decision A: the reason travels as data, and the REPL turns it into a note).
Why an ARX call declined (F_0052 Decision A: the reason travels as data, and the REPL turns it into a note).
Attributes
- Supertypes
-
trait Enumtrait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
An identified MIMO ARX model (F_0093), in the predictor form y[k] = Σᵢ Aᵢ·y[k−i] + Σₗ Bₗ·u[k−nk−l+1], the Aᵢ coupling the outputs.
An identified MIMO ARX model (F_0093), in the predictor form y[k] = Σᵢ Aᵢ·y[k−i] + Σₗ Bₗ·u[k−nk−l+1], the Aᵢ coupling the outputs.
A record of its own rather than a widened ArxModel, which is published API. At the prompt the blocks are stacked (F_0093 Decision A): a is (na·p)×p = [A₁; A₂; …] and b is (nb·p)×m = [B₁; B₂; …], which at p = 1 are exactly ArxModel's na×1 and nb×m. The sign of the Aᵢ is ArxModel's predictor sign.
Value parameters
- a
-
the
naautoregressive blocksA₁ … A_na, eachp×p; empty for a finite impulse response - b
-
the
nbinput blocksB₁ … B_nb, eachp×m, applied from lagnkon
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
An identified ARX model in the predictor form (F_0060 Decision A): y[k] = Σᵢ aᵢ·y[k−i] + Σⱼ Σₗ bₗⱼ·uⱼ[k−nk−l+1].
An identified ARX model in the predictor form (F_0060 Decision A): y[k] = Σᵢ aᵢ·y[k−i] + Σⱼ Σₗ bₗⱼ·uⱼ[k−nk−l+1].
The sign of a is stated because it cannot be inferred: MATLAB's arx/idpoly write A(q) = 1 + a₁q⁻¹ + …, so their a is the negative of this one (a_MATLAB = −a). The predictor sign is the one every recurrence and regression in this library already uses.
Value parameters
- a
-
the
naautoregressive coefficients,a₁first; empty for a finite impulse response - b
-
per input
j, itsnbcoefficientsb₁ⱼ … b_nb,j, applied from lagnkon
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
One candidate's score (F_0301).
One candidate's score (F_0301).
Value parameters
- na
-
the autoregressive order
- nb
-
the coefficients per input
- nk
-
the input delay
- score
-
the criterion;
-∞for a residual that vanishes exactly
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
The outcome of an ARX order search (F_0301).
The outcome of an ARX order search (F_0301).
Value parameters
- model
-
the model fitted at the chosen orders
- na
-
the chosen autoregressive order
- nb
-
the chosen coefficients per input
- nk
-
the chosen delay
- scores
-
every scored candidate, in grid order
- skipped
-
every candidate that was not scored, with the reason its fit declined
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
The error of an ARX model on a window of data (F_0330, AIACE L_0014).
The error of an ARX model on a window of data (F_0330, AIACE L_0014).
Value parameters
- from
-
the first scored sample,
max(na, nk + nb − 1)— the model's reach into the past, so the samples before it are read and never scored - residuals
-
p×(N − from): rowrholds outputr's residualy − ŷatk = from … N − 1 - rms
-
the root mean square of each output's residual over the scored samples
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
Continuous-to-discrete conversion.
Continuous-to-discrete conversion.
The method is always a visible argument, never a hidden default. The same plant discretised by zero-order hold and by Tustin has different discrete poles, so a silent choice would make two correct-looking answers disagree with no way to see why.
Attributes
Attributes
- Companion
- enum
- Supertypes
-
trait Sumtrait Mirrorclass Objecttrait Matchableclass Any
- Self type
-
DiscretisationMethod.type
A plant augmented with disturbance states (F_0300): x̂ = [x; d], x̂(k+1) = [[A, Bd], [0, I]]·x̂ + [[B], [0]]·u, y = [C, Cd]·x̂.
A plant augmented with disturbance states (F_0300): x̂ = [x; d], x̂(k+1) = [[A, Bd], [0, I]]·x̂ + [[B], [0]]·u, y = [C, Cd]·x̂.
Value parameters
- a
-
the augmented state matrix,
(n+nd)×(n+nd) - b
-
the augmented input matrix,
(n+nd)×m - c
-
the augmented output matrix,
p×(n+nd) - n
-
the plant's states
- nd
-
the disturbance states
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
A linearisation x' ≈ A·δx + B·δu + F₀, y ≈ C·δx + D·δu + G₀ about an operating point.
A linearisation x' ≈ A·δx + B·δu + F₀, y ≈ C·δx + D·δu + G₀ about an operating point.
Each field is an expression: a dense matrix at a numeric point, a symbolic _Matrix at a point with free parameters, exact cells when the input is exact.
Value parameters
- a
-
∂F/∂x,n×n - b
-
∂F/∂u,n×m - c
-
∂G/∂x,p×n - d
-
∂G/∂u,p×m - f0
-
F(x₀, u₀),n×1— zero at an equilibrium - g0
-
G(x₀, u₀),p×1
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
Why linearize declined (F_0052 Decision A: the reason travels as data, and the REPL turns it into a note).
Why linearize declined (F_0052 Decision A: the reason travels as data, and the REPL turns it into a note).
Attributes
- Supertypes
-
trait Enumtrait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
A minimal realisation (F_0307): (A, B, C, D) and its order, the McMillan degree.
A minimal realisation (F_0307): (A, B, C, D) and its order, the McMillan degree.
Value parameters
- a
-
the state matrix,
order×order - b
-
the input matrix
- c
-
the output matrix
- d
-
the feedthrough, unchanged
- order
-
the number of states
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
The prediction matrices of a model whose input is already an increment Δu of an accumulated input (F_0328, AIACE L_0012) — arx2nmssIncremental's, or any model with u(k−1) in its state: Y = Φ·x(k) + Γ·ΔU. The moves are increments, as in MpcIncrementalPrediction, so mpcQp reads MpcBounds.u as bounds on the position u(k−1) + Δu(k) + … + Δu(k+j) and MpcBounds.du as bounds on the moves; but the past input is in the state, so there is no Ψ·u(k−1) term.
The prediction matrices of a model whose input is already an increment Δu of an accumulated input (F_0328, AIACE L_0012) — arx2nmssIncremental's, or any model with u(k−1) in its state: Y = Φ·x(k) + Γ·ΔU. The moves are increments, as in MpcIncrementalPrediction, so mpcQp reads MpcBounds.u as bounds on the position u(k−1) + Δu(k) + … + Δu(k+j) and MpcBounds.du as bounds on the moves; but the past input is in the state, so there is no Ψ·u(k−1) term.
Not an MpcPrediction of the same model: that one holds its last move over the rest of the horizon, which for an increment is a ramp of the input. Here the increments are zero past Nc, so the input is held — the two agree only when Nc = Np. Build it with mpcAccumulatedPrediction.
Value parameters
- gamma
-
Γ,(Np·p)×(Nc·m), its block(i, l)the Markov parameterC·Aⁱ⁻ˡ·Bon and below the diagonal and zero above - phi
-
Φ, as in MpcPrediction
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait MpcPredictionMatricesclass Objecttrait Matchableclass AnyShow all
The bounds of an MPC problem (F_0299): each pair is (lower, upper), one entry per input or output, ±∞ for none; None for no bound of that kind at all.
The bounds of an MPC problem (F_0299): each pair is (lower, upper), one entry per input or output, ±∞ for none; None for no bound of that kind at all.
Value parameters
- du
-
the increments
u(k+j) − u(k+j−1), the first againstu(k−1) - soft
-
relaxes the output bounds through slacks;
Nonekeeps them hard - u
-
the inputs
u(k+j) - y
-
the predicted outputs
y(k+1) … y(k+Np)
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
Why an MPC construction gave no answer (F_0298–F_0300): a reason at the Scala level, the F_0052 Decision A arrangement every numeric tier of the library follows.
Why an MPC construction gave no answer (F_0298–F_0300): a reason at the Scala level, the F_0052 Decision A arrangement every numeric tier of the library follows.
Attributes
- Supertypes
-
trait Enumtrait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
The incremental (delta-u) prediction matrices (F_0298): Y = Φ·x(k) + Ψ·u(k−1) + Θ·ΔU, with u(k+j) = u(k−1) + Δu(k) + … + Δu(k+j) and Δu zero past Nc — the form offset-free tracking needs, since a constant input costs nothing in ΔU.
The incremental (delta-u) prediction matrices (F_0298): Y = Φ·x(k) + Ψ·u(k−1) + Θ·ΔU, with u(k+j) = u(k−1) + Δu(k) + … + Δu(k+j) and Δu zero past Nc — the form offset-free tracking needs, since a constant input costs nothing in ΔU.
Value parameters
- phi
-
Φ, as in MpcPrediction - psi
-
Ψ,(Np·p)×m, its blockithe accumulated Markov sumΣ_{j ≤ i} C·Aʲ·B - theta
-
Θ,(Np·p)×(Nc·m), its block(i, l)the sumΣ_{j ≤ i−l} C·Aʲ·Bbelow the diagonal and zero above
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait MpcPredictionMatricesclass Objecttrait Matchableclass AnyShow all
A cost on the position of the inputs when the moves are increments (F_0329, AIACE L_0013): Σⱼ ‖u(k+j) − u_s,j‖²_Sⱼ over the Nc decided steps, with u(k+j) = u(k−1) + Δu(k) + … + Δu(k+j). In those forms R weighs the moves and nothing else weighs where the actuator sits, so a plant with more inputs than setpoints keeps whatever split it started from; this cost settles it (a pump as low as possible, a valve as open as possible). With L the cumulative-sum matrix it adds 2·LᵀS̄L to the Hessian and 2·LᵀS̄(1⊗u(k−1) − u_s) to the linear term. S need only be positive semidefinite — a zero row leaves that input free — as long as the whole Hessian stays positive definite, which R > 0 ensures.
A cost on the position of the inputs when the moves are increments (F_0329, AIACE L_0013): Σⱼ ‖u(k+j) − u_s,j‖²_Sⱼ over the Nc decided steps, with u(k+j) = u(k−1) + Δu(k) + … + Δu(k+j). In those forms R weighs the moves and nothing else weighs where the actuator sits, so a plant with more inputs than setpoints keeps whatever split it started from; this cost settles it (a pump as low as possible, a valve as open as possible). With L the cumulative-sum matrix it adds 2·LᵀS̄L to the Hessian and 2·LᵀS̄(1⊗u(k−1) − u_s) to the linear term. S need only be positive semidefinite — a zero row leaves that input free — as long as the whole Hessian stays positive definite, which R > 0 ensures.
Value parameters
- target
-
u_s:mentries held, orNc·mstacked - weight
-
S: onem×mfor every step, orNcof them
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
The absolute-input prediction matrices (F_0298): Y = Φ·x(k) + Γ·U with Y the stacked outputs y(k+1) … y(k+Np) and U the Nc moves u(k) … u(k+Nc−1), the last held over the rest of the horizon — the convention of mpcMatrices exactly.
The absolute-input prediction matrices (F_0298): Y = Φ·x(k) + Γ·U with Y the stacked outputs y(k+1) … y(k+Np) and U the Nc moves u(k) … u(k+Nc−1), the last held over the rest of the horizon — the convention of mpcMatrices exactly.
Value parameters
- gamma
-
Γ,(Np·p)×(Nc·m), its last column accumulating the held move - phi
-
Φ,(Np·p)×n, stackingC·Aⁱfori = 1 … Np
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait MpcPredictionMatricesclass Objecttrait Matchableclass AnyShow all
Any form of the numeric prediction matrices (F_0298), which mpcQp takes (F_0299): the absolute form decides the moves U, the incremental and the accumulated ones (F_0328) the increments ΔU.
Any form of the numeric prediction matrices (F_0298), which mpcQp takes (F_0299): the absolute form decides the moves U, the incremental and the accumulated ones (F_0328) the increments ΔU.
Attributes
- Supertypes
-
class Objecttrait Matchableclass Any
- Known subtypes
The condensed MPC quadratic programme min ½ zᵀHz + fᵀz under A z ≤ b and lb ≤ z ≤ ub, ready for optimize.qpSolve (F_0299), with z the Nc·m moves followed by the slacks.
The condensed MPC quadratic programme min ½ zᵀHz + fᵀz under A z ≤ b and lb ≤ z ≤ ub, ready for optimize.qpSolve (F_0299), with z the Nc·m moves followed by the slacks.
Value parameters
- f
-
the linear term
- h
-
the Hessian,
2(GᵀQ̄G + R̄)with the slacks'2ρ₂on the diagonal - incremental
-
whether
zholds increments - ineq
-
the inequality rows, or
None - lb
-
lower bounds of
z - m
-
inputs per move
- nc
-
the control horizon
- uPrev
-
u(k−1) - ub
-
upper bounds of
z
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
Soft output bounds (F_0299, the owner's decision): one non-negative slack per output, shared over the horizon, relaxing both of that output's bounds and costing ρ₁·s + ρ₂·s². ρ₂ > 0 keeps the Hessian positive definite; once ρ₁ exceeds the bound's multiplier the penalty is exact — no slack is used while the hard problem is feasible.
Soft output bounds (F_0299, the owner's decision): one non-negative slack per output, shared over the horizon, relaxing both of that output's bounds and costing ρ₁·s + ρ₂·s². ρ₂ > 0 keeps the Hessian positive definite; once ρ₁ exceeds the bound's multiplier the penalty is exact — no slack is used while the hard problem is feasible.
Value parameters
- linear
-
ρ₁, one per output,≥ 0 - quadratic
-
ρ₂, one per output,> 0
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
A solved MPC step (F_0299).
A solved MPC step (F_0299).
Value parameters
- input
-
u(k), the input to apply now - moves
-
the decided sequence,
Ncvectors ofm: the inputs for an absolute prediction, the increments for an incremental or an accumulated one - qp
-
the certified QP optimum, whose
activeset warm-starts the next step - slacks
-
the output slacks, empty when the outputs are not softened
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
The terminal cost of an MPC programme (F_0304, AIACE L_0007): ‖x(k+Np) − x_s‖²_P.
The terminal cost of an MPC programme (F_0304, AIACE L_0007): ‖x(k+Np) − x_s‖²_P.
The stage cost already weighs y(k+Np), so the weight that completes the infinite-horizon (LQR) cost-to-go is P − CᵀQC with P from dare / dlqr, not P itself; with it an unconstrained MPC reproduces the LQR law u = −K·x exactly. P alone also stabilises, more conservatively.
Value parameters
- prediction
-
the state prediction at the horizon's end, from mpcTerminalPrediction or mpcAccumulatedTerminalPrediction, in the same form (absolute, incremental or accumulated) as the output prediction
- target
-
x_s,nentries;Nonefor the origin - weight
-
P,n×n
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
The weights of an MPC programme (F_0304, F_0305; AIACE L_0007, L_0008).
The weights of an MPC programme (F_0304, F_0305; AIACE L_0007, L_0008).
Value parameters
- inputTarget
-
the absolute form's input target
u_s(F_0305):mentries held, orNc·mstacked, the move cost becoming‖u − u_s‖²_R;Noneforu_s = 0. Without it the absolute form'sRpulls the inputs towards zero, which offsets tracking whenever the steady input is not zero. Not accepted with an incremental or an accumulated prediction, whose moves are increments: seepositionTarget - positionTarget
-
the increment forms' cost on the input itself (F_0329), or
None. Not accepted with an absolute prediction, whereinputTargetwithris that cost - q
-
the output weights: one
p×pfor every step, orNpof them, step by step - r
-
the move weights: one
m×mfor every move, orNcof them - terminal
-
the terminal cost, or
None
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
Why a Riccati-family call declined (F_0052 Decision A: the reason travels as data, the REPL prints it).
Why a Riccati-family call declined (F_0052 Decision A: the reason travels as data, the REPL prints it).
Attributes
- Supertypes
-
trait Enumtrait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
Attributes
- Companion
- enum
- Supertypes
-
trait Sumtrait Mirrorclass Objecttrait Matchableclass Any
- Self type
-
RiccatiKind.type
Why dlsim declined (F_0052 Decision A: the reason travels as data, the REPL prints it).
Why dlsim declined (F_0052 Decision A: the reason travels as data, the REPL prints it).
Attributes
- Supertypes
-
trait Enumtrait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
The steady-state target (F_0300).
The steady-state target (F_0300).
Value parameters
- reached
-
whether the outputs reach the setpoint there;
falsewhen the input bounds or the shape leave only the closest reachable target - u
-
u_s - x
-
x_s
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalsclass Objecttrait Matchableclass AnyShow all
Which structural question a _Structure node asks (F_0134), with its prompt word.
Which structural question a _Structure node asks (F_0134), with its prompt word.
Attributes
- Supertypes
-
trait Enumtrait Serializabletrait Producttrait Equalstrait Keywordedclass Objecttrait Matchableclass AnyShow all
acker(A, B, poles) — acker at the prompt (F_0138): the poles a row (or column) of real and complex values; the answer the 1×n gain. acker, MATLAB's name for the single-input formula, rather than place: it says which method answers, and it is not a plausible variable name to reserve.
acker(A, B, poles) — acker at the prompt (F_0138): the poles a row (or column) of real and complex values; the answer the 1×n gain. acker, MATLAB's name for the single-input formula, rather than place: it says which method answers, and it is not a plausible variable name to reserve.
Value parameters
- a
-
the state matrix
- b
-
the input column
- poles
-
the requested closed-loop poles
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
arx(u, y, na, nb, nk) — arx as a node, the row [[a, b]] (F_0060; several outputs since F_0093, through arxMimo).
arx(u, y, na, nb, nk) — arx as a node, the row [[a, b]] (F_0060; several outputs since F_0093, through arxMimo).
a is the na×1 column of autoregressive coefficients in the predictor sign, or 0 when na = 0 — a matrix cannot have zero rows, and 0 for an absent group is the qp/kkt convention; b is nb×m, a column per input. Tuple assignment binds both: a, b := arx(u, y, 2, 1, 1). With p ≥ 2 outputs the blocks are stacked (Decision A): a is (na·p)×p = [A₁; A₂; …], or zeros(p, p) when na = 0 (Decision B), and b is (nb·p)×m = [B₁; B₂; …] — the single-output shapes at p = 1. A refusal leaves the call as written, and declineReason carries the reason the REPL prints.
Value parameters
- na
-
the autoregressive order
- nb
-
the coefficients per input
- nk
-
the input delay
- u
-
the inputs
- y
-
the output
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
arx2ss(a, b, nk) — arx2ss as a node, the state-space row [[A, B, C, D]]; for a model with several outputs (a stacked p×p blocks, F_0093) the block observer form.
arx2ss(a, b, nk) — arx2ss as a node, the state-space row [[A, B, C, D]]; for a model with several outputs (a stacked p×p blocks, F_0093) the block observer form.
Value parameters
- a
-
the autoregressive coefficients, or
0for none - b
-
the
nb×minput coefficients - nk
-
the input delay
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
arx2tf(a, b, nk, z) — arx2tf as a node: one rational in z for one input, a 1×m row of them for several; for a model with several outputs (a stacked p×p blocks, F_0093) the p×m transfer matrix. z is excluded from children and carried through rebuild, the _Series convention.
arx2tf(a, b, nk, z) — arx2tf as a node: one rational in z for one input, a 1×m row of them for several; for a model with several outputs (a stacked p×p blocks, F_0093) the p×m transfer matrix. z is excluded from children and carried through rebuild, the _Series convention.
Value parameters
- a
-
the autoregressive coefficients, or
0for none - b
-
the
nb×minput coefficients - nk
-
the input delay
- z
-
the discrete frequency variable
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
arxRegressors(u, y, na, nb, nk) — arxRegressors as a node, the row [[X, Y]].
arxRegressors(u, y, na, nb, nk) — arxRegressors as a node, the row [[X, Y]].
Value parameters
- na
-
the autoregressive order
- nb
-
the coefficients per input
- nk
-
the input delay
- u
-
the inputs
- y
-
the output
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
c2d(G, s, z, Ts, method) — c2d at the prompt (F_0092, F_0009). The method is a slot word — zoh, tustin, foh, impulse, matched, forward or backward — always written and not reserved (the rk45/pbfgs precedent), because the same plant discretised two ways has different discrete poles. tustin alone may be followed by a prewarp frequency, c2dPrewarped.
c2d(G, s, z, Ts, method) — c2d at the prompt (F_0092, F_0009). The method is a slot word — zoh, tustin, foh, impulse, matched, forward or backward — always written and not reserved (the rk45/pbfgs precedent), because the same plant discretised two ways has different discrete poles. tustin alone may be followed by a prewarp frequency, c2dPrewarped.
Value parameters
- g
-
the continuous transfer function
- method
-
the method
- prewarp
-
the frequency Tustin is prewarped at, when given
- s
-
the continuous frequency variable
- ts
-
the sample period, a positive number
- z
-
the discrete variable of the result
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
dlsim(sys, u, x0[, states]) — dlsim as a node (F_0064): the outputs Y, or with the slot word states (not reserved, the svd(A, full) precedent) the row [[Y, X]], X holding x[0] … x[N]. sys is the [[A, B, C, D]] row stateSpace, linearize, arx2ss build; u is m×N, or N×m when no side but the other matches; x0 is a column, or 0 for rest. A refusal leaves the call as written, and detailed carries the reason.
dlsim(sys, u, x0[, states]) — dlsim as a node (F_0064): the outputs Y, or with the slot word states (not reserved, the svd(A, full) precedent) the row [[Y, X]], X holding x[0] … x[N]. sys is the [[A, B, C, D]] row stateSpace, linearize, arx2ss build; u is m×N, or N×m when no side but the other matches; x0 is a column, or 0 for rest. A refusal leaves the call as written, and detailed carries the reason.
Value parameters
- states
-
whether to return the states as well
- sys
-
the model row
- u
-
the inputs
- x0
-
the initial state
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
Closed loop with negative feedback: feedback(G, H, v) = G/(1 + G*H).
Closed loop with negative feedback: feedback(G, H, v) = G/(1 + G*H).
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
Impulse response: impulse(G, s, t) = L^-1{G(s)}.
Impulse response: impulse(G, s, t) = L^-1{G(s)}.
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
isStable(G, s) or isStableDiscrete(G, z) — isStable / isStableDiscrete at the prompt (F_0092 Decision B: the Scala names, a predicate named as a question). Strict in both: a pole on the imaginary axis, or on the unit circle, is not stable.
isStable(G, s) or isStableDiscrete(G, z) — isStable / isStableDiscrete at the prompt (F_0092 Decision B: the Scala names, a predicate named as a question). Strict in both: a pole on the imaginary axis, or on the unit circle, is not stable.
Value parameters
- discrete
-
whether to test the unit circle rather than the left half-plane
- g
-
the transfer function
- v
-
the frequency variable
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
linearize(F, G, x, u, x0, u0[, affine]) — linearize as a node (F_0059).
linearize(F, G, x, u, x0, u0[, affine]) — linearize as a node (F_0059).
Evaluates to the state-space row [[A, B, C, D]], or with affine to [[A, B, C, D, F0, G0]]; tuple assignment binds the parts. The state and input names are binders: excluded from children and carried through rebuild, so substitute cannot rewrite the variables the derivatives are taken in. A refusal leaves the call as written, and detailed carries the reason the REPL prints.
Value parameters
- affine
-
whether to append the offsets
F0,G0 - f
-
the dynamics column
- g
-
the output column
- u
-
the input names, in order
- u0
-
the operating input
- x
-
the state names, in order
- x0
-
the operating state
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
mpcMatrices(A, B, C, Np, Nc) — the prediction matrices as the row [[Phi, Gamma]], the lu/stateSpace shape, so Phi, Gamma := mpcMatrices(…) binds both (Decision D).
mpcMatrices(A, B, C, Np, Nc) — the prediction matrices as the row [[Phi, Gamma]], the lu/stateSpace shape, so Phi, Gamma := mpcMatrices(…) binds both (Decision D).
Value parameters
- a
-
the state matrix
- b
-
the input matrix
- c
-
the output matrix
- nc
-
the control horizon
- np
-
the prediction horizon
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
Parallel connection: parallel(G, H, v).
Parallel connection: parallel(G, H, v).
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
dare(A, B, Q, R), dlqr(A, B, Q, R), dlyap(A, Q), kalmanGain(A, C, Qw, Rv) and kalmanStep(xhat, P, u, y, sys, Qw, Rv) as one node (F_0065), the _DistributionQuery pattern: the five differ only in the function they call.
dare(A, B, Q, R), dlqr(A, B, Q, R), dlyap(A, Q), kalmanGain(A, C, Qw, Rv) and kalmanStep(xhat, P, u, y, sys, Qw, Rv) as one node (F_0065), the _DistributionQuery pattern: the five differ only in the function they call.
dare and dlyap answer a matrix; dlqr the row [[K, P]], kalmanGain [[M, P]] and kalmanStep [[xhat', P']], so tuple assignment binds them. A number is a 1×1 matrix, and a bare 0 is the zero block of the shape the call implies (Qw, D, u), the dlsim reading; sys is the [[A, B, C, D]] row stateSpace, linearize and arx2ss build. An exact operand demotes. A refusal leaves the call as written, and detailed carries the reason.
Value parameters
- args
-
its arguments, in the order the grammar takes them
- kind
-
the function
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
routhTable(G, s) -- the Routh array of G's denominator, routhTable at the prompt (F_0139), under the Scala name: routh shipped as a free variable name in 3.8 and stays one.
routhTable(G, s) -- the Routh array of G's denominator, routhTable at the prompt (F_0139), under the Scala name: routh shipped as a free variable name in 3.8 and stays one.
A matrix whose rows are the array's, from the highest power down, each padded with zeros to the width of the first: the zeros are the entries a hand-built table leaves blank. The degenerate cases are shown, not repaired, as routhTable keeps them -- an exhausted row is the last row, since a zero row is itself the diagnostic. isStable still decides from the poles, for the reason its note gives; this node is for reading the table.
Value parameters
- g
-
the transfer function
- v
-
the frequency variable, excluded from
children
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
Series connection: series(G, H, v).
Series connection: series(G, H, v).
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
Unit-step response: step(G, s, t) = L^-1{G(s)/s}.
Unit-step response: step(G, s, t) = L^-1{G(s)/s}.
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
controllable, observable, ctrb and obsv at the prompt (F_0134), from (A, B) / (A, C) or from a [[A, B, C, D]] model row.
controllable, observable, ctrb and obsv at the prompt (F_0134), from (A, B) / (A, C) or from a [[A, B, C, D]] model row.
The verdicts are the library's own tests, run on operands evaluated in the session, so the prompt and Scala cannot disagree: full row rank by QR of the transpose, never det(M·Mᵀ) (2.11), and observability through the duality. Operands are read as dlsim reads them (matrixOperand): a number is a 1×1 matrix, and 0 the zero block of the conforming shape. ctrb/obsv are capped by the environment's Limit.MaxMatrixCells.
Value parameters
- a
-
the state matrix, or the model row when
xis absent - kind
-
the question
- x
-
the input matrix
Bor the output matrixC
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
tfpoles(G, s) — the poles of G, poles at the prompt (F_0092 Decision A).
tfpoles(G, s) — the poles of G, poles at the prompt (F_0092 Decision A).
Value parameters
- g
-
the transfer function
- v
-
the frequency variable, excluded from
children(the_Seriesconvention)
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
tfzeros(G, s) — the zeros of G, zeros at the prompt; tfzeros because zeros(r, c) is the zero-matrix constructor (F_0092 Decision A).
tfzeros(G, s) — the zeros of G, zeros at the prompt; tfzeros because zeros(r, c) is the zero-matrix constructor (F_0092 Decision A).
Value parameters
- g
-
the transfer function
- v
-
the frequency variable
Attributes
- Supertypes
-
trait Serializabletrait Producttrait Equalstrait _Expressionclass Objecttrait Matchableclass AnyShow all
Value members
Concrete methods
Single-input pole placement by Ackermann's formula (F_0138): the gain K that gives A − B·K the eigenvalues poles, in the u = −K·x convention dlqr uses.
Single-input pole placement by Ackermann's formula (F_0138): the gain K that gives A − B·K the eigenvalues poles, in the u = −K·x convention dlqr uses.
K = eₙᵀ · C⁻¹ · φ(A), with C the controllability matrix and φ the monic polynomial whose roots are the poles. Certified: Ackermann's formula is badly conditioned as n grows, so the eigenvalues of A − B·K are compared with the requested poles, each within 1e-6 of the problem's own scale (the largest of ‖A‖ and the poles' moduli), and a gain that misses is declined rather than returned. Floating point: an exact operand is demoted, the expm precedent.
Value parameters
- a
-
the state matrix,
n×n - b
-
the input matrix,
n×1 - poles
-
the requested closed-loop poles,
nof them, closed under conjugation
Attributes
- Returns
-
Kas a1×nrow, orNonefor a multi-input or uncontrollable plant, poles not closed under conjugation or notnof them, or a gain that fails the certificate
Identifies an ARX model by least squares (F_0060), in the predictor form of ArxModel.
Identifies an ARX model by least squares (F_0060), in the predictor form of ArxModel.
Declines data that does not excite the model rather than fitting it: the regressor matrix must have full numerical rank at the session precision — svd and the relative tolerance rank uses (F_0061 Decision B) — before leastSquares is asked. QR alone would return numbers on an unexcited data set, meaningless ones. The fit is QR, never the normal equations. One output (MISO, Decision C); a model whose outputs are coupled is arxMimo.
Value parameters
- env
-
the environment, whose precision sets the rank tolerance and whose limits the regressor size and the SVD's work
- na
-
the autoregressive order
- nb
-
the coefficients per input
- nk
-
the input delay
- u
-
the inputs,
m×NorN×m - y
-
the output,
1×NorN×1
Attributes
- Returns
-
the model, or the reason it was declined
The non-minimal state-space (NMSS) realisation of a MIMO ARX model (F_0306, AIACE L_0009), whose state is measured: x(k) = [y(k), y(k−1), …, y(k−nᵧ+1), u(k−1), …, u(k−nᵤ)] with nᵧ = max(na, 1) and nᵤ = nk + nb − 2, exactly the past the recursion reads (Wang and Young's count; an older input never enters it). C reads y(k) off the state and D = 0, so a controller on this model needs no observer. nk = 0 declines: y(k+1) would then depend on u(k+1), which no state at time k can hold.
The non-minimal state-space (NMSS) realisation of a MIMO ARX model (F_0306, AIACE L_0009), whose state is measured: x(k) = [y(k), y(k−1), …, y(k−nᵧ+1), u(k−1), …, u(k−nᵤ)] with nᵧ = max(na, 1) and nᵤ = nk + nb − 2, exactly the past the recursion reads (Wang and Young's count; an older input never enters it). C reads y(k) off the state and D = 0, so a controller on this model needs no observer. nk = 0 declines: y(k+1) would then depend on u(k+1), which no state at time k can hold.
Value parameters
- model
-
the identified model
- nk
-
the input delay,
≥ 1
Attributes
- Returns
-
(A, B, C, D),p·nᵧ + m·nᵤstates, or the reason
The incremental NMSS realisation (F_0306): the input is Δu(k) and the state [Δy(k), …, Δy(k−nᵧ+1), Δu(k−1), …, Δu(k−nᵤ), y(k)] — Wang and Young's incremental form with the output appended, so y(k+1) = y(k) + Δy(k+1) is a row of the model and C reads y(k) directly. Stated because the literature carries several incremental forms; this one has an integrator on every output, which is what makes a controller on it offset-free. nk = 0 declines as in arx2nmss.
The incremental NMSS realisation (F_0306): the input is Δu(k) and the state [Δy(k), …, Δy(k−nᵧ+1), Δu(k−1), …, Δu(k−nᵤ), y(k)] — Wang and Young's incremental form with the output appended, so y(k+1) = y(k) + Δy(k+1) is a row of the model and C reads y(k) directly. Stated because the literature carries several incremental forms; this one has an integrator on every output, which is what makes a controller on it offset-free. nk = 0 declines as in arx2nmss.
Value parameters
- model
-
the identified model
- nk
-
the input delay,
≥ 1
Attributes
- Returns
-
(A, B, C, D),p·nᵧ + m·nᵤ + pstates, or the reason
A state-space realisation [A, B, C, D] of an ARX model (F_0060), discrete-time.
A state-space realisation [A, B, C, D] of an ARX model (F_0060), discrete-time.
The observer canonical form of arx2tf's common denominator: with n = max(na, nk + nb − 1) states, A carries a₁ … aₙ down its first column and ones on its superdiagonal, C = [1, 0, …, 0], D the direct feedthrough (b₁ⱼ when nk = 0, else 0), and B the numerator less that feedthrough times the denominator. From rest, its recursion x[k+1] = A·x[k] + B·u[k], y[k] = C·x[k] + D·u[k] reproduces the ARX output sample for sample — which is the test, rather than a transcribed matrix.
Value parameters
- a
-
the autoregressive coefficients, predictor sign; empty for none
- b
-
per input, its
nbcoefficients - nk
-
the input delay
Attributes
- Returns
-
(A, B, C, D), or the reason — ArxFailure.NoState for a static gain
The discrete transfer functions of an ARX model, one per input (F_0060).
The discrete transfer functions of an ARX model, one per input (F_0060).
Gⱼ(z) = Bⱼ(z)/A(z) written in positive powers of z: with n = max(na, nk + nb − 1), A(z) = zⁿ − Σ aᵢ·zⁿ⁻ⁱ and Bⱼ(z) = Σ bₗⱼ·zⁿ⁻ⁿᵏ⁻ˡ⁺¹, folded to lowest terms by the same normaliseTf feedback uses — so its poles are what poles reports. The delay is an argument (Decision B), visible where it acts, so b holds exactly what was estimated.
Value parameters
- a
-
the autoregressive coefficients, predictor sign; empty for none
- b
-
per input, its
nbcoefficients - nk
-
the input delay
- z
-
the discrete frequency variable to write the result in
Attributes
- Returns
-
one rational in
zper input, or the reason the model is malformed
Identifies a MIMO ARX model by least squares (F_0093), the outputs coupled through p×p blocks Aᵢ (see ArxMimoModel).
Identifies a MIMO ARX model by least squares (F_0093), the outputs coupled through p×p blocks Aᵢ (see ArxMimoModel).
Every output is regressed on the same regressor matrix — the stacked past of every output and the inputs (arxRegressors) — so the excitation test runs once and the fit is one QR solve per output column. Declines exactly as arx does; at p = 1 it is arx.
Value parameters
- env
-
the environment, whose precision sets the rank tolerance and whose limits the regressor size and the SVD's work
- na
-
the autoregressive order
- nb
-
the coefficients per input
- nk
-
the input delay
- u
-
the inputs,
m×NorN×m - y
-
the outputs,
p×NorN×p
Attributes
- Returns
-
the model, or the reason it was declined
Selects ARX orders over the grid nas × nbs × nks by an information criterion (F_0301).
Selects ARX orders over the grid nas × nbs × nks by an information criterion (F_0301).
Every candidate is fitted and scored on the same equations, k = k₀ … N − 1 with k₀ the largest max(na, nk + nb − 1) on the grid — a criterion compares losses, and losses over different samples do not compare. Each fit is arxMimo with its rank guard, so a candidate the data does not excite is skipped and reported, never scored. With validation, V is the one-step prediction loss on the validation data over the same k₀ (the estimate's loss favours the largest model); the penalty is the criterion's either way. The lowest score wins, a tie going to fewer coefficients and then to the earlier candidate, so on noise-free data, where every model containing the true one fits exactly (V = 0, score −∞), the true orders are chosen.
The grid is held to core.Limit.MaxArxOrderWork, the sum of the candidates' r·c² for their r×c regressor matrices, checked before any fit.
Value parameters
- criterion
-
the criterion, named
- env
-
the precision of the rank guard, and the budgets
- nas
-
the autoregressive orders to try
- nbs
-
the coefficient counts per input to try
- nks
-
the delays to try
- u
-
the inputs,
m×NorN×m - validation
-
validation inputs and outputs in the same layout, or
None - y
-
the outputs,
p×NorN×p
Attributes
- Returns
-
the selection, or the reason none was made
The one-step prediction error of an ARX model on a window of data (F_0330, AIACE L_0014): y(k) − Σ aᵢ·y(k−1−i) − Σ bₗ·u(k−nk−l) with the measured past outputs, the residual arx minimises and arxOrderSelection ranks by — on any data, the model's own or a window it was not fitted on. The data is read as arxRegressors reads it, in the predictor sign.
The one-step prediction error of an ARX model on a window of data (F_0330, AIACE L_0014): y(k) − Σ aᵢ·y(k−1−i) − Σ bₗ·u(k−nk−l) with the measured past outputs, the residual arx minimises and arxOrderSelection ranks by — on any data, the model's own or a window it was not fitted on. The data is read as arxRegressors reads it, in the predictor sign.
A small one-step error says the model explains each sample from the samples just before it; a model used over a horizon is tested by arxSimulationError, which is stricter.
Value parameters
- env
-
the budgets: the residual series is held to core.Limit.MaxMatrixCells
- model
-
the model
- nk
-
the input delay it was fitted with
- u
-
the inputs,
m×NorN×m - y
-
the outputs,
p×NorN×p
Attributes
- Returns
-
the error, or the reason: data that does not have the model's inputs and outputs, a window no longer than the model's reach, a sample that is not finite
The regressor matrix and target of an ARX fit (F_0060; several outputs since F_0093).
The regressor matrix and target of an ARX fit (F_0060; several outputs since F_0093).
For k = k₀ … N−1 with k₀ = max(na, nk + nb − 1), row k is [y[k−1]ᵀ … y[k−na]ᵀ, u₁[k−nk] … u₁[k−nk−nb+1], u₂[…] …] — every output's past lag by lag, then each input's lags — and the target row is y[k]ᵀ. The outputs are p×N (a row per output) or N×p, the samples running along the longer side and rows-per-output on a tie, so a row or a column is one output exactly as before; the inputs are m×N (a row per input) or N×m, read by which side matches N — m×N when both do. It needs only one row; a short experiment's rows can be stacked with another's before fitting, which is why the rows-per-coefficient requirement belongs to arx, not here.
Value parameters
- na
-
the autoregressive order,
≥ 0 - nb
-
the number of coefficients per input,
≥ 1 - nk
-
the input delay,
≥ 0;nk = 0is direct feedthrough - u
-
the inputs
- y
-
the outputs
Attributes
- Returns
-
(X, Y),Ywith a column per output, or the reason they cannot be built
The free-run (simulation) error of an ARX model on a window of data (F_0330, AIACE L_0014): the outputs before sample max(na, nk + nb − 1) are the measured ones, and every later output is the model's own, fed back — the measured inputs drive it, the measured outputs never correct it. It is the test of a model used to predict over a horizon: an error the one-step prediction forgets at every sample accumulates here. Declined when the simulated output leaves the finite numbers (an unstable model on a long window), never answered as an infinity.
The free-run (simulation) error of an ARX model on a window of data (F_0330, AIACE L_0014): the outputs before sample max(na, nk + nb − 1) are the measured ones, and every later output is the model's own, fed back — the measured inputs drive it, the measured outputs never correct it. It is the test of a model used to predict over a horizon: an error the one-step prediction forgets at every sample accumulates here. Declined when the simulated output leaves the finite numbers (an unstable model on a long window), never answered as an infinity.
Value parameters
- env
-
the budgets: the residual series is held to core.Limit.MaxMatrixCells
- model
-
the model
- nk
-
the input delay it was fitted with
- u
-
the inputs,
m×NorN×m - y
-
the outputs,
p×NorN×p
Attributes
- Returns
-
the error, or the reason
The plant (A, B, C) augmented with disturbance states entering through Bd, Cd (F_0300).
The plant (A, B, C) augmented with disturbance states entering through Bd, Cd (F_0300).
Admissible only when the augmented pair is detectable (Pannocchia and Rawlings): (A, C) detectable — A restricted to the unobservable subspace, the null space of the observability matrix read by the SVD at the library's rank tolerance, has every eigenvalue strictly inside the unit circle — and [[A − I, Bd], [C, Cd]] of full column rank n + nd, so nd ≤ p. Both are rank questions answered by singular values relative to the largest, never by a determinant (the 2.11 rule).
Value parameters
- a
-
the state matrix,
n×n - b
-
the input matrix,
n×m - bd
-
the disturbance's entry into the state,
n×nd - c
-
the output matrix,
p×n - cd
-
the disturbance's entry into the output,
p×nd - env
-
the precision that sets the rank tolerance, and the budgets
Attributes
- Returns
-
the augmented model, or why the disturbance model is not admissible
Frequency response of G at angular frequency w: substitute v -> i*w.
Frequency response of G at angular frequency w: substitute v -> i*w.
Rides the existing _Complex closure — no new arithmetic — which is why the whole of Bode and Nyquist is one substitution.
Value parameters
- g
-
the transfer function
- v
-
the frequency variable
- w
-
the angular frequency, in radians per unit time
Attributes
- Returns
-
(magnitude, phase-in-radians), orNonewhere the response is not finite (evaluating an integrator atw = 0, say) — never a fabricated infinity
Discretises a continuous transfer function over sample period ts.
Discretises a continuous transfer function over sample period ts.
Tustin and both Euler methods are substitutions for s, renormalised. Zero-order hold, first-order hold and impulse invariance are response equivalences: the step, ramp or impulse response, sampled at n·Ts, transformed by the z-transform and scaled — assembled from the inverse Laplace transform and the z-transform, which is why the z-transform had to exist first. Matched pole-zero maps the roots themselves.
Value parameters
- g
-
the continuous transfer function
- method
-
the method, always named
- s
-
the continuous frequency variable
- ts
-
the sample period; must be positive
- z
-
the discrete variable to express the result in
Attributes
- Returns
-
the discrete transfer function, or
Nonewhen the conversion does not close
Exact state-space discretisation over one sample period: A_d = e^(A*Ts).
Exact state-space discretisation over one sample period: A_d = e^(A*Ts).
Uses the block-matrix form, not B_d = A⁻¹(A_d − I)B, and that is a correctness matter rather than tidiness. Exponentiating [[A, B], [0, 0]]*Ts yields [[A_d, B_d], [0, I]] in one step, and it is defined for a singular A — where the inverse form is not, even though B_d exists. A singular A is entirely ordinary: any system with an integrator has one, so the naive form would fail on a common case rather than an exotic one.
This is what the matrix exponential exists to supply, and what a Kalman filter needs.
Value parameters
- a
-
the continuous state matrix
- b
-
the continuous input matrix
- ts
-
the sample period
Attributes
- Returns
-
(A_d, B_d), orNonewhen the operands are not conforming dense matrices
Prewarped Tustin (F_0009): the bilinear transform scaled so the discrete frequency response equals the continuous one exactly at w, s = (w / tan(w·Ts/2))·(z − 1)/(z + 1). Plain Tustin compresses the whole frequency axis into the Nyquist band, so a filter's corner lands somewhere else; prewarping puts the one frequency that matters back.
Prewarped Tustin (F_0009): the bilinear transform scaled so the discrete frequency response equals the continuous one exactly at w, s = (w / tan(w·Ts/2))·(z − 1)/(z + 1). Plain Tustin compresses the whole frequency axis into the Nyquist band, so a filter's corner lands somewhere else; prewarping puts the one frequency that matters back.
Value parameters
- g
-
the continuous transfer function
- s
-
the continuous frequency variable
- ts
-
the sample period; must be positive
- w
-
the frequency to match, in rad/s, with
0 < w·Ts/2 < π/2 - z
-
the discrete variable to express the result in
Attributes
- Returns
-
the discrete transfer function, or
None
Is the pair (A, B) controllable — can the input steer every state?
Is the pair (A, B) controllable — can the input steer every state?
Value parameters
- a
-
the state matrix
- b
-
the input matrix
Attributes
- Returns
-
Some(true)/Some(false), orNonewhen either operand is not a dense matrix
Inverse of c2d: recovers a continuous transfer function from a discrete one.
Inverse of c2d: recovers a continuous transfer function from a discrete one.
The substitution methods invert in closed form: Tustin by z = (2 + Ts*s)/(2 - Ts*s), which is what makes d2c(c2d(G)) return to G, and the Euler methods by z = 1 + Ts·s and z = 1/(1 − Ts·s) (F_0009). The response equivalences would need a matrix logarithm, and matched pole-zero a logarithm of each root with its branch; all four are declined rather than approximated.
Value parameters
- g
-
the discrete transfer function
- method
-
the method
gwas discretised with - s
-
the continuous variable to express the result in
- ts
-
the sample period
- z
-
the discrete variable
Attributes
- Returns
-
the continuous transfer function, or
None
Inverse of c2dPrewarped: z = (c + s)/(c − s), c = w / tan(w·Ts/2).
Inverse of c2dPrewarped: z = (c + s)/(c − s), c = w / tan(w·Ts/2).
Value parameters
- g
-
the discrete transfer function
- s
-
the continuous variable to express the result in
- ts
-
the sample period
- w
-
the frequency the discretisation was prewarped at
- z
-
the discrete variable
Attributes
- Returns
-
the continuous transfer function, or
None
The stabilising solution P of the discrete algebraic Riccati equation AᵀPA − P − AᵀPB(R + BᵀPB)⁻¹BᵀPA + Q = 0 (F_0065, MPC T3-01).
The stabilising solution P of the discrete algebraic Riccati equation AᵀPA − P − AᵀPB(R + BᵀPB)⁻¹BᵀPA + Q = 0 (F_0065, MPC T3-01).
Solved by structure-preserving doubling, then certified (X-02) twice:
- the residual, relative to the larger of
‖Q‖,‖AᵀPA‖and‖P‖, against0.5·10⁻ᵖ; - the closed loop
A − B·Kwith every eigenvalue strictly inside the unit circle.
The second test is what declines a problem with no stabilising solution — (A, B) not stabilisable — and one whose (A, Q^½) is not detectable, as T3-01 asks. A solution of the equation that does not stabilise is never answered. For the second case the refusal comes from the iteration itself: it starts at H₀ = Q, and an unstable mode Q does not penalise stays at 0 there (a = 2, b = 1, q = 0, r = 1 gives p = 0, not the stabilising p = 3), which the closed-loop test then refuses.
Value parameters
- a
-
the state matrix,
n×n - b
-
the input matrix,
n×m - env
-
the evaluation environment, whose precision sets the certificate
- q
-
the state weight, symmetric positive semidefinite
n×n - r
-
the input weight, symmetric positive definite
m×m
Attributes
- Returns
-
P, symmetric, or why there is none
Steady-state gain: G evaluated at v = 0.
Steady-state gain: G evaluated at v = 0.
Value parameters
- g
-
the transfer function
- v
-
the frequency variable
Attributes
- Returns
-
G(0), orNonewhen it is not finite (a pole at the origin) or not rational
The steady-state Kalman gain of the augmented model (F_0300), through kalmanGain.
The steady-state Kalman gain of the augmented model (F_0300), through kalmanGain.
Value parameters
- env
-
the precision of the certificate
- model
-
the augmented model
- qw
-
the process noise covariance of the augmented state,
(n+nd)×(n+nd) - rv
-
the measurement noise covariance,
p×p
Attributes
- Returns
-
(M, P), as kalmanGain answers, or why not
The infinite-horizon discrete LQR: the gain K of the law u = −K·x minimising Σ xᵀQx + uᵀRu, and the Riccati solution P (F_0065).
The infinite-horizon discrete LQR: the gain K of the law u = −K·x minimising Σ xᵀQx + uᵀRu, and the Riccati solution P (F_0065).
K = (R + BᵀPB)⁻¹BᵀPA, so the closed loop is A − B·K. The sign is stated because the literature also writes u = K·x (the feedback lesson: a convention that cannot be inferred is written down). See dare for the solver, the certificate and the refusals.
Value parameters
- a
-
the state matrix,
n×n - b
-
the input matrix,
n×m - env
-
the evaluation environment, whose precision sets the certificate
- q
-
the state weight, symmetric positive semidefinite
n×n - r
-
the input weight, symmetric positive definite
m×m
Attributes
- Returns
-
(K, P), or why there is none
Simulates the discrete-time model x[k+1] = A·x[k] + B·u[k], y[k] = C·x[k] + D·u[k] over the input sequence u from x[0] = x0 (F_0064, MPC T2-07).
Simulates the discrete-time model x[k+1] = A·x[k] + B·u[k], y[k] = C·x[k] + D·u[k] over the input sequence u from x[0] = x0 (F_0064, MPC T2-07).
Returns the outputs Y (p×N, column k is y[k]) and the states X (n×(N+1), columns x[0] … x[N]). The final state is included where MATLAB's and scipy's dlsim stop at x[N−1]: x[N] is the state a simulation continues from, so returning it is the "state in, state out" rule (X-04) — a long run can be split into calls with no gap.
Declines rather than overflowing: an unstable model run long enough leaves the finite numbers, and the step where that happened is reported instead of a matrix of Infinity. Floating point throughout, the expm/c2dExact precedent.
Value parameters
- a
-
the state matrix,
n×n - b
-
the input matrix,
n×m - c
-
the output matrix,
p×n - d
-
the feedthrough matrix,
p×m - u
-
the inputs,
m×N— columnkisu[k] - x0
-
the initial state,
n×1
Attributes
- Returns
-
(Y, X), or the reason the simulation was declined
The solution X of the Stein (discrete Lyapunov) equation A·X·Aᵀ − X + Q = 0 (F_0065) — the requirement's dlyap, named sugar over what solve's vectorized tier already answers.
The solution X of the Stein (discrete Lyapunov) equation A·X·Aᵀ − X + Q = 0 (F_0065) — the requirement's dlyap, named sugar over what solve's vectorized tier already answers.
Solved by the same doubling with G = 0 (Smith's method), so its cost is log of the decay rather than n²-sized vectorisation. Requires A stable (every eigenvalue strictly inside the unit circle), the condition for the series Σ AᵏQ(Aᵀ)ᵏ to converge; declined otherwise. Q need only be square: the equation is linear in it.
Value parameters
- a
-
the matrix,
n×n - env
-
the evaluation environment, whose precision sets the certificate
- q
-
the right-hand side,
n×n
Attributes
- Returns
-
X, or why there is none
Closed loop with negative feedback: G / (1 + G*H).
Closed loop with negative feedback: G / (1 + G*H).
The sign convention is stated because it cannot be inferred. Negative feedback is the control convention and what a unity-feedback loop means by default; a substantial part of the literature writes the positive form G/(1 - G*H), and choosing silently would make every closed-loop result wrong for half its readers — the reasoning that also fixes the spherical polar-angle convention in the vector package. For positive feedback, negate h.
Value parameters
- g
-
the forward path
- h
-
the feedback path (use
_Number(1)for unity feedback) - v
-
the frequency variable
Attributes
- Returns
-
the closed-loop transfer function, normalised to a single rational
The Bode sweep: magnitude in decibels and unwrapped phase in degrees, over a logarithmically spaced grid (issue F_0004).
The Bode sweep: magnitude in decibels and unwrapped phase in degrees, over a logarithmically spaced grid (issue F_0004).
Unwrapping is the substance here, not the grid. bode's phase comes from atan2, whose principal value is (-pi, pi], so a swept curve jumps by a full turn wherever it crosses the branch cut — 1/(s+1)^3 tends to -270 degrees but a raw sweep reports +90. That jump is an artefact of the arctangent and not of the plant, and every reader who plots a raw sweep inherits it. This accumulates a turn whenever consecutive samples differ by more than half a turn, which restores the continuous curve.
dB and degrees rather than the raw pair, because that is what a Bode plot is; the raw magnitude and radian phase stay available from bode itself, so nothing is lost.
The one assumption worth stating: unwrapping cannot distinguish a genuine half-turn step from a grid too coarse to resolve a fast one, so a sparse sweep across a lightly damped resonance can unwrap the wrong way. That is inherent to unwrapping rather than particular to this implementation, and the remedy is points, not cleverness.
A frequency where the response is not finite — a pole on the imaginary axis — is dropped, mirroring scalar.sample; the unwrapping state carries across the gap, so the curve resumes rather than restarting.
Value parameters
- env
-
bindings for any parameter the plant carries
- g
-
the transfer function
- points
-
how many samples, at least 2
- v
-
the frequency variable
- wMax
-
the highest angular frequency
- wMin
-
the lowest angular frequency, strictly positive
Attributes
- Returns
-
(omega, magnitude-in-dB, unwrapped-phase-in-degrees), ascending in omega
Impulse response L^-1{G(s)}. Declines for an improper G, as stepResponse does.
Impulse response L^-1{G(s)}. Declines for an improper G, as stepResponse does.
Value parameters
- g
-
the transfer function
- s
-
the frequency variable
- t
-
the time variable, free in the result
Attributes
- Returns
-
the response, or _ImpulseResponse unchanged when no rule applies
The input-disturbance model (F_0300): Bd = B, Cd = 0, one disturbance per input.
The input-disturbance model (F_0300): Bd = B, Cd = 0, one disturbance per input.
Value parameters
- a
-
the state matrix
- b
-
the input matrix
- c
-
the output matrix
- env
-
the precision and budgets
Attributes
- Returns
-
the augmented model, or why not
Continuous-time stability: every pole strictly in the left half-plane.
Continuous-time stability: every pole strictly in the left half-plane.
Decided from the poles rather than from a Routh table, a deliberate departure from the original plan. Routh's advantage is symbolic coefficients, but it carries well-known degenerate cases — a zero in the first column, or an identically zero row — each needing its own repair, and a mis-handled one yields a confident wrong verdict rather than a refusal. Root location has neither failure mode. Symbolic coefficients are refused here instead, which is the same answer Routh would have to give once scalar.sign could not decide, and routhTable remains available for the table itself.
Strict, so marginal stability is not stability: poles on the imaginary axis give false. An oscillator that never decays is not a stable system, and reporting it as one would be the confident wrong answer.
Value parameters
- g
-
the transfer function
- v
-
the frequency variable
Attributes
- Returns
-
Some(true)/Some(false), orNonewhen the poles cannot be determined
Discrete-time stability: every pole strictly inside the unit circle.
Discrete-time stability: every pole strictly inside the unit circle.
The continuous test does not transfer. z = 0.5 is a stable discrete pole while the same value read as a continuous one is unstable, so applying the left-half-plane rule to a z-domain transfer function inverts the answer rather than degrading it.
Value parameters
- g
-
the discrete transfer function
- v
-
the z-domain variable
Attributes
- Returns
-
Some(true)/Some(false), orNonewhen the poles cannot be determined
The steady-state Kalman filter for x[k+1] = A·x + B·u + w, y = C·x + D·u + v, w ~ N(0, Qw), v ~ N(0, Rv): the measurement-update gain M and the a priori covariance P (F_0065).
The steady-state Kalman filter for x[k+1] = A·x + B·u + w, y = C·x + D·u + v, w ~ N(0, Qw), v ~ N(0, Rv): the measurement-update gain M and the a priori covariance P (F_0065).
P solves the dual Riccati equation, dare(Aᵀ, Cᵀ, Qw, Rv), and M = P·Cᵀ(C·P·Cᵀ + Rv)⁻¹ is the gain kalmanStep's update applies. P is returned as well as M, as dlqr returns its P: it is what starts kalmanStep at steady state.
Value parameters
- a
-
the state matrix,
n×n - c
-
the output matrix,
p×n - env
-
the evaluation environment, whose precision sets the certificate
- qw
-
the process noise covariance, symmetric positive semidefinite
n×n - rv
-
the measurement noise covariance, symmetric positive definite
p×p
Attributes
- Returns
-
(M, P), or why there is none
One step of the discrete Kalman filter: update, then predict (F_0065, MPC T3-01).
One step of the discrete Kalman filter: update, then predict (F_0065, MPC T3-01).
From the prior x̂, P for step k and that step's u, y: the innovation y − C·x̂ − D·u, the gain M = P·Cᵀ(C·P·Cᵀ + Rv)⁻¹, the posterior x̂⁺ = x̂ + M·(innovation) with the Joseph-form covariance (I − M·C)·P·(I − M·C)ᵀ + M·Rv·Mᵀ, which stays symmetric positive semidefinite under rounding where (I − M·C)·P does not; then the prediction x̂' = A·x̂⁺ + B·u, P' = A·P⁺·Aᵀ + Qw. Both covariances are symmetrised, the RLS rule.
Returns the prior for step k + 1, so the result feeds back as the next call's input: state in, state out (X-04), nothing remembered.
Value parameters
- a
-
the state matrix,
n×n - b
-
the input matrix,
n×m - c
-
the output matrix,
p×n - d
-
the feedthrough matrix,
p×m - p
-
the prior error covariance,
n×n - qw
-
the process noise covariance,
n×n - rv
-
the measurement noise covariance,
p×p - u
-
the input at this step,
m×1 - xhat
-
the prior state estimate,
n×1 - y
-
the measurement at this step,
p×1
Attributes
- Returns
-
(x̂', P'), or why the step cannot be taken
Linearises x' = F(x, u), y = G(x, u) about the operating point (x₀, u₀) (F_0059).
Linearises x' = F(x, u), y = G(x, u) about the operating point (x₀, u₀) (F_0059).
A = ∂F/∂x, B = ∂F/∂u, C = ∂G/∂x, D = ∂G/∂u — four vector._Jacobians, so the library has one definition of a Jacobian — evaluated at the point, plus the offsets F(x₀, u₀) and G(x₀, u₀) that are zero only at an equilibrium. The tuples are ordered and explicit, never inferred from the free names (the grad rule): the column order of A is the order given. A field or a point may be written as a column or, for one component, as a bare expression (a number is a 1×1 matrix, the mpcMatrices reading).
Declines rather than linearising at a point where the model is not defined there. The domain analysis is consulted first, at a numeric point — its one use as a guard, allowed because this call is new and changes no existing result — and then every value and partial must be real: a complex value, a pole, or a kink such as abs(x) at 0 (whose derivative is 0/0) is a refusal with the entry named, never a number. A point with free parameters gives a symbolic linearisation; a closed entry that did not fold is a failed computation, not a symbolic one, and declines (the laurent rule).
Value parameters
- env
-
the environment (precision, working precision, bindings of other parameters)
- f
-
the dynamics,
n×1 - g
-
the outputs,
p×1 - u
-
the input names, in order
- u0
-
the operating input,
m×1 - x
-
the state names, in order
- x0
-
the operating state,
n×1
Attributes
- Returns
-
the linearisation, or the reason it was declined
Reduces a discrete- or continuous-time realisation to its controllable and observable part (F_0307, AIACE L_0009): the Kalman decomposition, which removes exactly the states that do not reach the input-output map.
Reduces a discrete- or continuous-time realisation to its controllable and observable part (F_0307, AIACE L_0009): the Kalman decomposition, which removes exactly the states that do not reach the input-output map.
First an orthonormal basis U of the controllable subspace (the range of [B, AB, …, Aⁿ⁻¹B]), which is A-invariant, so (UᵀAU, UᵀB, CU) has the same transfer function; then an orthonormal basis V of the orthogonal complement of its unobservable subspace (the range of the observability matrix's transpose), so (VᵀA₁V, VᵀB₁, C₁V) keeps it too. Each rank is read by singular values at the library's rank tolerance, relative to the largest (the 2.11 rule). Certified: the Markov parameters C·Aᵏ·B, k = 0 … n + r − 1 (enough to fix both transfer functions), must agree, each to 0.5·10⁻ᵖ of ‖C‖‖Aᵏ‖‖B‖. Not balanced truncation, which approximates and needs a stable plant.
Value parameters
- a
-
the state matrix,
n×n - b
-
the input matrix,
n×m - c
-
the output matrix,
p×n - d
-
the feedthrough,
p×m - env
-
the precision of the rank tolerance and the certificate, and the budgets
Attributes
- Returns
-
the minimal realisation, or why not
The numeric prediction matrices of a model (A, B, C) whose input is an increment of an accumulated input (F_0328, AIACE L_0012): the increments are zero past Nc, see MpcAccumulatedPrediction. For a plant (A, B, C) in absolute inputs, the model [[A, B], [0, I]], [[B], [I]], [C, 0] with the state [x, u(k−1)] gives the same programme as mpcIncrementalPrediction of the plant.
The numeric prediction matrices of a model (A, B, C) whose input is an increment of an accumulated input (F_0328, AIACE L_0012): the increments are zero past Nc, see MpcAccumulatedPrediction. For a plant (A, B, C) in absolute inputs, the model [[A, B], [0, I]], [[B], [I]], [C, 0] with the state [x, u(k−1)] gives the same programme as mpcIncrementalPrediction of the plant.
Value parameters
- a
-
the state matrix,
n×n - b
-
the matrix of the increments,
n×m - c
-
the output matrix,
p×n - limits
-
the budgets: core.Limit.MaxMpcHorizon and core.Limit.MaxMatrixCells
- nc
-
the control horizon,
1 ≤ Nc ≤ Np - np
-
the prediction horizon,
1 ≤ Np ≤ Limit.MaxMpcHorizon
Attributes
- Returns
-
(Φ, Γ), or why not
The state prediction at the end of the horizon for a model whose input is an increment (F_0328): x(k+Np) = Φₓ·x + Γₓ·ΔU, the increments zero past Nc — the last block row of mpcAccumulatedPrediction for C = I, the terminal prediction an MpcAccumulatedPrediction goes with.
The state prediction at the end of the horizon for a model whose input is an increment (F_0328): x(k+Np) = Φₓ·x + Γₓ·ΔU, the increments zero past Nc — the last block row of mpcAccumulatedPrediction for C = I, the terminal prediction an MpcAccumulatedPrediction goes with.
Value parameters
- a
-
the state matrix,
n×n - b
-
the matrix of the increments,
n×m - limits
-
the budgets
- nc
-
the control horizon
- np
-
the prediction horizon
Attributes
- Returns
-
the prediction,
nrows, or why not
The numeric prediction matrices of (A, B, C) in increments (F_0298, AIACE L_0001).
The numeric prediction matrices of (A, B, C) in increments (F_0298, AIACE L_0001).
Value parameters
- a
-
the state matrix,
n×n - b
-
the input matrix,
n×m - c
-
the output matrix,
p×n - limits
-
the budgets: core.Limit.MaxMpcHorizon and core.Limit.MaxMatrixCells
- nc
-
the control horizon,
1 ≤ Nc ≤ Np - np
-
the prediction horizon,
1 ≤ Np ≤ Limit.MaxMpcHorizon
Attributes
- Returns
-
(Φ, Ψ, Θ), or why not
The prediction matrices (Φ, Γ) of (A, B, C) over the horizons Np and Nc.
The prediction matrices (Φ, Γ) of (A, B, C) over the horizons Np and Nc.
A number is read as a 1×1 matrix (F_0055 Decision C); an operand whose shape is not known (a free name) declines.
Value parameters
- a
-
the state matrix,
n×n - b
-
the input matrix,
n×m - c
-
the output matrix,
p×n - env
-
the environment the operands evaluate in
- nc
-
the control horizon,
1 ≤ Nc ≤ Np - np
-
the prediction horizon,
1 ≤ Np ≤the environment'sLimit.MaxMpcHorizon
Attributes
- Returns
-
(Φ, Γ)as evaluated matrices, orNonewhen the plant does not conform, a horizon is out of range, an operand's shape is unknown, or a result would exceed the environment'sLimit.MaxMatrixCells
The numeric prediction matrices of (A, B, C) in absolute inputs (F_0298, AIACE L_0001): the dense counterpart of mpcMatrices, computed over arrays for a controller that rebuilds them each cycle.
The numeric prediction matrices of (A, B, C) in absolute inputs (F_0298, AIACE L_0001): the dense counterpart of mpcMatrices, computed over arrays for a controller that rebuilds them each cycle.
Value parameters
- a
-
the state matrix,
n×n - b
-
the input matrix,
n×m - c
-
the output matrix,
p×n - limits
-
the budgets: core.Limit.MaxMpcHorizon and core.Limit.MaxMatrixCells
- nc
-
the control horizon,
1 ≤ Nc ≤ Np - np
-
the prediction horizon,
1 ≤ Np ≤ Limit.MaxMpcHorizon
Attributes
- Returns
-
(Φ, Γ), or why not
Builds the condensed MPC quadratic programme (F_0299, AIACE L_0002) with one weight for every step: mpcQp with MpcWeights(Vector(q), Vector(r)).
Builds the condensed MPC quadratic programme (F_0299, AIACE L_0002) with one weight for every step: mpcQp with MpcWeights(Vector(q), Vector(r)).
Value parameters
- bounds
-
the bounds and the soft outputs
- limits
-
the budgets (the QP's own are checked when it is solved)
- prediction
-
the prediction matrices, absolute or incremental (F_0298)
- q
-
the output weight
Q,p×p, the same at every step - r
-
the move weight
R,m×m, the same at every step; in the absolute form it pulls the inputs towards zero (see MpcWeights.inputTarget) - reference
-
the reference:
pentries held over the horizon, orNp·pstacked - uPrev
-
u(k−1),mentries - x
-
the current state,
nentries
Attributes
- Returns
-
the programme, or why it cannot be built
The state prediction at the end of the horizon (F_0304): x(k+Np) = Φₓ·x + Γₓ·U (absolute) or Φₓ·x + Ψₓ·u(k−1) + Θₓ·ΔU (incremental), the last move held past Nc as everywhere. It is the last block row of mpcPrediction / mpcIncrementalPrediction for C = I, so the two cannot disagree.
The state prediction at the end of the horizon (F_0304): x(k+Np) = Φₓ·x + Γₓ·U (absolute) or Φₓ·x + Ψₓ·u(k−1) + Θₓ·ΔU (incremental), the last move held past Nc as everywhere. It is the last block row of mpcPrediction / mpcIncrementalPrediction for C = I, so the two cannot disagree.
Value parameters
- a
-
the state matrix,
n×n - b
-
the input matrix,
n×m - incremental
-
the incremental form
- limits
-
the budgets
- nc
-
the control horizon
- np
-
the prediction horizon
Attributes
- Returns
-
the prediction,
nrows, or why not
Nyquist point: the real and imaginary parts of G(i*w).
Nyquist point: the real and imaginary parts of G(i*w).
The same substitution as bode, reported in rectangular rather than polar form — the two are one computation presented two ways, not two computations.
Value parameters
- g
-
the transfer function
- v
-
the frequency variable
- w
-
the angular frequency
Attributes
- Returns
-
(real, imaginary), orNonewhere the response is not finite
The Nyquist sweep: the same grid as frequencyResponse, in rectangular coordinates.
The Nyquist sweep: the same grid as frequencyResponse, in rectangular coordinates.
One sweep presented two ways — the relationship bode and nyquist already have, and the reason both read the same logGrid rather than each building one. Unwrapping does not arise here: a point in the plane is unchanged by adding a turn to its argument.
Value parameters
- env
-
bindings for any parameter the plant carries
- g
-
the transfer function
- points
-
how many samples, at least 2
- v
-
the frequency variable
- wMax
-
the highest angular frequency
- wMin
-
the lowest angular frequency, strictly positive
Attributes
- Returns
-
(real, imaginary)for each grid frequency, non-finite points dropped
Is the pair (A, C) observable — can the output distinguish every state?
Is the pair (A, C) observable — can the output distinguish every state?
Observability of (A, C) is controllability of (Aᵀ, Cᵀ) — the duality, used here rather than restated, so the two can never disagree.
Value parameters
- a
-
the state matrix
- c
-
the output matrix
Attributes
- Returns
-
Some(true)/Some(false), orNonewhen either operand is not a dense matrix
The output-disturbance model (F_0300): Bd = 0, Cd = I, one disturbance per output.
The output-disturbance model (F_0300): Bd = 0, Cd = I, one disturbance per output.
Value parameters
- a
-
the state matrix
- b
-
the input matrix
- c
-
the output matrix
- env
-
the precision and budgets
Attributes
- Returns
-
the augmented model, or why not
Parallel connection: G + H.
Parallel connection: G + H.
Value parameters
- g
-
first block
- h
-
second block
- v
-
the frequency variable
Attributes
- Returns
-
the combined transfer function, normalised to a single rational
Poles of G: the roots of its denominator.
Poles of G: the roots of its denominator.
Returns _Values rather than Doubles because a complex pole is the interesting case, not an error — an oscillatory mode is a conjugate pair, and reducing the result to reals would silently drop exactly the systems a control engineer cares about.
Value parameters
- g
-
the transfer function
- v
-
the frequency variable
Attributes
- Returns
-
the poles, or
NonewhenGis not rational invor the roots do not resolve
The root locus of G over gains (F_0140): the roots of den + K·num at each gain, as continuous branches, one per closed-loop pole.
The root locus of G over gains (F_0140): the roots of den + K·num at each gain, as continuous branches, one per closed-loop pole.
The matching is the substance. A root finder returns its roots in no particular order, and the order changes wherever two roots meet — at every breakaway point — so connecting the i-th root of one gain to the i-th of the next cross-connects the branches. Each gain's roots are therefore matched to the previous gain's by nearest continuation, the globally closest pair first. A gain where the degree drops (K = −denₙ/numₙ for a biproper plant) or the roots do not resolve is dropped from every branch at once — the point, never the axis (the F_0022 rule), or later points would pair with the wrong partners.
Value parameters
- g
-
the open-loop transfer function, proper and rational with numeric coefficients
- gains
-
the gains, in the order the branches should run
- v
-
the frequency variable
Attributes
- Returns
-
the branches, each a sequence of
(re, im)points, orNonefor an improper or non-rationalG, or when no gain resolved
The root-locus sweep behind the browser's rlocus command (F_0140): G with the environment's parameters substituted (never v), swept over points gains from kMin to kMax — geometric when kMin > 0, since a locus is read across decades of gain as a Bode plot is across decades of frequency, linear otherwise.
The root-locus sweep behind the browser's rlocus command (F_0140): G with the environment's parameters substituted (never v), swept over points gains from kMin to kMax — geometric when kMin > 0, since a locus is read across decades of gain as a Bode plot is across decades of frequency, linear otherwise.
Value parameters
- env
-
the bindings for
G's parameters - g
-
the open-loop transfer function
- kMax
-
the highest gain, above
kMin - kMin
-
the lowest gain
- points
-
how many gains, at least 2
- v
-
the frequency variable
Attributes
- Returns
-
the branches with the open-loop poles and zeros as
(re, im), orNone
The Routh array of G's denominator, for inspecting a stability margin by hand.
The Routh array of G's denominator, for inspecting a stability margin by hand.
Numeric coefficients only. isStable does not consult it — see the note there.
Value parameters
- g
-
the transfer function
- v
-
the frequency variable
Attributes
- Returns
-
the array, row by row from the highest power down, or
None
Series (cascade) connection: G * H.
Series (cascade) connection: G * H.
Value parameters
- g
-
first block
- h
-
second block
- v
-
the frequency variable
Attributes
- Returns
-
the combined transfer function, normalised to a single rational
Bundles (A, B, C, D) into the 1x4 row that represents a state-space model.
Bundles (A, B, C, D) into the 1x4 row that represents a state-space model.
Value parameters
- a
-
state matrix
- b
-
input matrix
- c
-
output matrix
- d
-
feedthrough matrix
Attributes
- Returns
-
the model as a
_Matrixnode
The steady-state target (x_s, u_s) for the setpoint r and the disturbance estimate d (F_0300): x_s = A·x_s + B·u_s + Bd·d and C·x_s + Cd·d = r.
The steady-state target (x_s, u_s) for the setpoint r and the disturbance estimate d (F_0300): x_s = A·x_s + B·u_s + Bd·d and C·x_s + Cd·d = r.
Solved directly when [[A − I, B], [C, 0]] is square and invertible and the answer lies within the input bounds; otherwise by optimize.qpSolve, minimising ‖C·x_s + Cd·d − r‖² under the steady state equation and the bounds, so the closest reachable target is returned, reached saying whether it meets the setpoint (each output to 0.5·10⁻ᵖ of its own terms).
Value parameters
- a
-
the state matrix,
n×n - b
-
the input matrix,
n×m - bd
-
the disturbance's entry into the state,
n×nd - c
-
the output matrix,
p×n - cd
-
the disturbance's entry into the output,
p×nd - d
-
the disturbance estimate,
ndentries - env
-
the precision and budgets
- r
-
the setpoint,
pentries - uBounds
-
(lower, upper)onu_s,mentries each, orNone
Attributes
- Returns
-
the target, or why there is none
Unit-step response L^-1{G(s)/s} — almost entirely a re-spelling of the inverse Laplace transform's repeated-pole machinery.
Unit-step response L^-1{G(s)/s} — almost entirely a re-spelling of the inverse Laplace transform's repeated-pole machinery.
Declines for an improper G (numerator degree above denominator degree). Such a response contains an impulsive term at t = 0 that the inverse-transform tier does not represent, so returning only the smooth part would be a confidently incomplete answer rather than a refusal.
Value parameters
- g
-
the transfer function
- s
-
the frequency variable
- t
-
the time variable, free in the result
Attributes
- Returns
-
the response, or _StepResponse unchanged when no rule applies
Concrete fields
The most multiply-adds dlsim runs, N·(n² + n·m + p·n + p·m), checked before any work.
The most multiply-adds dlsim runs, N·(n² + n·m + p·n + p·m), checked before any work.
Measured (2026-10-09) just under the cap, at 9.1–9.4·10⁷: 48–50 ms on the JVM and 250–320 ms on Node, the slowest platform (n = 100, N = 9000 and n = 300, N = 1000). The output and state cells, capped at matrix.MaxMatrixCells, bind first for most long simulations.
The default of core.Limit.MaxDlsimWork (F_0124): the dlsim overload taking core.Limits and the dlsim node read the caller's value.
Attributes
The longest prediction horizon accepted.
The longest prediction horizon accepted.
Np matrix products and Np running sums are computed, each over re-inflated cell grids. Measured (F_0055, JVM, warm): a ten-state single-input plant takes 44 ms at Np = 100 and 464 ms at Np = 1000, Nc = 10; MPC horizons are tens to hundreds of steps, so the cap refuses only a mistyped digit.
The default of core.Limit.MaxMpcHorizon (F_0124): mpcMatrices reads its environment's value.
Attributes
The largest state dimension the Riccati family solves (F_0065).
The largest state dimension the Riccati family solves (F_0065).
Measured (2026-10-11), dlqr on a random stabilisable plant with three inputs, JVM / Node: n = 50 48 / 104 ms, n = 100 130 / 357 ms, n = 200 452 ms / 2.5 s — a few n³ products per doubling step and about ten steps. Node is the slowest platform and sets the cap (the F_0077 rule); 2.5 s there matches lsqfit's and arx's caps.
The default of core.Limit.MaxRiccatiOrder (F_0124): dare, dlqr, dlyap and kalmanGain read their environment's value, kalmanStep its Limits overload's.