Result Types¶
The standalone and handler-based APIs return dataclasses.
dynestyx.Result provides typed properties for conditioning, latent-path,
simulation, and evaluation outputs. sample and condition return this common
interface. Unsupported properties raise NotImplementedError; supported fields
can be None when their handler did not record a value.
Filter diagnostics are available directly as result.log_normalizing_constant,
result.ensemble, result.predicted_ensemble, and result.model_inputs when the
backend records them. .states retains the original backend object. For example:
with dsx.Filter(filter_config):
result = dsx.condition("trajectory", dynamics, obs_times=times, obs_values=values)
# Requires a backend that records cumulative log normalizing constants.
cumulative_loglik = result.log_normalizing_constant
StructuredSimulatedResult is an explicit conversion of a simulation result,
not a direct handler result.
Typed interface for outputs produced by dynestyx handlers.
Unsupported properties raise NotImplementedError. Supported fields may
be None when their handler did not record a value. Concrete results
retain their constructor arguments and stored dataclass fields.
Bases: Result
Common base for results from the NumPyro-free conditioning primitive.
dsx.condition returns this type under both Filter and Smoother.
It carries the complete inference output through the handler stack without
registering NumPyro sites. Filter results may additionally expose the
canonical one-step-ahead predicted_observations and an
evaluation_result attached by an outer evaluation handler. Posterior
distributions are time-major:
dists[i] corresponds to times[..., i]. Leading axes on times
are optional plate axes, while each distribution may carry the matching
plate axes in its batch shape.
ensemble: Real[Array, '*plate time n_members state_dim']
property
¶
Filtered state ensembles after assimilating each observation.
log_normalizing_constant: Real[Array, '*plate time']
property
¶
Cumulative log normalizing constants recorded by the filter backend.
model_inputs: FilterModelInputs
property
¶
Observation-aligned inputs recorded by the filter backend.
predicted_ensemble: Real[Array, '*plate time n_members state_dim']
property
¶
State ensembles before assimilating each observation, when recorded.
Bases: Result
Result of latent-state construction / scoring without NumPyro side effects.
Let z = state_path_params denote the free variables used to
parameterize the latent trajectory, and let
x = state_path = g(z)
denote the full reconstructed latent state path used by the probabilistic
model. The joint density is evaluated as log p(x, y) after
reconstructing x from z.
In simple discrete models these may match exactly. In ODE models, or when exact observations leave only a subset of state coordinates free, they generally differ.
When explicit missing-observation augmentation is active, the result also carries a second latent block:
missing_obs_valuesare the free coordinates used to fill missing entries ofobs_values,completed_obs_valuesis the dense observation array after those missing entries are filled back in.
Under plates, latent-coordinate fields are stacked when all members have the same shape. Ragged values are returned as a flat list in plate order, with the rightmost plate index varying fastest.
Bases: Result
Outputs computed by an evaluation handler.
Evaluation handlers attach this object to the ConditionedResult they
consume. NumPyro registration remains deferred so dsx.condition stays
side-effect free while dsx.sample can register the same outputs later.
Bases: Module, Result
Result of simulation without eager NumPyro side effects.
This result therefore stores the realized state path x and observation path y
produced on the requested simulator time grid.
For raw forward simulation, times, x_0, states, and
observations are populated. The field names match their NumPyro site
suffixes. When a simulator is layered outside a Filter or Smoother for
posterior rollout, the same result object instead carries
predicted_times, predicted_states, and
predicted_observations.
Simulator outputs always retain a trailing coordinate axis: x_0 has
shape (*plate, n_simulations, state_coordinates), and paths have shape
(*plate, n_simulations, time, coordinates). Scalar states, categorical
labels, and scalar observations use a singleton coordinate axis.
obs_times and ctrl_times record where observations and
controls actually sit -- the names match the obs_times /
ctrl_times keywords used elsewhere in the API. They need not equal
times, so read alignment off these fields rather than inferring it
from array lengths: e.g. open-loop "previous_transition" observes on
times[1:] and controls on times[:-1].
obs_times is populated by every simulator. ctrl_times accompanies
controls: populated by DiscreteTimeSimulator (when controls are
supplied) and DiscreteControlLoopSimulator, and None for an
uncontrolled model or for ODE/SDE simulators, which do not record
controls yet.
For open-loop simulation of a discrete-time model with
dynamics.observation_control_alignment="previous_transition", states are
of length :math:T (matching times), while observations and
controls are of length :math:T-1. Closed-loop simulation currently
runs this convention only (an unspecified field resolves to it; an explicit
"same_time" is not implemented yet), so it returns the same shapes. In
both cases, :math:y_0 is never sampled because there is no control that
produced it.
unflatten(layout: LayoutCollection) -> StructuredSimulatedResult
¶
Return a structured copy of this result.
Each populated state, control, and observation field (including
x_0 and the predicted_* fields) is converted by the matching
sublayout of layout. Fields whose sublayout is None and time
fields are copied unchanged.
StructuredSimulatedResult.flatten
undoes the conversion.
Bases: Module
A SimulatedResult with structured values.
Returned by
SimulatedResult.unflatten. It
has the same fields, but x_0, states, controls,
observations, predicted_states, and predicted_observations may
be pytrees of arrays, as described by the sublayouts of a
LayoutCollection. Leaves keep the leading batch and time axes of the
flat field. Time fields are never converted.
This is a user-facing helper: Dynestyx itself only consumes flat results.
flatten(layout) converts back to a SimulatedResult.
flatten(layout: LayoutCollection) -> SimulatedResult
¶
Return the flat result that unflatten(layout) converted.
layout must be the LayoutCollection passed to unflatten.
Raises ValueError if a structured field has no sublayout.