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 Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
enum ArxFailure

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 Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ArxMimoModel(a: Vector[_MatrixValue], b: Vector[_MatrixValue])

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 na autoregressive blocks A₁ … A_na, each p×p; empty for a finite impulse response

b

the nb input blocks B₁ … B_nb, each p×m, applied from lag nk on

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ArxModel(a: Vector[Double], b: Vector[Vector[Double]])

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 na autoregressive coefficients, a₁ first; empty for a finite impulse response

b

per input j, its nb coefficients b₁ⱼ … b_nb,j, applied from lag nk on

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ArxOrderScore(na: Int, nb: Int, nk: Int, score: Double)

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 Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ArxOrderSelection(na: Int, nb: Int, nk: Int, model: ArxMimoModel, scores: Vector[ArxOrderScore], skipped: Vector[(Int, Int, Int, ArxFailure)])

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 Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ArxPredictionError(rms: Vector[Double], residuals: _MatrixValue, from: Int)

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): row r holds output r's residual y − ŷ at k = from … N − 1

rms

the root mean square of each output's residual over the scored samples

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show 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

Companion
object
Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
trait Keyworded
class Object
trait Matchable
class Any
Show all

Attributes

Companion
enum
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class DisturbanceModel(a: _MatrixValue, b: _MatrixValue, c: _MatrixValue, n: Int, nd: Int)

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 Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show 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 Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show 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 Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class MinimalRealisation(a: _MatrixValue, b: _MatrixValue, c: _MatrixValue, d: _MatrixValue, order: Int)

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 Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all

Why minreal declined (F_0307).

Why minreal declined (F_0307).

Attributes

Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show 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 parameter C·Aⁱ⁻ˡ·B on and below the diagonal and zero above

phi

Φ, as in MpcPrediction

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class MpcBounds(u: Option[(Vector[Double], Vector[Double])] = ..., du: Option[(Vector[Double], Vector[Double])] = ..., y: Option[(Vector[Double], Vector[Double])] = ..., soft: Option[MpcSoftOutputs] = ...)

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 against u(k−1)

soft

relaxes the output bounds through slacks; None keeps them hard

u

the inputs u(k+j)

y

the predicted outputs y(k+1) … y(k+Np)

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
enum MpcFailure

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 Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show 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 block i the accumulated Markov sum Σ_{j ≤ i} C·Aʲ·B

theta

Θ, (Np·p)×(Nc·m), its block (i, l) the sum Σ_{j ≤ i−l} C·Aʲ·B below the diagonal and zero above

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class MpcPositionTarget(weight: Vector[_MatrixValue], target: Vector[Double])

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: m entries held, or Nc·m stacked

weight

S: one m×m for every step, or Nc of them

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class MpcPrediction(phi: _MatrixValue, gamma: _MatrixValue) extends MpcPredictionMatrices

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, stacking C·Aⁱ for i = 1 … Np

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
sealed trait MpcPredictionMatrices

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 Object
trait Matchable
class Any
Known subtypes
final case class MpcQp(h: _MatrixValue, f: Vector[Double], ineq: Option[(_MatrixValue, Vector[Double])], lb: Vector[Double], ub: Vector[Double], m: Int, nc: Int, incremental: Boolean, uPrev: Vector[Double])

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 z holds 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 Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class MpcSoftOutputs(linear: Vector[Double], quadratic: Vector[Double])

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 Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class MpcSolution(moves: Vector[Vector[Double]], input: Vector[Double], slacks: Vector[Double], qp: QpResult)

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, Nc vectors of m: the inputs for an absolute prediction, the increments for an incremental or an accumulated one

qp

the certified QP optimum, whose active set warm-starts the next step

slacks

the output slacks, empty when the outputs are not softened

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class MpcTerminal(weight: _MatrixValue, prediction: MpcPredictionMatrices, target: Option[Vector[Double]] = ...)

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, n entries; None for the origin

weight

P, n×n

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class MpcWeights(q: Vector[_MatrixValue], r: Vector[_MatrixValue], terminal: Option[MpcTerminal] = ..., inputTarget: Option[Vector[Double]] = ..., positionTarget: Option[MpcPositionTarget] = ...)

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): m entries held, or Nc·m stacked, the move cost becoming ‖u − u_s‖²_R; None for u_s = 0. Without it the absolute form's R pulls 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: see positionTarget

positionTarget

the increment forms' cost on the input itself (F_0329), or None. Not accepted with an absolute prediction, where inputTarget with r is that cost

q

the output weights: one p×p for every step, or Np of them, step by step

r

the move weights: one m×m for every move, or Nc of them

terminal

the terminal cost, or None

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show 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 Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
enum RiccatiKind extends Keyworded

Which Riccati-family function a _Riccati node is.

Which Riccati-family function a _Riccati node is.

Attributes

Companion
object
Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
trait Keyworded
class Object
trait Matchable
class Any
Show all
object RiccatiKind

Attributes

Companion
enum
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
enum SimFailure

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 Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class SteadyStateTarget(x: Vector[Double], u: Vector[Double], reached: Boolean)

The steady-state target (F_0300).

