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
93 changes: 93 additions & 0 deletions docs/api_reference/public/configurations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Configurations

Use `dynestyx.config` 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.config.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.config.KFConfig`
- `dsx.config.EKFConfig`
- `dsx.config.UKFConfig`
- `dsx.config.EnKFConfig`
- `dsx.config.PFConfig`

### Continuous-time filters

These filters handle continuous-time dynamics with discrete observations.

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

### Finite-state filters

- `dsx.config.HMMConfig`

### Localization and resampling

- `dsx.config.EnKFLocalizationConfig` for distance-based covariance tapering via `EnKFConfig(localization=...)`
- `dsx.config.EnKFLocalizationFunctions` for custom localization callbacks via `EnKFConfig(localization=...)`
- `dsx.config.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.config.KFSmootherConfig`
- `dsx.config.EKFSmootherConfig`
- `dsx.config.UKFSmootherConfig`
- `dsx.config.EnRTSSmootherConfig`
- `dsx.config.PFSmootherConfig`
- `dsx.config.ContinuousTimeKFSmootherConfig`
- `dsx.config.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.config.NUTSConfig`
- `dsx.config.HMCConfig`
- `dsx.config.AdaptiveMetropolisConfig`
- `dsx.config.AdaptiveMWGConfig`
- `dsx.config.SGLDConfig`
- `dsx.config.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.config.DiscretizerConfig` type alias.

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

## Simulators

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

- `dsx.config.ODESimulatorConfig`
- `dsx.config.SDESimulatorConfig`

## Observation scoring

Pass `dsx.config.ObservationScoringConfig` to `dsx.Evaluation(observation_scoring_config=...)`.
See [Scoring configs](inference/configs/scoring_configs.md) for score and predictive sample options.
22 changes: 12 additions & 10 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.config.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.config.EnKFLocalizationConfig(
state_observation_distances=cross_distances,
observation_distances=observation_distances,
taper=gaussian_taper,
)
filter_config = EnKFConfig(localization=localization)
filter_config = dsx.config.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.config.EnKFConfig(
localization=dsx.config.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 @@ -102,6 +103,7 @@ Projected forecast ensembles remain the raw ensemble even when the observation m
- EKFConfig
- UKFConfig
- PFConfig
- PFResamplingConfig
- TaperCovarianceFn
- ModifyCrossCovariance
- ConstructCholInnovationCovariance
Expand All @@ -118,8 +120,8 @@ Projected forecast ensembles remain the raw ensemble even when the observation m
- ContinuousTimeConfig
- ContinuousTimeKFConfig
- ContinuousTimeEKFConfig
- ContinuousTimeKFConfig
- ContinuousTimePFConfig
- ContinuousTimeUKFConfig
- ContinuousTimeDPFConfig
- ContinuousTimeEnKFConfig


Expand Down
17 changes: 6 additions & 11 deletions docs/api_reference/public/inference/configs/smoother_configs.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,17 +15,12 @@ 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.config.KFSmootherConfig(filter_source="cd_dynamax")
enrts = dsx.config.EnRTSSmootherConfig(n_particles=100)
pf = dsx.config.PFSmootherConfig(filter_source="cuthbert", n_particles=1_000)
ct_kf = dsx.config.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.
Expand Down
3 changes: 3 additions & 0 deletions dynestyx/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,10 @@
)
from dynestyx.utils import flatten_draws

from . import config

__all__ = [
"config",
"Covariance",
"ScalarCovariance",
"DiagonalCovariance",
Expand Down
91 changes: 91 additions & 0 deletions dynestyx/config.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
"""Public configuration options for Dynestyx handlers and samplers."""

from dynestyx.evaluation.configs import ObservationScoringConfig
from dynestyx.inference.configs.discretizer import (
DiffraxSampleConfig,
DiscretizerConfig,
EulerMaruyamaConfig,
ExactAffineConfig,
LocalLinearizationConfig,
MeanTrajectoryLinearizationConfig,
ODEFlowConfig,
)
from dynestyx.inference.configs.filter import (
ContinuousTimeDPFConfig,
ContinuousTimeEKFConfig,
ContinuousTimeEnKFConfig,
ContinuousTimeKFConfig,
ContinuousTimeUKFConfig,
EKFConfig,
EnKFConfig,
EnKFLocalizationConfig,
EnKFLocalizationFunctions,
HMMConfig,
KFConfig,
PFConfig,
PFResamplingConfig,
UKFConfig,
)
from dynestyx.inference.configs.mcmc import (
AdaptiveMetropolisConfig,
AdaptiveMWGConfig,
HMCConfig,
MALAConfig,
NUTSConfig,
SGLDConfig,
)
from dynestyx.inference.configs.simulator import (
ODESimulatorConfig,
SDESimulatorConfig,
SimulatorConfig,
)
from dynestyx.inference.configs.smoother import (
ContinuousTimeEKFSmootherConfig,
ContinuousTimeKFSmootherConfig,
EKFSmootherConfig,
EnRTSSmootherConfig,
KFSmootherConfig,
PFSmootherConfig,
UKFSmootherConfig,
)

__all__ = [
"AdaptiveMetropolisConfig",
"AdaptiveMWGConfig",
"ContinuousTimeDPFConfig",
"ContinuousTimeEKFConfig",
"ContinuousTimeEKFSmootherConfig",
"ContinuousTimeEnKFConfig",
"ContinuousTimeKFConfig",
"ContinuousTimeKFSmootherConfig",
"ContinuousTimeUKFConfig",
"DiffraxSampleConfig",
"DiscretizerConfig",
"EKFConfig",
"EKFSmootherConfig",
"EnKFConfig",
"EnKFLocalizationConfig",
"EnKFLocalizationFunctions",
"EnRTSSmootherConfig",
"EulerMaruyamaConfig",
"ExactAffineConfig",
"HMCConfig",
"HMMConfig",
"KFConfig",
"KFSmootherConfig",
"LocalLinearizationConfig",
"MALAConfig",
"MeanTrajectoryLinearizationConfig",
"NUTSConfig",
"ObservationScoringConfig",
"ODEFlowConfig",
"ODESimulatorConfig",
"PFConfig",
"PFResamplingConfig",
"PFSmootherConfig",
"SDESimulatorConfig",
"SGLDConfig",
"SimulatorConfig",
"UKFConfig",
"UKFSmootherConfig",
]
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ nav:
- api_reference/index.md
- Public API:
- Overview: api_reference/public/index.md
- Configurations: api_reference/public/configurations.md
- Models:
- Core Models:
- DynamicalModel: api_reference/public/models/core/dynamical_model.md
Expand Down
Loading