Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,6 @@ The single `Filter()` handler is directed to the appropriate filtering algorithm

`include_predicted_observations` controls result-level collection of supported backend predictive-observation outputs. The `record_predicted_observations_mean`, `record_predicted_observations_cov`, and `record_predicted_observations_ensemble` fields separately control NumPyro recording. Collection and recording default to enabled; unavailable fields are omitted without making Filter fail.

::: dynestyx.inference.configs.filter
::: dynestyx.configs.filter
options:
filters: []
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@
Internal API reference for MCMC configuration dataclasses used by inference dispatchers and
backend integrations.

::: dynestyx.inference.configs.mcmc
::: dynestyx.configs.mcmc
options:
filters: []
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Scoring Configs

`dynestyx.evaluation.configs` contains configuration for evaluating conditioned results. `ObservationScoringConfig` currently configures one-step-ahead predictive-observation scoring.
`dynestyx.configs.scoring` contains configuration for evaluating conditioned results. `ObservationScoringConfig` currently configures one-step-ahead predictive-observation scoring.

The score rule objects themselves live on the companion [Scoring](../../evaluation/scoring.md) page.

::: dynestyx.evaluation.configs
::: dynestyx.configs.scoring
options:
members:
- ObservationScoringConfig
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,6 @@ validated by `Smoother` before dispatch:
Smoother-specific fields live on the concrete classes rather than a nested
options object, which keeps handler dispatch and API docs aligned.

::: dynestyx.inference.configs.smoother
::: dynestyx.configs.smoother
options:
filters: []
6 changes: 3 additions & 3 deletions docs/api_reference/developer/simulators/simulator_configs.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,21 @@ simulator configuration.

## `SimulatorConfig`

::: dynestyx.inference.configs.simulator.SimulatorConfig
::: dynestyx.configs.simulator.SimulatorConfig
options:
show_root_heading: false
show_root_toc_entry: true

## `ODESimulatorConfig`

::: dynestyx.inference.configs.simulator.ODESimulatorConfig
::: dynestyx.configs.simulator.ODESimulatorConfig
options:
show_root_heading: false
show_root_toc_entry: true

## `SDESimulatorConfig`

::: dynestyx.inference.configs.simulator.SDESimulatorConfig
::: dynestyx.configs.simulator.SDESimulatorConfig
options:
show_root_heading: false
show_root_toc_entry: true
105 changes: 105 additions & 0 deletions docs/api_reference/public/configurations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
# Configurations

Use `dynestyx.configs` to find the configuration objects for filters, smoothers,
samplers, discretizers, simulators, and observation scoring.

```python
import dynestyx as dsx

filter_handler = dsx.Filter(filter_config=dsx.configs.EnKFConfig(n_particles=64))
```

## Filters

Pass a filter config to `dsx.Filter(filter_config=...)`.
See [Filter configurations](inference/configs/filter_configs.md) for algorithm and backend choices.

### Discrete-time filters

- `dsx.configs.KFConfig`
- `dsx.configs.EKFConfig`
- `dsx.configs.UKFConfig`
- `dsx.configs.EnKFConfig`
- `dsx.configs.PFConfig`

### Continuous-time filters

These filters handle continuous-time dynamics with discrete observations.

- `dsx.configs.ContinuousTimeKFConfig`
- `dsx.configs.ContinuousTimeEKFConfig`
- `dsx.configs.ContinuousTimeUKFConfig`
- `dsx.configs.ContinuousTimeEnKFConfig`
- `dsx.configs.ContinuousTimeDPFConfig`

### Finite-state filters

- `dsx.configs.HMMConfig`

### Localization and resampling

- `dsx.configs.EnKFLocalizationConfig` for distance-based covariance tapering via `EnKFConfig(localization=...)`
- `dsx.configs.EnKFLocalizationFunctions` for custom localization callbacks via `EnKFConfig(localization=...)`
- `dsx.configs.PFResamplingConfig` for resampling options via `PFConfig(resampling_method=...)`

## Smoothers

