Priors¶
A prior is a Gauss–Markov process over the solution and its first q derivatives;
it encodes the smoothness assumed before seeing the ODE. See
How to choose for picking one.
| Prior | Process | Key parameters |
|---|---|---|
IWP |
q-times integrated Wiener process (the default) |
q (smoothness order), d (dimension), Xi (structural scale) |
MaternPrior |
Matern process | q (smoothness order), d (dimension), length_scale, Xi (structural scale) |
JointPrior |
a state block stacked with a hidden block | exposes E0_x, E0_hidden for joint state–parameter models |
PrecondIWP, PrecondMaternPrior |
preconditioned variants | better conditioning at high q / small h |
q sets the method's order of accuracy; Xi (together with the calibrated
sigma^2) sets the size of the uncertainty. Initialize the state from x0 with
taylor_mode_initialization(vf, x0, q) (which returns the Taylor-mode mean and a
zero/Dirac initial covariance). Symbols are defined in
Notation.
Every prior exposes the discrete-time transition A(h), drift b(h), process
noise Q(h), and — what the square-root filter actually consumes — its
upper-triangular square root Q_sqr(h) (Q = Q_sqr.T @ Q_sqr). For IWP /
PrecondIWP this is a closed form that avoids ever factorizing the dense,
ill-conditioned Q(h).
Gaussian Markov process prior models.
Modules:
| Name | Description |
|---|---|
gmp_priors |
|
Classes:
| Name | Description |
|---|---|
IWP |
Integrated Wiener Process prior model. |
JointPrior |
Joint prior combining independent state (x) and hidden/input (u) priors. |
MaternPrior |
Matern Gaussian process prior model using block matrix exponential. |
PrecondIWP |
Preconditioned Integrated Wiener Process prior. |
PrecondJointPrior |
Joint prior for preconditioned priors combining state (x) and hidden (u). |
PrecondMaternPrior |
Preconditioned Matern Gaussian process prior model. |
Functions:
| Name | Description |
|---|---|
taylor_mode_initialization |
Return flattened Taylor-mode coefficients produced via JAX Jet. |
Classes¶
IWP
¶
Bases: BasePrior
Integrated Wiener Process prior model.
Methods:
| Name | Description |
|---|---|
A |
Return the state transition matrix for step size h. |
Q |
Return the diffusion matrix for step size h. |
Q_sqr |
Closed-form upper-triangular square root of |
b |
Return the drift vector for step size h. |
Functions¶
A
¶
Return the state transition matrix for step size h.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike
|
Step size. |
required |
Returns:
| Type | Description |
|---|---|
Array
|
State transition matrix (shape [(q+1)d, (q+1)d]). |
Q
¶
Return the diffusion matrix for step size h.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike
|
Step size. |
required |
Returns:
| Type | Description |
|---|---|
Array
|
Diffusion matrix (shape [(q+1)d, (q+1)d]). |
Q_sqr
¶
Closed-form upper-triangular square root of Q(h).
Q(h)_sqr = kron(chol(Q_bar).T @ T(h), chol(xi).T) (see
:meth:__init__); never forms or factorizes the dense ill-conditioned
Q(h).
b
¶
Return the drift vector for step size h.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike
|
Step size. |
required |
Returns:
| Type | Description |
|---|---|
Array
|
Zero drift vector (shape [(q+1)*d]). |
JointPrior
¶
Bases: BasePrior
Joint prior combining independent state (x) and hidden/input (u) priors.
Creates a block-diagonal prior structure where state and hidden evolution are independent. The resulting matrices are block-diagonal with zeros in the off-diagonal blocks.
For joint state-parameter estimation, the hidden state u can represent unknown parameters that appear in the ODE but evolve according to their own prior (e.g., IWP or Matern).
Projection matrices
E0: Extracts [x, u] - zeroth derivatives of both (shape [d_x + d_u, D]) E0_x: Extracts x only - zeroth derivative of state (shape [d_x, D]) E0_hidden: Extracts u only - zeroth derivative of hidden (shape [d_u, D]) E1: Extracts dx/dt - first derivative of state x (shape [d_x, D]) E2: Extracts d^2x/dt^2 - second derivative of x (shape [d_x, D]), if q >= 2
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prior_x
|
BasePrior
|
BasePrior instance for state evolution. |
required |
prior_u
|
BasePrior
|
BasePrior instance for hidden/input evolution. |
required |
Methods:
| Name | Description |
|---|---|
A |
Return the block-diagonal state transition matrix. |
Q |
Return the block-diagonal diffusion matrix. |
Q_sqr |
Block-diagonal upper-triangular square root of |
apply_state_sigma_sqr |
Scale only the state block of |
apply_state_sigma_to_cov_sqr |
Scale only the state block of a full-state covariance sqrt. |
b |
Return the concatenated drift vector. |
Attributes:
| Name | Type | Description |
|---|---|---|
E0_hidden |
Array
|
Hidden state extraction matrix for u only (shape [d_u, D]). |
E0_state |
Array
|
State-only value projection (Bosch et al. 2022 sec. 3). |
E0_x |
Array
|
State extraction matrix for x only (shape [d_x, D]). |
xi_state |
Array
|
State-prior component-correlation matrix (shape |
Attributes¶
E0_hidden
property
¶
Hidden state extraction matrix for u only (shape [d_u, D]).
Use this as E0_hidden in the measurement model.
E0_x
property
¶
State extraction matrix for x only (shape [d_x, D]).
Use this as E0 in the measurement model when you have hidden states.
xi_state
property
¶
State-prior component-correlation matrix (shape [d_x, d_x]).
Diagonal-mode calibration only requires the state block to be per-component diagonal; the hidden block's xi can be arbitrary.
Functions¶
A
¶
Return the block-diagonal state transition matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike
|
Step size. |
required |
Returns:
| Type | Description |
|---|---|
Array
|
Block-diagonal transition matrix with state and input blocks. |
Q
¶
Return the block-diagonal diffusion matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike
|
Step size. |
required |
Returns:
| Type | Description |
|---|---|
Array
|
Block-diagonal diffusion matrix with state and input blocks. |
Q_sqr
¶
Block-diagonal upper-triangular square root of Q(h).
Q is block-diagonal, so its square root is the block-diagonal of the
sub-priors' square roots -- this delegates to each sub-prior's
:meth:Q_sqr (closed-form for IWP) rather than factorizing the
dense joint Q(h).
apply_state_sigma_sqr
¶
Scale only the state block of Q_sqr by sqrt(sigma_sqr).
Accepts a scalar (uniform state-block scaling) or a length-d_x
vector (per-component state-block scaling used by
calibration="diagonal"). In both cases the input block is
untouched. Q is block-diagonal, so its upper-triangular sqrt is
also block-diagonal: column-scaling the state block of the sqrt by
sqrt(sigma_sqr_tiled) yields blkdiag(diag(sigma) Q_x diag(sigma),
Q_u) (where diag(sigma) collapses to a scalar in the scalar
case).
apply_state_sigma_to_cov_sqr
¶
Scale only the state block of a full-state covariance sqrt.
P = P_sqr.T @ P_sqr. Multiplying columns [:, :D_x] of the
upper-triangular sqrt by sqrt(sigma_sqr) scales rows and
columns :D_x of P by sigma_sqr and leaves the input
block alone.
b
¶
Return the concatenated drift vector.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike
|
Step size. |
required |
Returns:
| Type | Description |
|---|---|
Array
|
Drift vector concatenating state and input drifts. |
MaternPrior
¶
Bases: BasePrior
Matern Gaussian process prior model using block matrix exponential.
Note
Unlike IWP, the Matern process noise Q(h) is derived from a block
matrix exponential and factorized via a (jittered) Cholesky rather than a
closed-form square root. At high smoothness (roughly q >= 6) that dense
Q loses positive-definiteness in float64 and Q_sqr can return
NaN. Prefer q <= 4 for Matern priors, or use IWP / PrecondIWP
(closed-form Q_sqr) when you need higher orders.
Initialize the Matern prior.
This creates a Matern process prior for a d-dimensional process whose
dimensions share the same smoothness q and length scale and are
coupled by the component-correlation matrix Xi: the process noise is
kron(Q_scalar(h), Xi). Xi may be any positive-(semi)definite
matrix -- a diagonal Xi gives independent per-dimension output
scales, off-diagonal entries add cross-dimension correlation. (The
per-component "diagonal" calibration modes additionally require
Xi diagonal; that is checked at solve time.)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
q
|
int
|
Smoothness order. |
required |
d
|
int
|
State dimension. |
required |
length_scale
|
float
|
Length scale of the process. |
required |
Xi
|
ArrayLike | None
|
Optional component-correlation matrix (shape [d, d]). |
None
|
Methods:
| Name | Description |
|---|---|
A |
Return the state transition matrix for step size h. |
A_and_Q |
Compute both A(h) and Q(h) efficiently in a single expm call. |
Q |
Return the diffusion matrix for step size h. |
b |
Return the drift vector for step size h. |
Functions¶
A
¶
Return the state transition matrix for step size h.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike
|
Step size. |
required |
Returns:
| Type | Description |
|---|---|
Array
|
State transition matrix (shape [n, n]). |
A_and_Q
¶
Compute both A(h) and Q(h) efficiently in a single expm call. This is sometimes called matrix fraction decomposition (MFD)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike
|
Step size. |
required |
Returns:
| Type | Description |
|---|---|
Array
|
Tuple of (A_h, Q_h) where: |
Array
|
|
tuple[Array, Array]
|
|
Q
¶
Return the diffusion matrix for step size h.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike
|
Step size. |
required |
Returns:
| Type | Description |
|---|---|
Array
|
Diffusion matrix (shape [(q+1)d, (q+1)d]). |
b
¶
Return the drift vector for step size h.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike
|
Step size. |
required |
Returns:
| Type | Description |
|---|---|
Array
|
Zero drift vector (shape [(q+1)*d]). |
PrecondIWP
¶
Bases: BasePrior
Preconditioned Integrated Wiener Process prior.
Uses a preconditioning transformation T(h) to make matrices stepsize-independent. The transformation matrices A() and Q() are constant (independent of h), while the stepsize dependence is absorbed into T(h).
Methods:
| Name | Description |
|---|---|
A |
Return the constant preconditioning transition matrix. |
Q |
Return the constant preconditioning diffusion matrix. |
Q_sqr |
Return the constant upper-triangular square root of |
T |
Return the stepsize-dependent preconditioning transformation. |
b |
Return the zero drift vector. |
Functions¶
A
¶
Return the constant preconditioning transition matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike | None
|
Step size (unused, accepted for interface compatibility). |
None
|
Returns:
| Type | Description |
|---|---|
Array
|
Constant transition matrix (shape [(q+1)d, (q+1)d]). |
Q
¶
Return the constant preconditioning diffusion matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike | None
|
Step size (unused, accepted for interface compatibility). |
None
|
Returns:
| Type | Description |
|---|---|
Array
|
Constant diffusion matrix (shape [(q+1)d, (q+1)d]). |
Q_sqr
¶
Return the constant upper-triangular square root of Q.
Stepsize-independent in preconditioned space (see :meth:__init__).
T
¶
Return the stepsize-dependent preconditioning transformation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike
|
Step size. |
required |
Returns:
| Type | Description |
|---|---|
Array
|
Preconditioning transformation matrix (shape [(q+1)d, (q+1)d]). |
b
¶
Return the zero drift vector.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike | None
|
Step size (unused, accepted for interface compatibility). |
None
|
Returns:
| Type | Description |
|---|---|
Array
|
Zero drift vector (shape [(q+1)*d]). |
PrecondJointPrior
¶
PrecondJointPrior(
prior_x: PrecondIWP | PrecondMaternPrior,
prior_u: PrecondIWP | PrecondMaternPrior,
)
Joint prior for preconditioned priors combining state (x) and hidden (u).
This is the preconditioned version of JointPrior, designed specifically for PrecondIWP priors. The matrices A(), b(), Q() are constant (stepsize-independent), with the stepsize dependence absorbed into T(h).
Note: Mixing preconditioned and non-preconditioned priors is not supported and would lead to inconsistent filter behavior.
Projection matrices
E0: Extracts [x, u] - zeroth derivatives of both (shape [d_x + d_u, D]) E0_x: Extracts x only - zeroth derivative of state (shape [d_x, D]) E0_hidden: Extracts u only - zeroth derivative of hidden (shape [d_u, D]) E1: Extracts dx/dt - first derivative of state x (shape [d_x, D]) E2: Extracts d^2x/dt^2 - second derivative of x (shape [d_x, D]), if q >= 2
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prior_x
|
PrecondIWP | PrecondMaternPrior
|
PrecondIWP instance for state evolution. |
required |
prior_u
|
PrecondIWP | PrecondMaternPrior
|
PrecondIWP instance for hidden/input evolution. |
required |
Example
prior_x = PrecondIWP(q=2, d=2) prior_u = PrecondIWP(q=1, d=1) joint = PrecondJointPrior(prior_x, prior_u) A = joint.A() # Constant transition matrix T_h = joint.T(0.1) # Stepsize-dependent transformation
Methods:
| Name | Description |
|---|---|
A |
Return the block-diagonal transition matrix. |
Q |
Return the block-diagonal diffusion matrix. |
Q_sqr |
Block-diagonal upper-triangular square root of |
T |
Return the stepsize-dependent block-diagonal transformation matrix. |
apply_state_sigma_sqr |
Scale only the state block of |
apply_state_sigma_to_cov_sqr |
Scale only the state block of a full-state covariance sqrt. |
b |
Return the zero drift vector. |
Attributes:
| Name | Type | Description |
|---|---|---|
E0 |
Array
|
Combined state extraction matrix (shape [d_x + d_u, D]). |
E0_hidden |
Array
|
Hidden state extraction matrix for u only (shape [d_u, D]). |
E0_state |
Array
|
State-only value projection (Bosch et al. 2022 sec. 3). |
E0_x |
Array
|
State extraction matrix for x only (shape [d_x, D]). |
E1 |
Array
|
First derivative extraction matrix for x (shape [d_x, D]). |
E2 |
Array | None
|
Second derivative extraction matrix for x (shape [d_x, D]), or None. |
xi_state |
Array
|
State-prior component-correlation matrix (shape |
Attributes¶
E0_hidden
property
¶
Hidden state extraction matrix for u only (shape [d_u, D]).
Use this as E0_hidden in the measurement model.
E0_x
property
¶
State extraction matrix for x only (shape [d_x, D]).
Use this as E0 in the measurement model when you have hidden states.
Functions¶
A
¶
Return the block-diagonal transition matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike | None
|
Step size (passed through to sub-priors). |
None
|
Returns:
| Type | Description |
|---|---|
Array
|
Block-diagonal transition matrix with state and hidden blocks. |
Q
¶
Return the block-diagonal diffusion matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike | None
|
Step size (passed through to sub-priors). |
None
|
Returns:
| Type | Description |
|---|---|
Array
|
Block-diagonal diffusion matrix with state and hidden blocks. |
Q_sqr
¶
Block-diagonal upper-triangular square root of Q.
Delegates to each sub-prior's :meth:Q_sqr (constant for PrecondIWP)
rather than factorizing the dense joint Q.
T
¶
Return the stepsize-dependent block-diagonal transformation matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike
|
Step size. |
required |
Returns:
| Type | Description |
|---|---|
Array
|
Block-diagonal preconditioning transformation matrix. |
apply_state_sigma_sqr
¶
Scale only the state block of Q_sqr by sqrt(sigma_sqr).
Accepts a scalar or a length-d_x vector. See
:meth:JointPrior.apply_state_sigma_sqr for the rationale.
apply_state_sigma_to_cov_sqr
¶
Scale only the state block of a full-state covariance sqrt.
See :meth:JointPrior.apply_state_sigma_to_cov_sqr for the rationale.
b
¶
Return the zero drift vector.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike | None
|
Step size (passed through to sub-priors). |
None
|
Returns:
| Type | Description |
|---|---|
Array
|
Zero drift vector (shape [D_x + D_u]). |
PrecondMaternPrior
¶
Bases: BasePrior
Preconditioned Matern Gaussian process prior model.
Uses the same diagonal preconditioner D(h) as PrecondIWP, but the preconditioned transition A_bar(h) and diffusion Q_bar(h) are stepsize-dependent (they converge to the IWP constants as h -> 0).
Note
Like MaternPrior, the underlying expm-derived Q is Cholesky-
factorized and can return NaN at high smoothness (roughly q >= 6);
preconditioning does not rescue this. Prefer q <= 4, or PrecondIWP
for higher orders.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
q
|
int
|
Smoothness order (nu = q + 1/2). |
required |
d
|
int
|
State dimension. |
required |
length_scale
|
float
|
Length scale of the Matern process. |
required |
Xi
|
ArrayLike | None
|
Optional scaling matrix (shape [d, d]). |
None
|
Methods:
| Name | Description |
|---|---|
A |
Return the preconditioned transition matrix for step size h. |
Q |
Return the preconditioned diffusion matrix for step size h. |
Q_sqr |
Upper-triangular square root of the preconditioned |
T |
Return the stepsize-dependent preconditioning transformation. |
b |
Return the zero drift vector. |
Functions¶
A
¶
Return the preconditioned transition matrix for step size h.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike | None
|
Step size (required; Matern preconditioning is stepsize-dependent). |
None
|
Returns:
| Type | Description |
|---|---|
Array
|
Preconditioned transition matrix (shape [(q+1)d, (q+1)d]). |
Q
¶
Return the preconditioned diffusion matrix for step size h.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike | None
|
Step size (required; Matern preconditioning is stepsize-dependent). |
None
|
Returns:
| Type | Description |
|---|---|
Array
|
Preconditioned diffusion matrix (shape [(q+1)d, (q+1)d]). |
Q_sqr
¶
Upper-triangular square root of the preconditioned Q(h).
The preconditioned Q_bar(h) is well-conditioned (it converges to the
IWP constant as h -> 0), so a symmetrized Cholesky is stable here.
Accepts h=None for interface symmetry with the other preconditioned
priors, but Q itself requires h.
T
¶
Return the stepsize-dependent preconditioning transformation.
Uses the same preconditioner as PrecondIWP.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike
|
Step size. |
required |
Returns:
| Type | Description |
|---|---|
Array
|
Preconditioning transformation matrix (shape [(q+1)d, (q+1)d]). |
b
¶
Return the zero drift vector.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
h
|
ArrayLike | None
|
Step size (unused, accepted for interface compatibility). |
None
|
Returns:
| Type | Description |
|---|---|
Array
|
Zero drift vector (shape [(q+1)*d]). |
Functions¶
taylor_mode_initialization
¶
taylor_mode_initialization(
vf: VectorField,
inits: ArrayLike | tuple[ArrayLike, ...],
q: int,
t0: float = 0.0,
order: int = 1,
) -> tuple[Array, Array]
Return flattened Taylor-mode coefficients produced via JAX Jet.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
vf
|
VectorField
|
Vector field whose Taylor coefficients are required. For order=1: vf(x, , t) -> dx/dt For order=2: vf(x, dx, , t) -> d²x/dt² |
required |
inits
|
ArrayLike | tuple[ArrayLike, ...]
|
Initial value(s) around which the expansion takes place. For order=1: x0 (initial state) For order=2: (x0, dx0) tuple of initial state and velocity |
required |
q
|
int
|
Number of higher-order coefficients to compute. |
required |
t0
|
float
|
Initial time for Taylor expansion (default 0.0). |
0.0
|
order
|
int
|
ODE order (1 or 2, default 1). |
1
|
Returns:
| Type | Description |
|---|---|
Array
|
Tuple of (coefficients, covariance) where: |
Array
|
|
tuple[Array, Array]
|
|