it.grypho.scala.leonardo.ode

Members list

Type members

Classlikes

enum OdeFailure

Why the vector tier declined (F_0052 Decision A: a reason at the Scala level, which the REPL appends as a note). The node stays symbolic; this explains it.

Why the vector tier declined (F_0052 Decision A: a reason at the Scala level, which the REPL appends as a note). The node stays symbolic; this explains it.

Attributes

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

Attributes

Companion
enum
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
OdeMethod.type
enum OdeMethod extends Keyworded

The integration methods of the vector tier, always named by the caller (F_0051).

The integration methods of the vector tier, always named by the caller (F_0051).

Never a hidden default, the c2d / minimize rule: two methods give different answers at the same step, so a silent choice would make two correct-looking results disagree.

Attributes

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

Attributes

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

How a system's state is named (F_0051 Decision A).

How a system's state is named (F_0051 Decision A).

Attributes

Companion
object
Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class _ODE(rhs: _Expression, depVar: _Variable, indepVar: _Variable, t0: _Expression, y0: _Expression, target: _Expression) extends _Functional

Symbolic node for the solution value of a first-order initial-value problem.

Symbolic node for the solution value of a first-order initial-value problem.

Represents y(target) where y satisfies y' = rhs(t, y), y(t0) = y0.

Both depVar (the dependent variable y) and indepVar (the independent variable t) are binders: they are excluded from children so that substitute and dependsOn never recurse into them, matching the convention of scalar._Derivative and scalar._Limit. The expression positions rhs, t0, y0, and target are ordinary children and may hold free variables (e.g. a symbolic target keeps the result closed-form).

Evaluation strategy (four tiers, in order):

  1. Linear system via solveODESystem (F_0006): when y0 evaluates to an n×1 column and rhs is A*y or A*y + b with a constant square matrix A, the answer is e^(A*tau)*y0 (plus the input term) by the augmented matrix exponential. Tried first so a vector problem never reaches the scalar collect. Numeric only.
  2. Closed-form via solveODESymbolic: handles y' = a*y + b for a scalar coefficient (constant or, via the integrating factor, time-varying) and the separable shapes; returns a symbolic expression that stays closed-form when t0/y0/target are free. It declines a matrix coefficient, which is tier 1's.
  3. Numeric RK4 via solveODE: folds t0/y0/target to concrete _Numbers and runs the integrator; returns Right(_Number(result)).
  4. Vector RK4 (F_0051) via odeCertified, when y0 is a column and tiers 1–2 declined — a time-varying A(t)*y, or a nonlinear system written through at(y, i, 1): depVar is bound to the whole column, and the answer is certified by step doubling. The column-of-names spelling builds _ODESystem instead. When none applies, eval returns Left(this) — the fixpoint convention shared with the transform nodes and the scalar._Functional hierarchy.

Round-trip: toString emits ode(rhs, depVar, indepVar, t0, y0, target), which re-parses to an equivalent node.

Value parameters

depVar

the dependent variable (the unknown function, e.g. y)

indepVar

the independent variable (what y is differentiated against, e.g. t)

rhs

the right-hand side f(t, y) of the ODE

t0

the initial time point

target

the point at which the solution is evaluated

y0

the initial value y(t0)

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class _Functional
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _ODESystem(rhs: _Expression, states: Vector[_Variable], indepVar: _Variable, t0: _Expression, y0: _Expression, target: _Expression) extends _Expression

ode(rhs, [[x], [v]], t, t0, y0, target) — a system whose state is written as a column of names (F_0051 Decision A), each bound to its component, so [[v], [-x]] reads as written.

ode(rhs, [[x], [v]], t, t0, y0, target) — a system whose state is written as a column of names (F_0051 Decision A), each bound to its component, so [[v], [-x]] reads as written.

A separate node rather than a widened _ODE: _ODE is a published case class whose depVar is one _Variable, and changing that field's type would be a binary break for a spelling. The single-name form still builds _ODE, unchanged.