Pass a smoother config to `dsx.Smoother(smoother_config=...)`.
See [Smoother configurations](inference/configs/smoother_configs.md) for supported backends and options.

- `dsx.configs.KFSmootherConfig`
- `dsx.configs.EKFSmootherConfig`
- `dsx.configs.UKFSmootherConfig`
- `dsx.configs.EnRTSSmootherConfig`
- `dsx.configs.PFSmootherConfig`
- `dsx.configs.ContinuousTimeKFSmootherConfig`
- `dsx.configs.ContinuousTimeEKFSmootherConfig`

## MCMC

Pass a sampler config to `MCMCInference(mcmc_config=..., model=...)`.
See [MCMC configurations](inference/configs/mcmc_configs.md) for sampler and backend options.

- `dsx.configs.NUTSConfig`
- `dsx.configs.HMCConfig`
- `dsx.configs.AdaptiveMetropolisConfig`
- `dsx.configs.AdaptiveMWGConfig`
- `dsx.configs.SGLDConfig`
- `dsx.configs.MALAConfig`

## Discretizers

Pass a discretizer config to `dsx.Discretizer(discretizer_config=...)`.
See [Discretizer configurations](inference/configs/discretizer_configs.md) for method selection and the `dsx.configs.DiscretizerConfig` type alias.

- `dsx.configs.ODEFlowConfig`
- `dsx.configs.EulerMaruyamaConfig`
- `dsx.configs.ExactAffineConfig`
- `dsx.configs.LocalLinearizationConfig`
- `dsx.configs.MeanTrajectoryLinearizationConfig`
- `dsx.configs.DiffraxSampleConfig`

## Simulators

Pass a simulator config to `dsx.Simulator(simulator_config=...)`.
See [Simulator configurations](simulators/simulator_configs.md) for solver settings and the `dsx.configs.SimulatorConfig` type alias.

- `dsx.configs.ODESimulatorConfig`
- `dsx.configs.SDESimulatorConfig`

## Observation scoring

Pass `dsx.configs.ObservationScoringConfig` to `dsx.Evaluation(observation_scoring_config=...)`.
See [Scoring configs](inference/configs/scoring_configs.md) for score and predictive sample options.

## Migrating existing imports

Update config imports from `dynestyx.inference.configs.<module>` to
`dynestyx.configs.<module>`. Use `dynestyx.configs.scoring` for
`ObservationScoringConfig` imports from `dynestyx.evaluation.configs` or
`dynestyx.inference.scoring_configs`.

