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.