Integrated by odeCertified: RK4 at the scalar tier's step count, answered only when n and 2n steps agree within the tolerance = uses (Decision B), relative to the run's largest state component (F_0211). The names are binders — excluded from children, carried through rebuild.

Value parameters

indepVar

the independent variable

rhs

the right-hand side, an n×1 column in the state names and indepVar

states

the state names, in the order of y0

t0

the initial time

target

the time the state is wanted at

y0

the initial state, an n×1 column

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _OdeSolve(rhs: _Expression, state: OdeState, indepVar: _Variable, t0: _Expression, y0: _Expression, t1: _Expression, h: _Expression, method: OdeMethod) extends _Expression

odeSolve(F, y, t, t0, y0, t1, h, method) — the trajectory from t0 to t1 as a matrix, one row per output time with t in the first column then the state (F_0051 Decision D).

odeSolve(F, y, t, t0, y0, t1, h, method) — the trajectory from t0 to t1 as a matrix, one row per output time with t in the first column then the state (F_0051 Decision D).

Value parameters

h

the output spacing (and the step, for euler/rk4)

indepVar

the independent variable

method

the method, always named

rhs

the right-hand side

state

how the state is named

t0

the initial time

t1

the final time, which is always a row

y0

the initial state, an n×1 column

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all
case class _OdeStep(rhs: _Expression, state: OdeState, indepVar: _Variable, t0: _Expression, y0: _Expression, h: _Expression, method: OdeMethod) extends _Expression

odeStep(F, y, t, t0, y0, h, method) — the state one step of method after t0 (F_0051, MPC requirement T1-04). y is a name (bound to the whole column) or a column of names. For euler/rk4 exactly one step of size h, uncertified, since the step is the caller's; for rk45, the state at t0 + h by adaptive steps. Names bound in the environment — a controller's inputs — are constants during the step.

odeStep(F, y, t, t0, y0, h, method) — the state one step of method after t0 (F_0051, MPC requirement T1-04). y is a name (bound to the whole column) or a column of names. For euler/rk4 exactly one step of size h, uncertified, since the step is the caller's; for rk45, the state at t0 + h by adaptive steps. Names bound in the environment — a controller's inputs — are constants during the step.

Value parameters

h

the step (or the interval, for rk45)

indepVar

the independent variable

method

the method, always named

rhs

the right-hand side

state

how the state is named

t0

the time of the current state

y0

the current state, an n×1 column

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait _Expression
class Object
trait Matchable
class Any
Show all

Value members

Concrete methods

def odeCertified(rhs: _Expression, state: OdeState, indepVar: _Variable, t0: Double, y0: Vector[Double], target: Double, env: Environment): Either[OdeFailure, Vector[Double]]

ode's automatic vector integration (F_0051 steps 2 and Decision B): RK4 with the scalar tier's stepCount, certified by step doubling — the problem is integrated with n and 2n steps, and answered (the finer result) only when the two agree within the tolerance = uses relative to the run's largest state component (F_0211 Decision 1: it was absolute, which is a claim about the state's units). A stiff or under-resolved problem then declines instead of returning a finite, confident and wrong number. The certificate triples the work (n + 2n steps): measured 121 ms for the oscillator over 2π and 214 ms for Lotka–Volterra over 5 (JVM), while a stiff y' = -10⁶(y - cos t) declines in 7 ms, its state going non-finite.

ode's automatic vector integration (F_0051 steps 2 and Decision B): RK4 with the scalar tier's stepCount, certified by step doubling — the problem is integrated with n and 2n steps, and answered (the finer result) only when the two agree within the tolerance = uses relative to the run's largest state component (F_0211 Decision 1: it was absolute, which is a claim about the state's units). A stiff or under-resolved problem then declines instead of returning a finite, confident and wrong number. The certificate triples the work (n + 2n steps): measured 121 ms for the oscillator over 2π and 214 ms for Lotka–Volterra over 5 (JVM), while a stiff y' = -10⁶(y - cos t) declines in 7 ms, its state going non-finite.