Use `dsx.configs` for `ODESimulatorConfig`, `SDESimulatorConfig`,
`SimulatorConfig`, and `ObservationScoringConfig` previously accessed directly
on `dsx`. The previous paths still resolve during the transition and emit a
`DeprecationWarning`.
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ See [Comparing SDE discretization methods on Lorenz–63](../../../../deep_dives

## Configuration classes

::: dynestyx.inference.configs.discretizer
::: dynestyx.configs.discretizer
options:
members:
- BaseDiscretizerConfig
Expand Down
28 changes: 15 additions & 13 deletions docs/api_reference/public/inference/configs/filter_configs.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ Create an updated config with `dataclasses.replace` instead of assigning to its
```python
from dataclasses import replace

from dynestyx.inference.configs.filter import EnKFConfig
import dynestyx as dsx

config = EnKFConfig(n_particles=30)
config = dsx.configs.EnKFConfig(n_particles=30)
larger_ensemble = replace(config, n_particles=100)
```

Expand Down Expand Up @@ -46,27 +46,28 @@ Dynestyx offers a few built-in taper functions for commonly-used correlation fun
```python
import jax.numpy as jnp

from dynestyx.inference.filters import EnKFConfig, EnKFLocalizationConfig
import dynestyx as dsx


def gaussian_taper(distances):
length_scale = 3.0
return jnp.exp(-0.5 * (distances / length_scale) ** 2)


localization = EnKFLocalizationConfig(
localization = dsx.configs.EnKFLocalizationConfig(
state_observation_distances=cross_distances,
observation_distances=observation_distances,
taper=gaussian_taper,
)
filter_config = EnKFConfig(localization=localization)
filter_config = dsx.configs.EnKFConfig(localization=localization)
```

For advanced usage, one may provide directly the functions that modify the covariance and cross-covariance. [Cuthbert's localization tutorial](https://state-space-models.github.io/cuthbert/examples/enkf_localization_l96/) shows how to construct these callbacks from distance-based tapers and explains their role in the EnKF update:

```python
from cuthbertlib.ensemble_kalman import construct_tapered_chol_innovation_covariance
from dynestyx.inference.filters import EnKFConfig, EnKFLocalizationFunctions

import dynestyx as dsx


def modify_cross_covariance(cross_covariance, model_inputs):
Expand All @@ -81,8 +82,8 @@ def modify_predicted_observation_covariance(covariance, model_inputs):
return observation_taper * covariance


filter_config = EnKFConfig(
localization=EnKFLocalizationFunctions(
filter_config = dsx.configs.EnKFConfig(
localization=dsx.configs.EnKFLocalizationFunctions(
modify_cross_covariance=modify_cross_covariance,
construct_chol_innovation_covariance=construct_chol_innovation_covariance,
modify_predicted_observation_covariance=modify_predicted_observation_covariance,
Expand All @@ -94,14 +95,15 @@ Projected forecast ensembles remain the raw ensemble even when the observation m

## Discrete Time Configuration Classes

::: dynestyx.inference.configs.filter
::: dynestyx.configs.filter
options:
members:
- BaseFilterConfig
- KFConfig
- EKFConfig
- UKFConfig
- PFConfig
- PFResamplingConfig
- TaperCovarianceFn
- ModifyCrossCovariance
- ConstructCholInnovationCovariance
Expand All @@ -112,20 +114,20 @@ Projected forecast ensembles remain the raw ensemble even when the observation m

## Continuous Time Configuration Classes

::: dynestyx.inference.configs.filter
::: dynestyx.configs.filter
options:
members:
- ContinuousTimeConfig
- ContinuousTimeKFConfig
- ContinuousTimeEKFConfig
- ContinuousTimeKFConfig
- ContinuousTimePFConfig
- ContinuousTimeUKFConfig
- ContinuousTimeDPFConfig
- ContinuousTimeEnKFConfig


## Discrete State-Space Configuration Classes

::: dynestyx.inference.configs.filter
::: dynestyx.configs.filter
options:
members:
- HMMConfig
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ defaults and behavior. To retain that behavior, change existing
`AdaptiveMetropolisConfig` now selects the joint method and has no
`max_adaptation` option. Both methods support only the BlackJAX backend.

::: dynestyx.inference.configs.mcmc
::: dynestyx.configs.mcmc
options:
members:
- BaseMCMCConfig
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

The score rule objects themselves live on the companion [Scoring](../../evaluation/scoring.md) page.

::: dynestyx.evaluation.configs
::: dynestyx.configs.scoring
options:
members:
- ObservationScoringConfig
19 changes: 7 additions & 12 deletions docs/api_reference/public/inference/configs/smoother_configs.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,21 +15,16 @@ instead of assigning to its fields.
## Common Choices

```python
from dynestyx.inference.configs.smoother import (
ContinuousTimeKFSmootherConfig,
EnRTSSmootherConfig,
KFSmootherConfig,
PFSmootherConfig,
)

kf = KFSmootherConfig(filter_source="cd_dynamax")
enrts = EnRTSSmootherConfig(n_particles=100)
pf = PFSmootherConfig(filter_source="cuthbert", n_particles=1_000)
ct_kf = ContinuousTimeKFSmootherConfig()
import dynestyx as dsx

kf = dsx.configs.KFSmootherConfig(filter_source="cd_dynamax")
enrts = dsx.configs.EnRTSSmootherConfig(n_particles=100)
pf = dsx.configs.PFSmootherConfig(filter_source="cuthbert", n_particles=1_000)
ct_kf = dsx.configs.ContinuousTimeKFSmootherConfig()
```

`EnRTSSmootherConfig` inherits the EnKF ensemble-size, inflation, perturbed-observation, and localization options. Localization affects its forward EnKF; the EnRTS backward gain remains the standard unlocalized empirical gain. `PFSmootherConfig` exposes particle-smoother options: `pf_backward_sampling_method`, `pf_mcmc_n_steps`, and `pf_n_smoother_particles`. `ContinuousTimeKFSmootherConfig` exposes `cdlgssm_smoother_type` for the CD-Dynamax continuous-discrete linear Gaussian smoother variant.

::: dynestyx.inference.configs.smoother
::: dynestyx.configs.smoother
options:
filters: []
2 changes: 1 addition & 1 deletion docs/api_reference/public/inference/smoothers.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

```python
from dynestyx import DiscreteTimeSimulator, Smoother
from dynestyx.inference.configs.smoother import KFSmootherConfig
from dynestyx.configs.smoother import KFSmootherConfig

with DiscreteTimeSimulator(n_simulations=4):
with Smoother(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ import dynestyx as dsx
import jax
import jax.numpy as jnp
import numpyro.distributions as dist
from dynestyx.inference.configs.filter import EnKFConfig
from dynestyx.configs.filter import EnKFConfig

dynamics = dsx.DynamicalModel(
initial_condition=dist.Delta(jnp.array([1.0, 2.0]), event_dim=1),
Expand Down
6 changes: 3 additions & 3 deletions docs/api_reference/public/simulators/simulator_configs.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,21 @@ simulator configuration.

## `SimulatorConfig`

::: dynestyx.inference.configs.simulator.SimulatorConfig
::: dynestyx.configs.simulator.SimulatorConfig
options:
show_root_heading: false
show_root_toc_entry: true

## `ODESimulatorConfig`

::: dynestyx.inference.configs.simulator.ODESimulatorConfig
::: dynestyx.configs.simulator.ODESimulatorConfig
options:
show_root_heading: false
show_root_toc_entry: true

## `SDESimulatorConfig`

::: dynestyx.inference.configs.simulator.SDESimulatorConfig
::: dynestyx.configs.simulator.SDESimulatorConfig
options:
show_root_heading: false
show_root_toc_entry: true
Original file line number Diff line number Diff line change
Expand Up @@ -216,7 +216,7 @@
" condition_deterministic=False,\n",
")\n",
"\n",
"with SDESimulator(simulator_config=dsx.SDESimulatorConfig(dt0=1e-2)):\n",
"with SDESimulator(simulator_config=dsx.configs.SDESimulatorConfig(dt0=1e-2)):\n",
" synthetic = predictive(\n",
" key_data,\n",
" predict_times=obs_times,\n",
Expand Down
2 changes: 1 addition & 1 deletion docs/deep_dives/discrete_time_kf_associative_scaling.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
"from numpyro.infer import Predictive\n",
"\n",
"import dynestyx as dsx\n",
"from dynestyx.inference.configs.filter import KFConfig\n",
"from dynestyx.configs.filter import KFConfig\n",
"from dynestyx.inference.integrations.cuthbert.discrete import compute_cuthbert_filter\n",
"from dynestyx import DiscreteTimeSimulator"
]
Expand Down
4 changes: 2 additions & 2 deletions docs/deep_dives/filtering_deterministic_processes.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -100,8 +100,8 @@
" ODESimulatorConfig,\n",
")\n",
"from dynestyx.discretizers import Discretizer, ODEFlowConfig\n",
"from dynestyx.inference.configs.filter import EKFConfig, EnKFConfig\n",
"from dynestyx.inference.configs.smoother import EnRTSSmootherConfig\n",
"from dynestyx.configs.filter import EKFConfig, EnKFConfig\n",
"from dynestyx.configs.smoother import EnRTSSmootherConfig\n",
"from dynestyx.inference.filters import Filter\n",
"from dynestyx.inference.smoothers import Smoother\n",
"\n",
Expand Down
Loading
Loading