The steady-state target (F_0300).

Value parameters

reached

whether the outputs reach the setpoint there; false when the input bounds or the shape leave only the closest reachable target

u

u_s

x

x_s

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
enum StructureKind(val word: String) extends Keyworded

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 Enum
trait Serializable
trait Product
trait Equals
trait Keyworded
class Object
trait Matchable
class Any
Show all
case class _Acker(a: _Expression, b: _Expression, poles: _Expression) extends _Expression

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 Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _Arx(u: _Expression, y: _Expression, na: _Expression, nb: _Expression, nk: _Expression) extends _Expression

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 Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _Arx2Ss(a: _Expression, b: _Expression, nk: _Expression) extends _Expression

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 0 for none

b

the nb×m input coefficients

nk

the input delay

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _Arx2Tf(a: _Expression, b: _Expression, nk: _Expression, z: _Variable) extends _Expression

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 0 for none

b

the nb×m input coefficients

nk

the input delay

z

the discrete frequency variable

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show 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 Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _C2d(g: _Expression, s: _Variable, z: _Variable, ts: _Expression, method: DiscretisationMethod, prewarp: Option[_Expression] = ...) extends _Expression

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 Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _Dlsim(sys: _Expression, u: _Expression, x0: _Expression, states: Boolean = ...) extends _Expression

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 Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _Feedback(g: _Expression, h: _Expression, v: _Variable) extends _Expression

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 Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all

Impulse response: impulse(G, s, t) = L^-1{G(s)}.

Impulse response: impulse(G, s, t) = L^-1{G(s)}.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _IsStable(g: _Expression, v: _Variable, discrete: Boolean = ...) extends _Expression

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 Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _Linearize(f: _Expression, g: _Expression, x: Vector[_Variable], u: Vector[_Variable], x0: _Expression, u0: _Expression, affine: Boolean = ...) extends _Expression

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 Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show 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 Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _Parallel(g: _Expression, h: _Expression, v: _Variable) extends _Expression

Parallel connection: parallel(G, H, v).

Parallel connection: parallel(G, H, v).

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _Riccati(kind: RiccatiKind, args: List[_Expression]) extends _Expression

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 Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _Routh(g: _Expression, v: _Variable) extends _Expression

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 Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _Series(g: _Expression, h: _Expression, v: _Variable) extends _Expression

Series connection: series(G, H, v).

Series connection: series(G, H, v).

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _StepResponse(g: _Expression, s: _Variable, t: _Variable) extends _Expression

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 Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _Structure(kind: StructureKind, a: _Expression, x: Option[_Expression]) extends _Expression

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 x is absent

kind

the question

x

the input matrix B or the output matrix C

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _TfPoles(g: _Expression, v: _Variable) extends _Expression

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 _Series convention)

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _TfZeros(g: _Expression, v: _Variable) extends _Expression

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 Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all

Value members

Concrete methods

def acker(a: _MatrixValue, b: _MatrixValue, poles: Vector[(Double, Double)]): Option[_MatrixValue]

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, n of them, closed under conjugation

Attributes

Returns

K as a 1×n row, or None for a multi-input or uncontrollable plant, poles not closed under conjugation or not n of them, or a gain that fails the certificate

def arx(u: _MatrixValue, y: _MatrixValue, na: Int, nb: Int, nk: Int, env: Environment): Either[ArxFailure, ArxModel]

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×N or N×m

y

the output, 1×N or N×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ᵤ + p states, or the reason

def arx2ss(a: Vector[Double], b: Vector[Vector[Double]], nk: Int): Either[ArxFailure, (_MatrixValue, _MatrixValue, _MatrixValue, _MatrixValue)]

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 nb coefficients

nk

the input delay

Attributes

Returns

(A, B, C, D), or the reason — ArxFailure.NoState for a static gain

def arx2tf(a: Vector[Double], b: Vector[Vector[Double]], nk: Int, z: _Variable): Either[ArxFailure, Vector[_Expression]]

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 nb coefficients

nk

the input delay

z

the discrete frequency variable to write the result in

Attributes

Returns

one rational in z per input, or the reason the model is malformed

def arxMimo(u: _MatrixValue, y: _MatrixValue, na: Int, nb: Int, nk: Int, env: Environment): Either[ArxFailure, ArxMimoModel]

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×N or N×m

y

the outputs, p×N or N×p

Attributes

Returns

the model, or the reason it was declined

def arxOrderSelection(u: _MatrixValue, y: _MatrixValue, nas: Seq[Int], nbs: Seq[Int], nks: Seq[Int], criterion: ArxCriterion, validation: Option[(_MatrixValue, _MatrixValue)], env: Environment): Either[ArxFailure, ArxOrderSelection]

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×N or N×m

validation

validation inputs and outputs in the same layout, or None

y

the outputs, p×N or N×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×N or N×m

y

the outputs, p×N or N×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

def arxRegressors(u: _MatrixValue, y: _MatrixValue, na: Int, nb: Int, nk: Int): Either[ArxFailure, (_MatrixValue, _MatrixValue)]

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 = 0 is direct feedthrough

u

the inputs

y