Attributes

Returns

the state at target, or why it was not certified

def odeSolve(rhs: _Expression, state: OdeState, indepVar: _Variable, t0: Double, y0: Vector[Double], t1: Double, h: Double, method: OdeMethod, env: Environment): Either[OdeFailure, Vector[(Double, Vector[Double])]]

The trajectory from t0 to t1 at output spacing h (F_0051's odeSolve).

The trajectory from t0 to t1 at output spacing h (F_0051's odeSolve).

One row per output time, t first: t0, t0 + h, … and t1 itself, the last interval cut short when h does not divide the span. Each interval is one step of euler/rk4, or adaptive rk45 steps landing exactly on the output time.

Attributes

Returns

the rows (t, state), or why they were not computed

def odeStep(rhs: _Expression, state: OdeState, indepVar: _Variable, t0: Double, y0: Vector[Double], h: Double, method: OdeMethod, env: Environment): Either[OdeFailure, Vector[Double]]

One step of method from (t0, y0) over h (F_0051's odeStep).

One step of method from (t0, y0) over h (F_0051's odeStep).

For euler and rk4 this is exactly one step of size h, uncertified — the step is the caller's choice, and a fixed step is what a controller simulation wants. For rk45, h is the interval: the state at t0 + h, reached by as many adaptive steps as the tolerance needs.

Attributes

Returns

the state at t0 + h, or why it was not computed

def solveODE(rhs: _Expression, depVar: _Variable, indepVar: _Variable, t0: Double, y0: Double, target: Double, env: Environment): Option[Double]

Integrates y' = rhs(t, y), y(t0) = y0 to y(target) via RK4.

Integrates y' = rhs(t, y), y(t0) = y0 to y(target) via RK4.

Value parameters

depVar

the dependent variable name (bound to the current y at each stage)

env

the evaluation environment (provides precision and other bindings)

indepVar

the independent variable name (bound to the current t at each stage)

rhs

the right-hand side f(t, y) as a symbolic expression

t0

the initial time

target

the time at which the solution is requested

y0

the initial value y(t0)

Attributes

Returns

Some(y(target)) on success; None if any stage is non-numeric or non-finite

def solveODESymbolic(rhs: _Expression, depVar: _Variable, indepVar: _Variable, t0: _Expression, y0: _Expression, target: _Expression, env: Environment): Option[_Expression]

Closed-form tier for linear first-order IVPs y' = a(t)*y + b(t).

Closed-form tier for linear first-order IVPs y' = a(t)*y + b(t).

The right-hand side must be linear in the dependent variable (collect(rhs, depVar) yields at most a degree-1 coefficient vector [b, a]); non-linear shapes such as sin(y) or y^2 return None (the caller falls back to RK4).

Two sub-tiers:

  1. Constant coefficients (a, b free of the independent variable t) — the exact tau = target - t0 forms, avoiding any substitution:

    • y' = a*y (b = 0): y = y0 * exp(a*tau)
    • y' = b (a = 0): y = y0 + b*tau
    • y' = a*y + b (general): y = (y0 + b/a) * exp(a*tau) - b/a
  2. Variable coefficients (a or b depends on t) — the integrating-factor method. With A = integral(a dt) and mu = exp(-A) the equation (mu*y)' = mu*b integrates to mu*y = Q + C, Q = integral(mu*b dt); the initial condition fixes C = mu(t0)*y0 - Q(t0), giving

   y(target) = (Q(target) - Q(t0) + y0*mu(t0)) / mu(target)

This closes whenever both integral(a dt) and integral(mu*b dt) reduce to a closed form (it reuses the full indefinite-integration engine, so e.g. mu*b = t*e^t is handled by integration by parts); if either stays symbolic, this tier returns None and the caller falls back to RK4.

In both tiers the result stays symbolic when target, y0, t0, or a coefficient is free, and folds to a _Number once everything is concrete.

Value parameters

depVar

the dependent variable (y)

env

the evaluation environment

indepVar

the independent variable (t)

rhs

the right-hand side of the ODE y' = rhs

t0

the initial time (may be symbolic)

target

the evaluation point (may be symbolic)

y0

the initial value (may be symbolic)

Attributes

Returns

Some(closed-form expression for y(target)), or None if not recognised

def solveODESystem(rhs: _Expression, depVar: _Variable, indepVar: _Variable, t0: _Expression, y0: _Expression, target: _Expression, env: Environment): Option[_MatrixValue]

Closed-form tier for a constant-coefficient linear system y' = A·y + b, y(t0) = y0.

Closed-form tier for a constant-coefficient linear system y' = A·y + b, y(t0) = y0.

y is an n×1 column, A a square n×n matrix and b an n×1 column, both constant. The solution is the augmented matrix exponential

exp([[A, b], [0, 0]]·τ) = [[Φ, Γ], [0, 1]],   y(target) = Φ·y0 + Γ,   τ = target − t0

computed by core._MatrixValue.augmentedExp, the kernel control.c2dExact also uses, so the two agree by construction (F_0006). The homogeneous y' = A·y is the b = 0 case.

The vector-ness is read from y0, the one operand that must be a vector: the tier runs only when y0 evaluates to a column, so a scalar problem never reaches it, and the _ODE node, its binders and its toString need no change.

Recognition is structural and accepts A·y, A·y + b and b + A·y (A·y − b is A·y + (−1)·b). A product is either the scalar Product — what a coefficient bound to a matrix builds — or a node carrying core._MatrixProductShaped, which is what a literal matrix builds; sums likewise through core._MatrixSumShaped. The core traits are what keep ode free of a matrix import.

Declines, returning None so the caller falls through (a vector problem reaches F_0051's certified RK4, odeCertified): a time-varying A(t) or b(t) (no closed form in general — it needs the Magnus series), a coefficient that is not a square dense matrix (a scalar coefficient is left to the scalar tier, which is correct for it), any non-conforming b or y0, and a τ that does not fold to a number, since core._MatrixValue.expm is a numeric kernel. Backward time needs nothing special: e^(Aτ) is defined for either sign. An exact operand demotes to Double, the lu/qr/expm precedent.

Value parameters

depVar

the dependent variable (y)

env

the evaluation environment

indepVar

the independent variable (t)

rhs

the right-hand side of y' = rhs

t0

the initial time

target

the evaluation point

y0

the initial state, an n×1 column

Attributes

Returns

Some(y(target)) as an n×1 matrix, or None when the problem is not such a system

Concrete fields

val MaxOdeSteps: Int

The most steps one integration may take, fixed or adaptive. The scalar RK4's own ceiling too, so the two tiers cannot run away differently. The default of core.Limit.MaxOdeSteps (F_0124): every tier reads its environment's value.

The most steps one integration may take, fixed or adaptive. The scalar RK4's own ceiling too, so the two tiers cannot run away differently. The default of core.Limit.MaxOdeSteps (F_0124): every tier reads its environment's value.

Attributes

The most rows odeSolve materialises. The Session.MaxSampleCount rule: the trajectory is built in full before it is returned, so an uncapped h is an out-of-memory error rather than a refusal. Measured (F_0051, JVM): 99,991 rows of a two-state RK4 trajectory take 0.38 s, and one row past the cap is refused before any work. The default of core.Limit.MaxTrajectoryRows (F_0124).

The most rows odeSolve materialises. The Session.MaxSampleCount rule: the trajectory is built in full before it is returned, so an uncapped h is an out-of-memory error rather than a refusal. Measured (F_0051, JVM): 99,991 rows of a two-state RK4 trajectory take 0.38 s, and one row past the cap is refused before any work. The default of core.Limit.MaxTrajectoryRows (F_0124).

Attributes