Skip to content

PreparedModel

PreparedModel wraps a NumPyro model callable and retains the static observation missingness layouts needed by LatentPathBuilder. This works with automatic LPB selection and with explicit LPB handlers, even if the model constructs new DynamicalModel objects from sampled parameters on every execution.

Prepare the wrapper with concrete observations before using traced model arguments:

import jax.random as jr
from numpyro.infer import MCMC, NUTS

import dynestyx as dsx

model = dsx.PreparedModel(model_fn)
model.prepare(obs_times=times, obs_values=observations)

mcmc = MCMC(
    NUTS(model),
    num_warmup=200,
    num_samples=200,
    jit_model_args=True,
)
mcmc.run(jr.PRNGKey(1), obs_times=times, obs_values=observations)

prepare executes the full model once under a NumPyro seed (zero by default, configurable through rng_seed), including its normal handlers and side effects. It discards the execution outputs and returns the wrapper. Subsequent model execution retains the usual seed requirements. An ordinary eager call under a seed also prepares layouts; JAX does not automatically perform this eager pass.

Each wrapper owns its cache. Entries are distinguished by sample-site name and observation shape; plate members have separate entries. Observation times and finite values may change, but the missingness pattern at an existing site and shape must remain fixed. A changed pattern raises a layout mismatch error. For a different pattern, create a new wrapper and a new inference or compiled callable. Calling prepare again does not invalidate existing JAX compilations or reset the wrapper's layouts.

Explicit missing_obs_metadata takes precedence for that call and does not replace the wrapper's cached layout. The wrapper stores no parameter draws, inferred states, or model outputs. Nested wrapped models use their own caches, and the caller's cache scope is restored when a model returns or raises.

Wrap a NumPyro model with a persistent LPB missingness-layout cache.

Automatic and explicit LatentPathBuilder handlers share this wrapper's metadata by sample-site name and observation shape, including plate-member names. Separate wrappers have independent caches. Dynamics may be rebuilt from sampled parameters on every execution.

Call prepare with concrete observations before passing observations dynamically through JIT or MCMC(..., jit_model_args=True). An ordinary eager call under a NumPyro seed also prepares layouts. A first call with dynamically traced observations needs a prepared layout or explicit missing_obs_metadata.

Observation values and times may change, but the missingness pattern for an existing site and shape must remain fixed. Use a new wrapper and a new inference/compiled callable for a different pattern. Explicit metadata overrides the wrapper's layout for that call without changing its cache.

Attributes:

Name Type Description
model

Original NumPyro model callable. Only static missingness metadata is retained; parameters, inferred states, and execution outputs are not cached.

__init__(model: Callable[..., Any]) -> None

Create an independent cache for model without executing it.

__call__(*args: Any, **kwargs: Any) -> Any

Execute the model with this wrapper's layouts available to LPB.

prepare(*args: Any, rng_seed: int | PRNGKeyArray = 0, **kwargs: Any) -> Self

Run the model eagerly to prepare layouts, then return this wrapper.

Parameters:

Name Type Description Default
*args Any

Positional model arguments, containing concrete observations.

()
rng_seed int | PRNGKeyArray

NumPyro seed or key for this preparation execution. Defaults to zero; subsequent inference supplies its own seed.

0
**kwargs Any

Keyword model arguments.

{}

The full model executes once, including its usual side effects and handlers. Execution outputs are discarded. Failed preparation leaves the existing cache unchanged. This method does not reset an existing layout or invalidate JAX's compiled functions.