Skip to content

Dynamics noise

State-dependent dynamics noise Q(x): the world can diffuse more in some states than others. A constant Q needs no object. It goes in the model's dynamics_noise. DynamicsNoiseModel is the protocol for a Q(x) in dynamics_noise_model, the twin of ObservationModel on the sensor side, and a plain matrix does not satisfy it. CallableDynamicsNoise carries the Q(x) function, with the same two arguments as CallableSensor.

DynamicsNoiseModel

Bases: Protocol

How much the dynamics diffuse per step, as a covariance Q(x) at each state.

The model's dynamics_noise_model slot takes one, as observation_model takes an ObservationModel. A constant Q needs no object. It goes in dynamics_noise, and a plain matrix does not satisfy this protocol. A state-dependent Q(x) brings epistemic value back through the internal route (RFC-001 chapter 8).

is_fixed property

is_fixed: bool

True when Q does not vary with the state.

The filter then keeps its fixed path and reads the model's dynamics_noise, which equals this object's Q.

noise_at

noise_at(state: ArrayLike) -> Float64[Array, 'n n']

The dynamics-noise covariance Q at state.

Source code in src/cpomdp/dynamics.py
def noise_at(self, state: ArrayLike, /) -> Float64[Array, "n n"]:
    """The dynamics-noise covariance ``Q`` at ``state``."""
    ...

CallableDynamicsNoise dataclass

CallableDynamicsNoise(
    noise_fn: Callable[
        [Float64[Array, n], PyTree], Float64[Array, "n n"]
    ],
    noise_params: PyTree,
)

State-dependent dynamics noise, Q(state) = noise_fn(state, noise_params).

The dynamics-side twin of CallableSensor, with the same two arguments. noise_fn holds the functional form. It is static aux, since a callable cannot be a traced leaf. noise_params holds the values it is a function of, as a pytree leaf, so the EFE is differentiable with respect to them. A number belongs in noise_params if it might ever be fitted, and is baked into noise_fn only if it is structural. Pass a module-level noise_fn. A closure or lambda hashes by identity and defeats jit caching.

noise_fn must return a positive-semi-definite (n, n) covariance at every reachable state. The model probes it once at construction, where n is known.

Attributes:

Name Type Description
noise_fn Callable[[Float64[Array, n], PyTree], Float64[Array, 'n n']]

(state, noise_params) -> Q, the covariance at one state.

noise_params PyTree

the pytree of values noise_fn reads.

Source code in src/cpomdp/dynamics.py
def __init__(
    self,
    noise_fn: Callable[[Float64[Array, "n"], PyTree], Float64[Array, "n n"]],
    noise_params: PyTree,
) -> None:
    object.__setattr__(self, "noise_fn", noise_fn)
    object.__setattr__(self, "noise_params", noise_params)
    self._validate()

noise_at

noise_at(state: ArrayLike) -> Float64[Array, 'n n']

Q at state, which is read as a float array first.

Source code in src/cpomdp/dynamics.py
def noise_at(self, state: ArrayLike, /) -> Float64[Array, "n n"]:
    """``Q`` at ``state``, which is read as a float array first."""
    return self.noise_fn(jnp.asarray(state, dtype=float), self.noise_params)

tree_flatten

tree_flatten() -> tuple[tuple[PyTree], Callable]

Traced children (noise_params,); aux noise_fn.

Source code in src/cpomdp/dynamics.py
def tree_flatten(self) -> tuple[tuple[PyTree], Callable]:
    """Traced children ``(noise_params,)``; aux ``noise_fn``."""
    return (self.noise_params,), self.noise_fn

tree_unflatten classmethod

tree_unflatten(
    aux_data: Callable, children: tuple
) -> CallableDynamicsNoise

Rebuild without re-validating — leaves may be tracers.

Source code in src/cpomdp/dynamics.py
@classmethod
def tree_unflatten(
    cls, aux_data: Callable, children: tuple
) -> "CallableDynamicsNoise":
    """Rebuild without re-validating — leaves may be tracers."""
    (noise_params,) = children
    obj = object.__new__(cls)
    object.__setattr__(obj, "noise_fn", aux_data)
    object.__setattr__(obj, "noise_params", noise_params)
    return obj