Skip to content

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

IWP(q: int, d: int, Xi: ArrayLike | None = None)

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 Q(h).

b

Return the drift vector for step size h.

Functions
A
A(h: ArrayLike) -> Array

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
Q(h: ArrayLike) -> Array

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
Q_sqr(h: ArrayLike) -> Array

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
b(h: ArrayLike) -> Array

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

JointPrior(prior_x: BasePrior, prior_u: BasePrior)

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 Q(h).

apply_state_sigma_sqr

Scale only the state block of Q_sqr by sqrt(sigma_sqr).

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 [d_x, d_x]).

Attributes
E0_hidden property
E0_hidden: Array

Hidden state extraction matrix for u only (shape [d_u, D]).

Use this as E0_hidden in the measurement model.

E0_state property
E0_state: Array

State-only value projection (Bosch et al. 2022 sec. 3).

E0_x property
E0_x: Array

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
xi_state: Array

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
A(h: ArrayLike) -> Array

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
Q(h: ArrayLike) -> Array

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
Q_sqr(h: ArrayLike) -> Array

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
apply_state_sigma_sqr(
    Q_sqr: Array, sigma_sqr: ArrayLike
) -> Array

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
apply_state_sigma_to_cov_sqr(
    P_sqr: Array, sigma_sqr: ArrayLike
) -> Array

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
b(h: ArrayLike) -> Array

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

MaternPrior(
    q: int,
    d: int,
    length_scale: float,
    Xi: ArrayLike | None = None,
)

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
A(h: ArrayLike) -> Array

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
A_and_Q(h: ArrayLike) -> tuple[Array, Array]

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
  • A_h: State transition matrix (shape [n, n])
tuple[Array, Array]
  • Q_h: Diffusion matrix (shape [n, n])
Q
Q(h: ArrayLike) -> Array

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
b(h: ArrayLike) -> Array

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

PrecondIWP(q: int, d: int, Xi: ArrayLike | None = None)

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 Q.

T

Return the stepsize-dependent preconditioning transformation.

b

Return the zero drift vector.

Functions
A
A(h: ArrayLike | None = None) -> Array

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
Q(h: ArrayLike | None = None) -> Array

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
Q_sqr(h: ArrayLike | None = None) -> Array

Return the constant upper-triangular square root of Q.

Stepsize-independent in preconditioned space (see :meth:__init__).

T
T(h: ArrayLike) -> Array

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
b(h: ArrayLike | None = None) -> Array

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 Q.

T

Return the stepsize-dependent block-diagonal transformation matrix.

apply_state_sigma_sqr

Scale only the state block of Q_sqr by sqrt(sigma_sqr).

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 [d_x, d_x]).

Attributes
E0 property
E0: Array

Combined state extraction matrix (shape [d_x + d_u, D]).

E0_hidden property
E0_hidden: Array

Hidden state extraction matrix for u only (shape [d_u, D]).

Use this as E0_hidden in the measurement model.

E0_state property
E0_state: Array

State-only value projection (Bosch et al. 2022 sec. 3).

E0_x property
E0_x: Array

State extraction matrix for x only (shape [d_x, D]).

Use this as E0 in the measurement model when you have hidden states.

E1 property
E1: Array

First derivative extraction matrix for x (shape [d_x, D]).

E2 property
E2: Array | None

Second derivative extraction matrix for x (shape [d_x, D]), or None.

xi_state property
xi_state: Array

State-prior component-correlation matrix (shape [d_x, d_x]).

Functions
A
A(h: ArrayLike | None = None) -> Array

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
Q(h: ArrayLike | None = None) -> Array

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
Q_sqr(h: ArrayLike | None = None) -> Array

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
T(h: ArrayLike) -> Array

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
apply_state_sigma_sqr(
    Q_sqr: Array, sigma_sqr: ArrayLike
) -> Array

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
apply_state_sigma_to_cov_sqr(
    P_sqr: Array, sigma_sqr: ArrayLike
) -> Array

Scale only the state block of a full-state covariance sqrt.

See :meth:JointPrior.apply_state_sigma_to_cov_sqr for the rationale.

b
b(h: ArrayLike | None = None) -> Array

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

PrecondMaternPrior(
    q: int,
    d: int,
    length_scale: float,
    Xi: ArrayLike | None = None,
)

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 Q(h).

T

Return the stepsize-dependent preconditioning transformation.

b

Return the zero drift vector.

Functions
A
A(h: ArrayLike | None = None) -> Array

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
Q(h: ArrayLike | None = None) -> Array

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
Q_sqr(h: ArrayLike | None = None) -> Array

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
T(h: ArrayLike) -> Array

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
b(h: ArrayLike | None = None) -> Array

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
  • coefficients are the flattened Taylor coefficients as numpy array
tuple[Array, Array]
  • covariance is a zero covariance matrix as numpy array