"""Helpers for a model whose rounds last more than one tick: whole-step kernels and targets.
A round steps every factor once and may last a different time per level of one control node
(``SystemParams.durations``); the engine composes and integrates nothing, so the kernel of a
step is written for the whole step. Three pure functions write the mechanical cases:
* :func:`compose` the kernel of ``n`` repeats of a per-tick linear-Gaussian kernel;
* :func:`discretise` the exact zero-order-hold discretisation of a continuous-time linear
system over a duration, one per level if the levels last different times;
* :func:`accumulated_target` a per-tick target as the conditional target of a step, per level,
its precision (Gaussian) or log-table (categorical) scaled by the level's duration.
Each returns an ordinary declaration (a ``LinearGaussianTransition``, a ``ConditionalGaussian``,
a ``ConditionalCategorical``). Design: docs/design/step-durations.md T3, T4, T5.
"""
import jax
import jax.numpy as jnp
from jax import Array
from jax.scipy.linalg import expm
from hybrid_aif.distributions import (
Categorical,
ConditionalCategorical,
ConditionalGaussian,
Gaussian,
)
from hybrid_aif.factors import LinearGaussianTransition
def _compose_mode(F: Array, b: Array, chol: Array, G: Array | None, n: int):
"""``n`` repeats of ``x' = F x + G u + b + eps``, ``eps ~ N(0, chol cholᵀ)``, for one mode:
``(F^n, sum F^i b, sum F^i Q F^iᵀ, sum F^i G)`` over ``i < n``."""
Q = chol @ chol.T
eye = jnp.eye(F.shape[-1], dtype=F.dtype)
def body(carry, _):
Fp, bn, Qn, Gn = carry
bn = bn + Fp @ b
Qn = Qn + Fp @ Q @ Fp.T
Gn = Gn if G is None else Gn + Fp @ G
return (F @ Fp, bn, Qn, Gn), None
init = (eye, jnp.zeros_like(b), jnp.zeros_like(Q), None if G is None else jnp.zeros_like(G))
(Fn, bn, Qn, Gn), _ = jax.lax.scan(body, init, None, length=n)
return Fn, bn, Qn, Gn
[docs]
def compose(kernel: LinearGaussianTransition, n: int) -> LinearGaussianTransition:
"""The kernel of ``n`` repeats of a per-tick linear-Gaussian kernel, per mode.
With ``x' = F x + G u + b + eps`` and ``eps ~ N(0, Q)`` per tick (a control input held over
the step), ``n`` ticks give ``F_n = F^n``, ``b_n = sum_{i<n} F^i b``, ``Q_n = sum_{i<n} F^i Q
F^iᵀ`` and ``G_n = sum_{i<n} F^i G``. A per-mode ``F`` or ``G`` (leading axes
``innovations.parent_shape``) is composed mode by mode; a shared one stays shared, and an
innovation noise shared across the modes (:attr:`ConditionalGaussian.shared_chol`) under a
shared ``F`` stays shared (under a per-mode ``F`` the composed noise is per mode). ``n`` is a
static positive int. The returned innovation is a
:class:`~hybrid_aif.distributions.ConditionalGaussian` carrying the Cholesky factor of
``Q_n`` (a kernel with a singular ``Q`` per tick needs ``n`` ticks to be non-singular in the
directions it reaches, as the Cholesky factor requires).
Design: docs/design/step-durations.md T3.
"""
if not isinstance(n, int) or isinstance(n, bool) or n < 1:
raise ValueError(f"compose: n must be a positive int, got {n!r}")
if kernel.noise_prior is not None:
raise ValueError(
"compose: the kernel's noise is learned (noise_prior), and the composed noise "
"Q_n = sum F^i Q F^iᵀ is no inverse-Gamma or inverse-Wishart variable a learn step "
"could update; compose its point form, hybrid_aif.factors.transition_point(kernel), "
"or learn the noise of the composed kernel itself"
)
inn = kernel.innovations
shape = inn.parent_shape
d = inn.dim
count = 1
for s in shape:
count *= s
shared_F = kernel.F.ndim == 2
G = kernel.G
shared_G = G is not None and G.ndim == 2
def flat(x, shared, trailing):
if shared:
return jnp.broadcast_to(x, (count, *x.shape))
return x.reshape(count, *trailing)
F = flat(kernel.F, shared_F, (d, d))
b = inn.loc.reshape(count, d)
chol = inn.stacked_chol().reshape(count, d, d)
Gf = None if G is None else flat(G, shared_G, G.shape[-2:])
if Gf is None:
Fn, bn, Qn, _ = jax.vmap(lambda f, c, ch: _compose_mode(f, c, ch, None, n))(F, b, chol)
Gn = None
else:
Fn, bn, Qn, Gn = jax.vmap(lambda f, c, ch, g: _compose_mode(f, c, ch, g, n))(F, b, chol, Gf)
Fn = Fn[0] if shared_F else Fn.reshape(*shape, d, d)
if Gn is not None:
Gn = Gn[0] if shared_G else Gn.reshape(*shape, *Gn.shape[-2:])
# one noise composed under one map is one noise: the shared form is kept
chol_n = jnp.linalg.cholesky(Qn)
chol_n = chol_n[0] if inn.shared_chol and shared_F else chol_n.reshape(*shape, d, d)
innovations = ConditionalGaussian(
loc=bn.reshape(*shape, d), chol=chol_n, parent_ndims=inn.parent_ndims
)
return LinearGaussianTransition(F=Fn, innovations=innovations, G=Gn)
def _discretise_one(A: Array, B: Array | None, Q: Array, dt: Array):
"""Van Loan's exact zero-order-hold discretisation over ``dt``: ``(F, Q_d, G)``."""
d = A.shape[-1]
zeros = jnp.zeros_like(A)
noise = expm(jnp.block([[-A, Q], [zeros, A.T]]) * dt)
F = noise[d:, d:].T
Qd = F @ noise[:d, d:]
Qd = 0.5 * (Qd + Qd.T)
if B is None:
return F, Qd, None
du = B.shape[-1]
top = jnp.concatenate([A, B], axis=1)
bottom = jnp.zeros((du, d + du), A.dtype)
G = expm(jnp.concatenate([top, bottom], axis=0) * dt)[:d, d:]
return F, Qd, G
[docs]
def discretise(
A: Array, B: Array | None, Q: Array, dt: Array | float, modes: int | None = None
) -> LinearGaussianTransition:
"""The exact zero-order-hold discretisation of ``dx = A x + B u dt + dw``, ``dw ~ N(0, Q dt)``.
Over a duration ``dt``: ``F = expm(A dt)``, ``Q_d = int_0^dt expm(A s) Q expm(A s)ᵀ ds`` and
``G = int_0^dt expm(A s) ds B`` (a control held over the step), by Van Loan's matrix
exponential. ``A`` and ``Q`` are ``(d, d)``, ``B`` is ``(d, du)`` or ``None`` (the kernel then
has no ``G``). ``dt`` is one positive number, shared (a kernel whose innovations have the
trivial parent shape ``(1,)``, or ``(modes,)`` copies when ``modes`` is given), or a
``(levels,)`` array, one duration per level of a control node: the kernel is then per-mode,
``F``, ``G`` and the innovation's parent axis the level, which is how an option's kernel is
written (``modes``, if given, must equal ``levels``). Design: docs/design/step-durations.md T3.
"""
A = jnp.asarray(A)
Q = jnp.asarray(Q, A.dtype)
Bm = None if B is None else jnp.asarray(B, A.dtype)
dts = jnp.asarray(dt, A.dtype)
if dts.ndim > 1:
raise ValueError(f"discretise: dt is one number or a (levels,) array, got {dts.shape}")
if dts.ndim == 1 and modes is not None and modes != dts.shape[0]:
raise ValueError(
f"discretise: dt has {dts.shape[0]} level(s) but modes={modes}; give one or the other"
)
shared = dts.ndim == 0
if shared:
dts = jnp.broadcast_to(dts, (1 if modes is None else modes,))
d = A.shape[-1]
F, Qd, G = jax.vmap(lambda t: _discretise_one(A, Bm, Q, t))(dts)
innovations = ConditionalGaussian(
loc=jnp.zeros((dts.shape[0], d), A.dtype),
chol=jnp.linalg.cholesky(Qd),
parent_ndims=1,
)
if shared and modes is None:
F, G = F[0], None if G is None else G[0]
return LinearGaussianTransition(F=F, innovations=innovations, G=G)
[docs]
def accumulated_target(
target: Gaussian | Categorical, durations: Array
) -> ConditionalGaussian | ConditionalCategorical:
"""A per-tick target as the conditional target of a step, one distribution per level.
``durations`` is a positive ``(levels,)`` array. A per-tick ``Gaussian`` ``(loc, chol)`` with
precision ``L`` becomes a :class:`~hybrid_aif.distributions.ConditionalGaussian`
(``parent_ndims=1``) with the same ``loc`` and precision ``D_k L`` at level ``k``
(``chol_k = chol / sqrt(D_k)``). A per-tick ``Categorical`` becomes a
:class:`~hybrid_aif.distributions.ConditionalCategorical` whose table has the child axis first
and the level axis last, column ``k`` being ``log_softmax(D_k log_softmax(logits))``.
Each level is a normalised density with its own normaliser, scored once: the cross-entropy
against level ``k`` is ``D_k`` times the per-tick one up to a constant of that level, and
that constant is not a cost the model sets. A fixed cost per option is the control node's own
target, never this helper's. Design: docs/design/step-durations.md T4, T5.
"""
dur = jnp.asarray(durations)
if dur.ndim != 1:
raise ValueError(f"accumulated_target: durations is a (levels,) array, got {dur.shape}")
if isinstance(target, Gaussian):
if target.diagonal:
raise ValueError(
"accumulated_target: a Gaussian with a diagonal standard deviation (a chol "
"without its second axis) is a form for a modality's obs_targets entry; pass a "
"target with a full chol"
)
if target.batch_shape != ():
raise ValueError(
"accumulated_target: a Gaussian target is one distribution (batch shape ()), "
f"got batch shape {target.batch_shape}"
)
scale = 1.0 / jnp.sqrt(dur)
return ConditionalGaussian(
loc=jnp.broadcast_to(target.loc, (dur.shape[0], target.dim)),
chol=target.chol[None] * scale[:, None, None],
parent_ndims=1,
)
if isinstance(target, Categorical):
if target.logits.ndim != 1:
raise ValueError(
"accumulated_target: a Categorical target is one distribution over its levels, "
f"got logits of shape {target.logits.shape}"
)
log_c = jax.nn.log_softmax(target.logits)
table = jax.nn.log_softmax(dur[None, :] * log_c[:, None], axis=0)
return ConditionalCategorical(log_table=table, parent_ndims=1)
raise TypeError(
f"accumulated_target takes a Gaussian or a Categorical target, got {type(target).__name__}"
)