NonlinearGaussianTransition#
- class hybrid_aif.NonlinearGaussianTransition[source]#
Bases:
Modulex' = f(x, controls) + eps: a user-written mean map with conditioned innovations.Under
noise_scale="per_coordinate"the map also scales the innovations:freturns(mean, scale)andeps ~ N(loc_j, diag(s) chol_j chol_jᵀ diag(s)),sthe 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
MixtureGaussianor when it has discrete state parents. Discrete state parents inB_depsswitch it, as they switch aLinearGaussianTransition: the mode reachesfas an integer level in the parent’s declared place amongcontrols, and the innovations take one axis for it, sox' = f(x, (j, ...)) + eps_j. Onefreads every mode (a per-mode table insidef, indexed by the level, writes one map per mode). The predicted next state is a mode-aligned mixture: each component is pushed throughfonce 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.Modulecalled asf(x, controls):xthe state factor’s(d,)state,controlsa 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 undernoise_scale="per_coordinate"the tuple(mean, scale)of two(d,)float arrays. A level may be traced (the propagation maps over the modes), sofindexes 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.fis not learned.
- innovations: ConditionalGaussian#
A
ConditionalGaussianadded tof’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, theLinearGaussianTransitionconvention (the trivial(1,)for none); its Cholesky factor’s diagonal must be positive for beliefs to be propagated. Undernoise_scale="per_coordinate"its Cholesky factor isdiag(scale) chol_jand its offsetloc_jis not scaled.
- propagation: str = 'first_order'#
How a belief is pushed through
f(static):"first_order"linearisesfat the belief’s mean,"unscented"pushes2n + 1sigma points through it (nthe state’s dimension plus that of any control carried as a belief). Both are exact forfaffine in its continuous inputs and a scale that does not vary.
- noise_scale: Literal['per_coordinate'] | None = None#
What
freturns besides the mean (static):None, nothing (the mean alone);"per_coordinate", the pair(mean, scale),scalea(d,)vector, the innovations’ Cholesky factor taken asdiag(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 assqrt(1 - rho(d)**2)withrho(0) = 1has an infinite or NaN derivative atd = 0(zero displacement, a vehicle at rest), and the gradient planner then returns a NaN plan from a start at rest; guard it assqrt(1 - rho**2 + eps), or with a doublewherethat 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): theLinearGaussianTransitionfield of the same name. Undernoise_scale="per_coordinate"it is a prior over the unscaledchol_j cholᵀ_j. Learned at first order (flinearised at the previous mean); the unscented rule is refused bylearn. Design: process-noise-learning.md D1, D2.
- property learnable_noise: bool#
Capability, per-field: the process noise is a posterior (
noise_priorholds one).
- __init__(
- f,
- innovations,
- propagation='first_order',
- noise_scale=None,
- noise_prior=None,