NonlinearGaussianTransition#

class hybrid_aif.NonlinearGaussianTransition[source]#

Bases: Module

x' = f(x, controls) + eps: a user-written mean map with conditioned innovations.

Under noise_scale="per_coordinate" the map also scales the innovations: f returns (mean, scale) and eps ~ N(loc_j, diag(s) chol_j chol_jᵀ diag(s)), s the scale at the previous state and the controls, so the process noise depends on both.

A state factor declaring this transition is Gaussian-carried, or mixture-carried when its prior is a MixtureGaussian or when it has discrete state parents. Discrete state parents in B_deps switch it, as they switch a LinearGaussianTransition: the mode reaches f as an integer level in the parent’s declared place among controls, and the innovations take one axis for it, so x' = f(x, (j, ...)) + eps_j. One f reads every mode (a per-mode table inside f, indexed by the level, writes one map per mode). The predicted next state is a mode-aligned mixture: each component is pushed through f once per joint mode, weighted by the mode’s belief, and reduced as the linear switching path reduces. Design: docs/design/nonlinear-transitions.md N1–N5, the amendment of 2026-11-13, and N4’s amendment of 2026-11-15 (switching).

f: Module#

An equinox.Module called as f(x, controls): x the state factor’s (d,) state, controls a tuple with one entry per parent in declared (B_deps) order: a discrete state parent’s integer mode level, a discrete control node’s integer level, a continuous node’s float vector (a factor with no state parent has control entries only, as before switching was built); it returns the (d,) mean of the next state, or under noise_scale="per_coordinate" the tuple (mean, scale) of two (d,) float arrays. A level may be traced (the propagation maps over the modes), so f indexes by it with array operations (table[level], jnp.take), not Python control flow. Its numeric fields are pytree leaves and its code is static structure. f is not learned.

innovations: ConditionalGaussian#

A ConditionalGaussian added to f’s output, eps ~ N(loc_j, chol_j chol_jᵀ), whose parent axes are the state factor’s discrete parents in declared (B_deps) order, its discrete state parents (the modes) and its discrete control nodes, the LinearGaussianTransition convention (the trivial (1,) for none); its Cholesky factor’s diagonal must be positive for beliefs to be propagated. Under noise_scale="per_coordinate" its Cholesky factor is diag(scale) chol_j and its offset loc_j is not scaled.

propagation: str = 'first_order'#

How a belief is pushed through f (static): "first_order" linearises f at the belief’s mean, "unscented" pushes 2n + 1 sigma points through it (n the state’s dimension plus that of any control carried as a belief). Both are exact for f affine in its continuous inputs and a scale that does not vary.

noise_scale: Literal['per_coordinate'] | None = None#

What f returns besides the mean (static): None, nothing (the mean alone); "per_coordinate", the pair (mean, scale), scale a (d,) vector, the innovations’ Cholesky factor taken as diag(scale) chol. Validation checks the map’s return against it; no code path reads the return’s structure instead.

The scale must be strictly positive and finite (a softplus or an exponential, say); it is not checked under jit. A zero on a coordinate whose mean has no spread makes the predicted covariance singular, and its Cholesky factor NaN; a negative entry flips the sign of that coordinate’s correlations. For the gradient planner and any gradient through a belief, the scale must also be differentiable wherever it is evaluated, the unscented centre point included (its zero weight does not cancel a NaN). A scale such as sqrt(1 - rho(d)**2) with rho(0) = 1 has an infinite or NaN derivative at d = 0 (zero displacement, a vehicle at rest), and the gradient planner then returns a NaN plan from a start at rest; guard it as sqrt(1 - rho**2 + eps), or with a double where that keeps the root’s argument away from zero on the branch not taken.

noise_prior: InverseGamma | InverseWishart | Parameter | None = None#

A conjugate prior over the innovations’ covariance, or Parameter(name): the LinearGaussianTransition field of the same name. Under noise_scale="per_coordinate" it is a prior over the unscaled chol_j cholᵀ_j. Learned at first order (f linearised at the previous mean); the unscented rule is refused by learn. Design: process-noise-learning.md D1, D2.

property learnable_noise: bool#

Capability, per-field: the process noise is a posterior (noise_prior holds one).

__init__(
f,
innovations,
propagation='first_order',
noise_scale=None,
noise_prior=None,
)#