the outputs

Attributes

Returns

(X, Y), Y with 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×N or N×m

y

the outputs, p×N or N×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

def bode(g: _Expression, v: _Variable, w: Double): Option[(Double, Double)]

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), or None where the response is not finite (evaluating an integrator at w = 0, say) — never a fabricated infinity

def c2d(g: _Expression, s: _Variable, z: _Variable, ts: Double, method: DiscretisationMethod): Option[_Expression]

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 None when the conversion does not close

def c2dExact(a: _Expression, b: _Expression, ts: Double): Option[(_MatrixValue, _MatrixValue)]

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), or None when the operands are not conforming dense matrices

def c2dPrewarped(g: _Expression, s: _Variable, z: _Variable, ts: Double, w: Double): Option[_Expression]

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

def controllable(a: _Expression, b: _Expression): Option[Boolean]

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), or None when either operand is not a dense matrix

def d2c(g: _Expression, z: _Variable, s: _Variable, ts: Double, method: DiscretisationMethod): Option[_Expression]

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 g was 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

def d2cPrewarped(g: _Expression, z: _Variable, s: _Variable, ts: Double, w: Double): Option[_Expression]

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‖, against 0.5·10⁻ᵖ;
  • the closed loop A − B·K with 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

def dcgain(g: _Expression, v: _Variable): Option[Double]

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), or None when 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 — column k is u[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

def frequencyResponse(g: _Expression, v: _Variable, wMin: Double, wMax: Double, points: Int, env: Environment): Vector[(Double, Double, Double)]

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

def isStable(g: _Expression, v: _Variable): Option[Boolean]

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), or None when the poles cannot be determined

def isStableDiscrete(g: _Expression, v: _Variable): Option[Boolean]

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), or None when 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, n rows, 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

def mpcMatrices(a: _Expression, b: _Expression, c: _Expression, np: Int, nc: Int, env: Environment): Option[(_Expression, _Expression)]

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's Limit.MaxMpcHorizon

Attributes

Returns

(Φ, Γ) as evaluated matrices, or None when the plant does not conform, a horizon is out of range, an operand's shape is unknown, or a result would exceed the environment's Limit.MaxMatrixCells

def mpcPrediction(a: _MatrixValue, b: _MatrixValue, c: _MatrixValue, np: Int, nc: Int, limits: Limits): Either[MpcFailure, MpcPrediction]

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

def mpcQp(prediction: MpcPredictionMatrices, q: _MatrixValue, r: _MatrixValue, reference: Vector[Double], x: Vector[Double], uPrev: Vector[Double], bounds: MpcBounds, limits: Limits): Either[MpcFailure, MpcQp]

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: p entries held over the horizon, or Np·p stacked

uPrev

u(k−1), m entries

x

the current state, n entries

Attributes

Returns

the programme, or why it cannot be built

def mpcTerminalPrediction(a: _MatrixValue, b: _MatrixValue, np: Int, nc: Int, incremental: Boolean, limits: Limits): Either[MpcFailure, MpcPredictionMatrices]

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, n rows, or why not

def nyquist(g: _Expression, v: _Variable, w: Double): Option[(Double, Double)]

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), or None where the response is not finite

def nyquistSweep(g: _Expression, v: _Variable, wMin: Double, wMax: Double, points: Int, env: Environment): Vector[(Double, Double)]

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

def observable(a: _Expression, c: _Expression): Option[Boolean]

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), or None when 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

def poles(g: _Expression, v: _Variable): Option[Vector[_Value]]

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 None when G is not rational in v or the roots do not resolve

def rootLocus(g: _Expression, v: _Variable, gains: Vector[Double]): Option[Vector[Vector[(Double, Double)]]]

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, or None for an improper or non-rational G, or when no gain resolved

def rootLocusSweep(g: _Expression, v: _Variable, kMin: Double, kMax: Double, points: Int, env: Environment): Option[(Vector[Vector[(Double, Double)]], Vector[(Double, Double)], Vector[(Double, Double)])]

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), or None

def routhTable(g: _Expression, v: _Variable): Option[Vector[Vector[Double]]]

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 _Matrix node

def steadyStateTarget(a: _MatrixValue, b: _MatrixValue, c: _MatrixValue, bd: _MatrixValue, cd: _MatrixValue, r: Vector[Double], d: Vector[Double], uBounds: Option[(Vector[Double], Vector[Double])], env: Environment): Either[MpcFailure, SteadyStateTarget]

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, nd entries

env

the precision and budgets

r

the setpoint, p entries

uBounds

(lower, upper) on u_s, m entries each, or None

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

def zeros(g: _Expression, v: _Variable): Option[Vector[_Value]]

Zeros of G: the roots of its numerator. See poles for the _Value result type.

Zeros of G: the roots of its numerator. See poles for the _Value result type.

Value parameters

g

the transfer function

v

the frequency variable

Attributes

Returns

the zeros, or None when G is not rational in v

Concrete fields

val MaxDlsimWork: Long

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

val MaxMpcHorizon: Int

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

val MaxRiccatiOrder: Int

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.

Attributes