From 65682f8f0ba464ce5928231171d2eb5b1752ac25 Mon Sep 17 00:00:00 2001 From: Matthew Levine Date: Wed, 18 Nov 2026 17:53:05 -0500 Subject: [PATCH] Expose public configs through dynestyx.config --- docs/api_reference/public/configurations.md | 93 +++++++++++++++++++ .../inference/configs/filter_configs.md | 22 +++-- .../inference/configs/smoother_configs.md | 17 ++-- dynestyx/__init__.py | 3 + dynestyx/config.py | 91 ++++++++++++++++++ mkdocs.yml | 1 + 6 files changed, 206 insertions(+), 21 deletions(-) create mode 100644 docs/api_reference/public/configurations.md create mode 100644 dynestyx/config.py diff --git a/docs/api_reference/public/configurations.md b/docs/api_reference/public/configurations.md new file mode 100644 index 00000000..c3ccea11 --- /dev/null +++ b/docs/api_reference/public/configurations.md @@ -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. diff --git a/docs/api_reference/public/inference/configs/filter_configs.md b/docs/api_reference/public/inference/configs/filter_configs.md index 7d753cd4..d89cfc79 100644 --- a/docs/api_reference/public/inference/configs/filter_configs.md +++ b/docs/api_reference/public/inference/configs/filter_configs.md @@ -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) ``` @@ -46,7 +46,7 @@ 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): @@ -54,19 +54,20 @@ def gaussian_taper(distances): 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): @@ -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, @@ -102,6 +103,7 @@ Projected forecast ensembles remain the raw ensemble even when the observation m - EKFConfig - UKFConfig - PFConfig + - PFResamplingConfig - TaperCovarianceFn - ModifyCrossCovariance - ConstructCholInnovationCovariance @@ -118,8 +120,8 @@ Projected forecast ensembles remain the raw ensemble even when the observation m - ContinuousTimeConfig - ContinuousTimeKFConfig - ContinuousTimeEKFConfig - - ContinuousTimeKFConfig - - ContinuousTimePFConfig + - ContinuousTimeUKFConfig + - ContinuousTimeDPFConfig - ContinuousTimeEnKFConfig diff --git a/docs/api_reference/public/inference/configs/smoother_configs.md b/docs/api_reference/public/inference/configs/smoother_configs.md index 65ca82f0..0649edbc 100644 --- a/docs/api_reference/public/inference/configs/smoother_configs.md +++ b/docs/api_reference/public/inference/configs/smoother_configs.md @@ -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. diff --git a/dynestyx/__init__.py b/dynestyx/__init__.py index 321178f2..50c4155b 100644 --- a/dynestyx/__init__.py +++ b/dynestyx/__init__.py @@ -77,7 +77,10 @@ ) from dynestyx.utils import flatten_draws +from . import config + __all__ = [ + "config", "Covariance", "ScalarCovariance", "DiagonalCovariance", diff --git a/dynestyx/config.py b/dynestyx/config.py new file mode 100644 index 00000000..fabf6ec7 --- /dev/null +++ b/dynestyx/config.py @@ -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", +] diff --git a/mkdocs.yml b/mkdocs.yml index f2707207..d0b78a67 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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