diff --git a/docs/api_reference/developer/inference/configs/filter_configs.md b/docs/api_reference/developer/inference/configs/filter_configs.md index 2b6e3421e..a9834ed6f 100644 --- a/docs/api_reference/developer/inference/configs/filter_configs.md +++ b/docs/api_reference/developer/inference/configs/filter_configs.md @@ -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: [] diff --git a/docs/api_reference/developer/inference/configs/mcmc_configs.md b/docs/api_reference/developer/inference/configs/mcmc_configs.md index e08681f26..40bba930c 100644 --- a/docs/api_reference/developer/inference/configs/mcmc_configs.md +++ b/docs/api_reference/developer/inference/configs/mcmc_configs.md @@ -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: [] diff --git a/docs/api_reference/developer/inference/configs/scoring_configs.md b/docs/api_reference/developer/inference/configs/scoring_configs.md index bc3e50d44..ddbd9f891 100644 --- a/docs/api_reference/developer/inference/configs/scoring_configs.md +++ b/docs/api_reference/developer/inference/configs/scoring_configs.md @@ -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 diff --git a/docs/api_reference/developer/inference/configs/smoother_configs.md b/docs/api_reference/developer/inference/configs/smoother_configs.md index 43a12981c..186184333 100644 --- a/docs/api_reference/developer/inference/configs/smoother_configs.md +++ b/docs/api_reference/developer/inference/configs/smoother_configs.md @@ -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: [] diff --git a/docs/api_reference/developer/simulators/simulator_configs.md b/docs/api_reference/developer/simulators/simulator_configs.md index fb98661c9..6ab6c550c 100644 --- a/docs/api_reference/developer/simulators/simulator_configs.md +++ b/docs/api_reference/developer/simulators/simulator_configs.md @@ -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 diff --git a/docs/api_reference/public/configurations.md b/docs/api_reference/public/configurations.md new file mode 100644 index 000000000..8200efe09 --- /dev/null +++ b/docs/api_reference/public/configurations.md @@ -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.` to +`dynestyx.configs.`. 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`. diff --git a/docs/api_reference/public/inference/configs/discretizer_configs.md b/docs/api_reference/public/inference/configs/discretizer_configs.md index 109cdd1d7..4c2be833a 100644 --- a/docs/api_reference/public/inference/configs/discretizer_configs.md +++ b/docs/api_reference/public/inference/configs/discretizer_configs.md @@ -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 diff --git a/docs/api_reference/public/inference/configs/filter_configs.md b/docs/api_reference/public/inference/configs/filter_configs.md index 7d753cd46..0b28b9c8a 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.configs.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.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): @@ -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, @@ -94,7 +95,7 @@ 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 @@ -102,6 +103,7 @@ Projected forecast ensembles remain the raw ensemble even when the observation m - EKFConfig - UKFConfig - PFConfig + - PFResamplingConfig - TaperCovarianceFn - ModifyCrossCovariance - ConstructCholInnovationCovariance @@ -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 diff --git a/docs/api_reference/public/inference/configs/mcmc_configs.md b/docs/api_reference/public/inference/configs/mcmc_configs.md index bc0238c43..a5544ec34 100644 --- a/docs/api_reference/public/inference/configs/mcmc_configs.md +++ b/docs/api_reference/public/inference/configs/mcmc_configs.md @@ -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 diff --git a/docs/api_reference/public/inference/configs/scoring_configs.md b/docs/api_reference/public/inference/configs/scoring_configs.md index 7ffc97318..aeab85509 100644 --- a/docs/api_reference/public/inference/configs/scoring_configs.md +++ b/docs/api_reference/public/inference/configs/scoring_configs.md @@ -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 diff --git a/docs/api_reference/public/inference/configs/smoother_configs.md b/docs/api_reference/public/inference/configs/smoother_configs.md index 65ca82f0d..97d26b5a8 100644 --- a/docs/api_reference/public/inference/configs/smoother_configs.md +++ b/docs/api_reference/public/inference/configs/smoother_configs.md @@ -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: [] diff --git a/docs/api_reference/public/inference/smoothers.md b/docs/api_reference/public/inference/smoothers.md index 1fd0fd7bb..cea6ab0be 100644 --- a/docs/api_reference/public/inference/smoothers.md +++ b/docs/api_reference/public/inference/smoothers.md @@ -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( diff --git a/docs/api_reference/public/relaxations/gaussian_relaxation.md b/docs/api_reference/public/relaxations/gaussian_relaxation.md index 106c973ac..a5116a222 100644 --- a/docs/api_reference/public/relaxations/gaussian_relaxation.md +++ b/docs/api_reference/public/relaxations/gaussian_relaxation.md @@ -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), diff --git a/docs/api_reference/public/simulators/simulator_configs.md b/docs/api_reference/public/simulators/simulator_configs.md index fb98661c9..6ab6c550c 100644 --- a/docs/api_reference/public/simulators/simulator_configs.md +++ b/docs/api_reference/public/simulators/simulator_configs.md @@ -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 diff --git a/docs/deep_dives/continuous_time_lti_profile_likelihood.ipynb b/docs/deep_dives/continuous_time_lti_profile_likelihood.ipynb index 2cefa9753..041665f23 100644 --- a/docs/deep_dives/continuous_time_lti_profile_likelihood.ipynb +++ b/docs/deep_dives/continuous_time_lti_profile_likelihood.ipynb @@ -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", diff --git a/docs/deep_dives/discrete_time_kf_associative_scaling.ipynb b/docs/deep_dives/discrete_time_kf_associative_scaling.ipynb index 98508d402..123bb4193 100644 --- a/docs/deep_dives/discrete_time_kf_associative_scaling.ipynb +++ b/docs/deep_dives/discrete_time_kf_associative_scaling.ipynb @@ -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" ] diff --git a/docs/deep_dives/filtering_deterministic_processes.ipynb b/docs/deep_dives/filtering_deterministic_processes.ipynb index 44528a699..86c157afe 100644 --- a/docs/deep_dives/filtering_deterministic_processes.ipynb +++ b/docs/deep_dives/filtering_deterministic_processes.ipynb @@ -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", diff --git a/docs/deep_dives/gp_drift.ipynb b/docs/deep_dives/gp_drift.ipynb index 5a873c8ad..c79de3de7 100644 --- a/docs/deep_dives/gp_drift.ipynb +++ b/docs/deep_dives/gp_drift.ipynb @@ -403,7 +403,7 @@ } ], "source": [ - "from dynestyx.inference.configs.filter import ContinuousTimeEnKFConfig\n", + "from dynestyx.configs.filter import ContinuousTimeEnKFConfig\n", "\n", "\n", "def model_with_gp_drift(obs_times=None, obs_values=None, predict_times=None):\n", diff --git a/docs/deep_dives/l63_covariance_inflation_scoring.ipynb b/docs/deep_dives/l63_covariance_inflation_scoring.ipynb index 3d2ffb60c..2b0c136c2 100644 --- a/docs/deep_dives/l63_covariance_inflation_scoring.ipynb +++ b/docs/deep_dives/l63_covariance_inflation_scoring.ipynb @@ -87,15 +87,15 @@ " ODESimulator,\n", " ODESimulatorConfig,\n", ")\n", - "from dynestyx.evaluation.configs import ObservationScoringConfig\n", + "from dynestyx.configs.scoring import ObservationScoringConfig\n", "from dynestyx.evaluation.scoring import (\n", " DawidSebastianiScore,\n", " EnergyScore,\n", " GaussianLogProbScore,\n", " ObservationWiseCRPSScore,\n", ")\n", - "from dynestyx.inference.configs.filter import EnKFConfig\n", - "from dynestyx.inference.configs.discretizer import ODEFlowConfig\n", + "from dynestyx.configs.filter import EnKFConfig\n", + "from dynestyx.configs.discretizer import ODEFlowConfig\n", "\n", "warnings.filterwarnings(\"ignore\", message=\"A JAX array is being set as static!\")\n", "\n", diff --git a/docs/deep_dives/l96_localization_hyperparameter_scoring.ipynb b/docs/deep_dives/l96_localization_hyperparameter_scoring.ipynb index a15aaaff5..e3ca92991 100644 --- a/docs/deep_dives/l96_localization_hyperparameter_scoring.ipynb +++ b/docs/deep_dives/l96_localization_hyperparameter_scoring.ipynb @@ -51,14 +51,14 @@ "\n", "import dynestyx as dsx\n", "from dynestyx import DynamicalModel, Evaluation, Filter, LinearGaussianObservation\n", - "from dynestyx.evaluation.configs import ObservationScoringConfig\n", + "from dynestyx.configs.scoring import ObservationScoringConfig\n", "from dynestyx.evaluation.scoring import (\n", " DawidSebastianiScore,\n", " EnergyScore,\n", " GaussianLogProbScore,\n", " ObservationWiseCRPSScore,\n", ")\n", - "from dynestyx.inference.configs.discretizer import ODEFlowConfig\n", + "from dynestyx.configs.discretizer import ODEFlowConfig\n", "from dynestyx.inference.filters import EnKFConfig, EnKFLocalizationConfig\n", "\n", "STATE_DIM = 40\n", @@ -172,7 +172,7 @@ "\n", "H = jnp.eye(STATE_DIM)[OBS_INDICES]\n", "R = OBS_NOISE_STD**2 * jnp.eye(OBS_DIM)\n", - "ode_config = dsx.ODESimulatorConfig(dt0=MODEL_DT)\n", + "ode_config = dsx.configs.ODESimulatorConfig(dt0=MODEL_DT)\n", "\n", "\n", "def l96_dynamics(initial_condition):\n", diff --git a/docs/deep_dives/lti_identifiability_canonicalization.ipynb b/docs/deep_dives/lti_identifiability_canonicalization.ipynb index 1234a0189..d59e112ea 100644 --- a/docs/deep_dives/lti_identifiability_canonicalization.ipynb +++ b/docs/deep_dives/lti_identifiability_canonicalization.ipynb @@ -57,8 +57,8 @@ "from numpyro.infer.util import log_density\n", "\n", "import dynestyx as dsx\n", - "from dynestyx.inference.configs.filter import KFConfig\n", - "from dynestyx.inference.configs.mcmc import AdaptiveMetropolisConfig, NUTSConfig\n", + "from dynestyx.configs.filter import KFConfig\n", + "from dynestyx.configs.mcmc import AdaptiveMetropolisConfig, NUTSConfig\n", "from dynestyx.inference.mcmc import MCMCInference\n", "\n", "SMOKE = os.environ.get(\"LTI_SMOKE\", \"0\") == \"1\"\n", diff --git a/docs/deep_dives/lv_uode.ipynb b/docs/deep_dives/lv_uode.ipynb index 06acf1f0c..9e60bc421 100644 --- a/docs/deep_dives/lv_uode.ipynb +++ b/docs/deep_dives/lv_uode.ipynb @@ -236,7 +236,7 @@ "\n", "\n", "predictive = Predictive(model_with_true_drift, num_samples=1, condition_deterministic=False)\n", - "with SDESimulator(simulator_config=dsx.SDESimulatorConfig(dt0=1e-3)):\n", + "with SDESimulator(simulator_config=dsx.configs.SDESimulatorConfig(dt0=1e-3)):\n", " synthetic = predictive(k_data, predict_times=obs_times)\n", "\n", "obs_values = synthetic[\"f_observations\"][0, 0] # (T, 2) — both species\n", @@ -326,7 +326,7 @@ } ], "source": [ - "from dynestyx.inference.configs.filter import ContinuousTimeEnKFConfig\n", + "from dynestyx.configs.filter import ContinuousTimeEnKFConfig\n", "\n", "\n", "def true_model_with_filter(obs_times=None, obs_values=None):\n", @@ -490,7 +490,7 @@ } ], "source": [ - "from dynestyx.inference.configs.filter import ContinuousTimeEnKFConfig\n", + "from dynestyx.configs.filter import ContinuousTimeEnKFConfig\n", "\n", "def data_conditioned_model(obs_times=None, obs_values=None):\n", " with Filter(filter_config=ContinuousTimeEnKFConfig(\n", diff --git a/docs/deep_dives/mcmc_inference_algorithm_comparison.ipynb b/docs/deep_dives/mcmc_inference_algorithm_comparison.ipynb index a4e3ae3ca..6ffb47fc5 100644 --- a/docs/deep_dives/mcmc_inference_algorithm_comparison.ipynb +++ b/docs/deep_dives/mcmc_inference_algorithm_comparison.ipynb @@ -59,7 +59,7 @@ "from numpyro.infer import Predictive\n", "\n", "from dynestyx import DiscreteTimeSimulator\n", - "from dynestyx.inference.configs.mcmc import (\n", + "from dynestyx.configs.mcmc import (\n", " AdaptiveMetropolisConfig,\n", " AdaptiveMWGConfig,\n", " HMCConfig,\n", diff --git a/docs/deep_dives/observation_scoring_with_cuthbert_enkf.ipynb b/docs/deep_dives/observation_scoring_with_cuthbert_enkf.ipynb index d7e38a9a9..510fd2244 100644 --- a/docs/deep_dives/observation_scoring_with_cuthbert_enkf.ipynb +++ b/docs/deep_dives/observation_scoring_with_cuthbert_enkf.ipynb @@ -80,14 +80,14 @@ " ODESimulatorConfig,\n", ")\n", "from dynestyx.discretizers import Discretizer, ODEFlowConfig\n", - "from dynestyx.evaluation.configs import ObservationScoringConfig\n", + "from dynestyx.configs.scoring import ObservationScoringConfig\n", "from dynestyx.evaluation.scoring import (\n", " DawidSebastianiScore,\n", " EnergyScore,\n", " GaussianLogProbScore,\n", " ObservationWiseCRPSScore,\n", ")\n", - "from dynestyx.inference.configs.filter import EnKFConfig\n", + "from dynestyx.configs.filter import EnKFConfig\n", "from dynestyx.inference.filters import Filter\n", "\n", "STATE_DIM = 3\n", diff --git a/docs/deep_dives/pde/heat_equation_inference.ipynb b/docs/deep_dives/pde/heat_equation_inference.ipynb index 6878a11d7..03ed6c3d1 100644 --- a/docs/deep_dives/pde/heat_equation_inference.ipynb +++ b/docs/deep_dives/pde/heat_equation_inference.ipynb @@ -126,7 +126,7 @@ "\n", "import dynestyx as dsx\n", "from dynestyx import ContinuousTimeStateEvolution, DynamicalModel, LinearGaussianObservation\n", - "from dynestyx.inference.configs.filter import ContinuousTimeKFConfig\n", + "from dynestyx.configs.filter import ContinuousTimeKFConfig\n", "from dynestyx import Simulator, Filter\n", "import diffrax as dfx\n", "\n", @@ -298,7 +298,7 @@ "predictive_model = Predictive(heat_equation_model, num_samples=1)\n", "\n", "with ODESimulator(\n", - " simulator_config=dsx.ODESimulatorConfig(\n", + " simulator_config=dsx.configs.ODESimulatorConfig(\n", " solver=dfx.ImplicitEuler(), # note the implicit solver is used here\n", " stepsize_controller=dfx.PIDController(rtol=1e-3, atol=1e-3),\n", " dt0=dt,\n", @@ -426,7 +426,7 @@ "reparam_model = reparam(heat_equation_model, config={\"f_state_path_params\": TransformReparam()})\n", "\n", "with dsx.LatentPathBuilder(\n", - " ode_simulator_config=dsx.ODESimulatorConfig(\n", + " ode_simulator_config=dsx.configs.ODESimulatorConfig(\n", " solver=dfx.ImplicitEuler(), # note the use of the implicit solver here, unconditionally stable for stiff problems like the heat equation\n", " stepsize_controller=dfx.PIDController(rtol=1e-3, atol=1e-3),\n", " dt0=dt,\n", diff --git a/docs/deep_dives/pde/reaction_diffusion_inference.ipynb b/docs/deep_dives/pde/reaction_diffusion_inference.ipynb index 56c401cf5..0f2ca3520 100644 --- a/docs/deep_dives/pde/reaction_diffusion_inference.ipynb +++ b/docs/deep_dives/pde/reaction_diffusion_inference.ipynb @@ -78,7 +78,7 @@ "\n", "from dynestyx import ODESimulator\n", "from dynestyx import Filter\n", - "from dynestyx.inference.configs.filter import ContinuousTimeEnKFConfig\n", + "from dynestyx.configs.filter import ContinuousTimeEnKFConfig\n", "from numpyro.infer import MCMC, NUTS\n", "\n" ] @@ -210,7 +210,7 @@ "predictive_model = Predictive(reaction_diffusion_equation_model, num_samples=1)\n", "\n", "with ODESimulator(\n", - " dsx.ODESimulatorConfig(\n", + " dsx.configs.ODESimulatorConfig(\n", " solver=dfx.ImplicitEuler(),\n", " stepsize_controller=dfx.PIDController(rtol=1e-3, atol=1e-3),\n", " dt0=dt,\n", @@ -306,7 +306,7 @@ ], "source": [ "with dsx.LatentPathBuilder(\n", - " ode_simulator_config=dsx.ODESimulatorConfig(\n", + " ode_simulator_config=dsx.configs.ODESimulatorConfig(\n", " solver=dfx.ImplicitEuler(),\n", " stepsize_controller=dfx.PIDController(rtol=1e-5, atol=1e-5),\n", " dt0=dt,\n", @@ -501,7 +501,7 @@ "predictive_model = Predictive(reaction_diffusion_equation_model, num_samples=1)\n", "\n", "with ODESimulator(\n", - " dsx.ODESimulatorConfig(\n", + " dsx.configs.ODESimulatorConfig(\n", " solver=dfx.Sil3(), # IMEX solver. You can use any solver you want, but it will warn you if a non-IMEX solver is used.\n", " stepsize_controller=dfx.PIDController(rtol=1e-3, atol=1e-3),\n", " dt0=dt,\n", diff --git a/docs/deep_dives/sde_discretization_comparison.ipynb b/docs/deep_dives/sde_discretization_comparison.ipynb index 20932f63e..7b48b0823 100644 --- a/docs/deep_dives/sde_discretization_comparison.ipynb +++ b/docs/deep_dives/sde_discretization_comparison.ipynb @@ -98,8 +98,8 @@ " LocalLinearizationConfig,\n", " MeanTrajectoryLinearizationConfig,\n", ")\n", - "from dynestyx.inference.configs.filter import EnKFConfig\n", - "from dynestyx.inference.configs.mcmc import NUTSConfig\n", + "from dynestyx.configs.filter import EnKFConfig\n", + "from dynestyx.configs.mcmc import NUTSConfig\n", "from dynestyx.inference.filters import Filter\n", "from dynestyx.inference.mcmc import MCMCInference\n", "\n", diff --git a/docs/faq.md b/docs/faq.md index 865b408d9..40b5a8de5 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -139,7 +139,7 @@ parameters in `model`: ```python import jax.random as jr -from dynestyx.inference.configs.mcmc import NUTSConfig +from dynestyx.configs.mcmc import NUTSConfig from dynestyx.inference.mcmc import MCMCInference with dsx.Filter(filter_config=my_filter_config): diff --git a/docs/logo/make_logo.py b/docs/logo/make_logo.py index 7f20b69d3..99f8f3649 100644 --- a/docs/logo/make_logo.py +++ b/docs/logo/make_logo.py @@ -305,7 +305,7 @@ def potential_fn(x, u, t): rng_key=jr.PRNGKey(seed), predict_times=obs_times, n_simulations=n_particles, - simulator_config=dsx.SDESimulatorConfig(dt0=dt), + simulator_config=dsx.configs.SDESimulatorConfig(dt0=dt), ) if simulation.states is None: raise RuntimeError("SDE simulation returned no state trajectories.") diff --git a/docs/math_intro.md b/docs/math_intro.md index d2f497af7..ac8aabe95 100644 --- a/docs/math_intro.md +++ b/docs/math_intro.md @@ -78,9 +78,9 @@ There are two entry points: Both inspect the model and automatically select discrete-time, ODE, or SDE simulation. For a differential equation, pass the corresponding -[`dsx.ODESimulatorConfig`](api_reference/public/simulators/simulator_configs.md) +[`dsx.configs.ODESimulatorConfig`](api_reference/public/simulators/simulator_configs.md) or -[`dsx.SDESimulatorConfig`](api_reference/public/simulators/simulator_configs.md) +[`dsx.configs.SDESimulatorConfig`](api_reference/public/simulators/simulator_configs.md) through `simulator_config` to control the numerical solver. Discrete-time models do not require a simulator configuration. In every case, `n_simulations` specifies how many independent trajectories to generate. @@ -93,7 +93,7 @@ import jax.random as jr from numpyro.infer import Predictive predict_times = jnp.arange(0.0, 1.0, 0.1) -simulator_config = dsx.SDESimulatorConfig(source="em_scan", dt0=1e-3) +simulator_config = dsx.configs.SDESimulatorConfig(source="em_scan", dt0=1e-3) with dsx.Simulator( simulator_config=simulator_config, diff --git a/docs/tutorials/control/control_optimization.ipynb b/docs/tutorials/control/control_optimization.ipynb index 22ab9b253..7de67333b 100644 --- a/docs/tutorials/control/control_optimization.ipynb +++ b/docs/tutorials/control/control_optimization.ipynb @@ -23,7 +23,7 @@ "\n", "import dynestyx as dsx\n", "from dynestyx.control import DiscreteControlLoopSimulator, filter_state_mean\n", - "from dynestyx.inference.configs.filter import KFConfig\n", + "from dynestyx.configs.filter import KFConfig\n", "from dynestyx.models import DynamicalModel\n", "from dynestyx.models.observations import LinearGaussianObservation\n", "from dynestyx.models.state_evolution import LinearGaussianStateEvolution\n", diff --git a/docs/tutorials/control/controller_demo.ipynb b/docs/tutorials/control/controller_demo.ipynb index 96448f215..649b1c097 100644 --- a/docs/tutorials/control/controller_demo.ipynb +++ b/docs/tutorials/control/controller_demo.ipynb @@ -51,7 +51,7 @@ "import matplotlib.pyplot as plt\n", "import numpyro.distributions as dist\n", "\n", - "from dynestyx.inference.configs.filter import KFConfig\n", + "from dynestyx.configs.filter import KFConfig\n", "from dynestyx.models import DynamicalModel\n", "from dynestyx.models.observations import LinearGaussianObservation\n", "from dynestyx.models.state_evolution import LinearGaussianStateEvolution" @@ -450,7 +450,7 @@ }, "outputs": [], "source": [ - "from dynestyx.inference.configs.filter import EnKFConfig, PFConfig\n", + "from dynestyx.configs.filter import EnKFConfig, PFConfig\n", "from dynestyx.models import FullDiffusion\n", "\n", "state_dim_2d = control_dim_2d = 2\n", diff --git a/docs/tutorials/control/mpc_demo.ipynb b/docs/tutorials/control/mpc_demo.ipynb index 276de4bc3..f3d51a043 100644 --- a/docs/tutorials/control/mpc_demo.ipynb +++ b/docs/tutorials/control/mpc_demo.ipynb @@ -85,7 +85,7 @@ }, "outputs": [], "source": [ - "from dynestyx.inference.configs.filter import EnKFConfig, PFConfig\n", + "from dynestyx.configs.filter import EnKFConfig, PFConfig\n", "from dynestyx.models import FullDiffusion\n", "\n", "state_dim_2d = control_dim_2d = 2\n", diff --git a/docs/tutorials/gentle_intro/04_filtering_nuts_pseudomarginal.ipynb b/docs/tutorials/gentle_intro/04_filtering_nuts_pseudomarginal.ipynb index c4e16ff6a..baf34dc4b 100644 --- a/docs/tutorials/gentle_intro/04_filtering_nuts_pseudomarginal.ipynb +++ b/docs/tutorials/gentle_intro/04_filtering_nuts_pseudomarginal.ipynb @@ -436,7 +436,7 @@ "from numpyro.infer import Predictive\n", "\n", "from dynestyx import Filter, flatten_draws\n", - "from dynestyx.inference.configs.filter import EKFConfig\n", + "from dynestyx.configs.filter import EKFConfig\n", "\n", "\n", "# Use posterior mean for rollout\n", diff --git a/docs/tutorials/gentle_intro/06_continuous_time.ipynb b/docs/tutorials/gentle_intro/06_continuous_time.ipynb index dcea243e0..9271712ac 100644 --- a/docs/tutorials/gentle_intro/06_continuous_time.ipynb +++ b/docs/tutorials/gentle_intro/06_continuous_time.ipynb @@ -128,7 +128,7 @@ " num_samples=1,\n", " condition_deterministic=False,\n", ")\n", - "with SDESimulator(simulator_config=dsx.SDESimulatorConfig(source=\"em_scan\")):\n", + "with SDESimulator(simulator_config=dsx.configs.SDESimulatorConfig(source=\"em_scan\")):\n", " synthetic = predictive(key, predict_times=obs_times_full)\n", "\n", "# Simulators return (n_sim, T, dim); Predictive adds (num_samples,).\n", @@ -521,7 +521,7 @@ " condition_deterministic=False,\n", ")\n", "with SDESimulator(\n", - " simulator_config=dsx.SDESimulatorConfig(source=\"em_scan\"),\n", + " simulator_config=dsx.configs.SDESimulatorConfig(source=\"em_scan\"),\n", " n_simulations=n_sim,\n", "):\n", " with Filter(filter_config=ContinuousTimeEnKFConfig(n_particles=50, record_filtered_states_mean=True, record_filtered_states_cov_diag=True)):\n", @@ -621,7 +621,7 @@ "# Generate a NEW dataset for back-testing (different trajectory)\n", "key_backtest = jr.PRNGKey(123)\n", "times_backtest = jnp.arange(0.0, 15.0, 0.01) # shorter window for demo\n", - "with SDESimulator(simulator_config=dsx.SDESimulatorConfig(source=\"em_scan\")):\n", + "with SDESimulator(simulator_config=dsx.configs.SDESimulatorConfig(source=\"em_scan\")):\n", " synthetic_backtest = Predictive(\n", " l63_model,\n", " params={\"rho\": jnp.array(rho_true)},\n", @@ -654,7 +654,7 @@ " condition_deterministic=False,\n", ")\n", "with SDESimulator(\n", - " simulator_config=dsx.SDESimulatorConfig(source=\"em_scan\"),\n", + " simulator_config=dsx.configs.SDESimulatorConfig(source=\"em_scan\"),\n", " n_simulations=50,\n", "):\n", " with Filter(\n", diff --git a/docs/tutorials/gentle_intro/06b_odes.ipynb b/docs/tutorials/gentle_intro/06b_odes.ipynb index 3e3e34c4d..49e32362f 100644 --- a/docs/tutorials/gentle_intro/06b_odes.ipynb +++ b/docs/tutorials/gentle_intro/06b_odes.ipynb @@ -635,7 +635,7 @@ "from numpyro.infer import Predictive\n", "\n", "from dynestyx import Filter\n", - "from dynestyx.inference.configs.filter import ContinuousTimeEKFConfig\n", + "from dynestyx.configs.filter import ContinuousTimeEKFConfig\n", "\n", "# Build train/test split from synthetic timeline.\n", "times_full = synthetic_samples[\"f_times\"][0, 0, :]\n", diff --git a/docs/tutorials/gentle_intro/08_hierarchical_inference.ipynb b/docs/tutorials/gentle_intro/08_hierarchical_inference.ipynb index 7504a9236..a9c59816f 100644 --- a/docs/tutorials/gentle_intro/08_hierarchical_inference.ipynb +++ b/docs/tutorials/gentle_intro/08_hierarchical_inference.ipynb @@ -228,7 +228,7 @@ "source": [ "import dynestyx as dsx\n", "from dynestyx import LTI_continuous, Simulator\n", - "from dynestyx.inference.configs.filter import ContinuousTimeKFConfig\n", + "from dynestyx.configs.filter import ContinuousTimeKFConfig\n", "from dynestyx.inference.filters import Filter\n", "\n", "\n", @@ -642,7 +642,7 @@ ], "source": [ "from dynestyx import Discretizer\n", - "from dynestyx.inference.configs.filter import EKFConfig\n", + "from dynestyx.configs.filter import EKFConfig\n", "\n", "def conditioned_hierarchical_ou_model():\n", " with Filter(EKFConfig()):\n", diff --git a/docs/tutorials/gentle_intro/09_discrete_smoothing.ipynb b/docs/tutorials/gentle_intro/09_discrete_smoothing.ipynb index b85912576..43fc09429 100644 --- a/docs/tutorials/gentle_intro/09_discrete_smoothing.ipynb +++ b/docs/tutorials/gentle_intro/09_discrete_smoothing.ipynb @@ -82,8 +82,8 @@ "\n", "import dynestyx as dsx\n", "from dynestyx import DiscreteTimeSimulator, Filter, Smoother\n", - "from dynestyx.inference.configs.filter import KFConfig\n", - "from dynestyx.inference.configs.smoother import KFSmootherConfig" + "from dynestyx.configs.filter import KFConfig\n", + "from dynestyx.configs.smoother import KFSmootherConfig" ] }, { diff --git a/docs/tutorials/gentle_intro/10_continuous_smoothing.ipynb b/docs/tutorials/gentle_intro/10_continuous_smoothing.ipynb index 062c990f5..a197cec2b 100644 --- a/docs/tutorials/gentle_intro/10_continuous_smoothing.ipynb +++ b/docs/tutorials/gentle_intro/10_continuous_smoothing.ipynb @@ -84,8 +84,8 @@ "\n", "import dynestyx as dsx\n", "from dynestyx import Filter, Simulator, Smoother\n", - "from dynestyx.inference.configs.filter import ContinuousTimeKFConfig\n", - "from dynestyx.inference.configs.smoother import ContinuousTimeKFSmootherConfig" + "from dynestyx.configs.filter import ContinuousTimeKFConfig\n", + "from dynestyx.configs.smoother import ContinuousTimeKFSmootherConfig" ] }, { diff --git a/docs/tutorials/gentle_intro/11_missing_observations.ipynb b/docs/tutorials/gentle_intro/11_missing_observations.ipynb index b49b58cd2..0ee4b716c 100644 --- a/docs/tutorials/gentle_intro/11_missing_observations.ipynb +++ b/docs/tutorials/gentle_intro/11_missing_observations.ipynb @@ -58,8 +58,8 @@ "\n", "import dynestyx as dsx\n", "from dynestyx import DiscreteTimeSimulator, Filter, Smoother\n", - "from dynestyx.inference.configs.filter import KFConfig, EKFConfig\n", - "from dynestyx.inference.configs.smoother import KFSmootherConfig\n", + "from dynestyx.configs.filter import KFConfig, EKFConfig\n", + "from dynestyx.configs.smoother import KFSmootherConfig\n", "from dynestyx.models import DynamicalModel, LinearGaussianObservation, LinearGaussianStateEvolution\n", "\n", "az.style.use(\"arviz-variat\")\n", diff --git a/docs/tutorials/gentle_intro/11b_missing_observations_latent_path_mcmc.ipynb b/docs/tutorials/gentle_intro/11b_missing_observations_latent_path_mcmc.ipynb index e2c80a0de..9fac8fa35 100644 --- a/docs/tutorials/gentle_intro/11b_missing_observations_latent_path_mcmc.ipynb +++ b/docs/tutorials/gentle_intro/11b_missing_observations_latent_path_mcmc.ipynb @@ -111,7 +111,7 @@ "\n", "import dynestyx as dsx\n", "from dynestyx import DiscreteTimeSimulator, Smoother\n", - "from dynestyx.inference.configs.smoother import KFSmootherConfig\n", + "from dynestyx.configs.smoother import KFSmootherConfig\n", "from dynestyx.models import (\n", " DynamicalModel,\n", " LinearGaussianObservation,\n", diff --git a/docs/tutorials/gentle_intro/11c_missing_observations_hmms.ipynb b/docs/tutorials/gentle_intro/11c_missing_observations_hmms.ipynb index 93fb13b38..bd537d3cf 100644 --- a/docs/tutorials/gentle_intro/11c_missing_observations_hmms.ipynb +++ b/docs/tutorials/gentle_intro/11c_missing_observations_hmms.ipynb @@ -92,7 +92,7 @@ "\n", "import dynestyx as dsx\n", "from dynestyx import DiscreteTimeSimulator, DynamicalModel, Filter\n", - "from dynestyx.inference.configs.filter import HMMConfig\n", + "from dynestyx.configs.filter import HMMConfig\n", "\n", "jax.config.update(\"jax_enable_x64\", True)\n", "az.style.use(\"arviz-variat\")" diff --git a/docs/tutorials/gentle_intro/12_observation_scoring_with_filters.ipynb b/docs/tutorials/gentle_intro/12_observation_scoring_with_filters.ipynb index 71c900d1f..6b5a5bebd 100644 --- a/docs/tutorials/gentle_intro/12_observation_scoring_with_filters.ipynb +++ b/docs/tutorials/gentle_intro/12_observation_scoring_with_filters.ipynb @@ -83,12 +83,12 @@ " GaussianLogProbScore,\n", " ObservationWiseCRPSScore,\n", ")\n", - "from dynestyx.inference.configs.filter import (\n", + "from dynestyx.configs.filter import (\n", " ContinuousTimeEKFConfig,\n", " ContinuousTimeEnKFConfig,\n", " ContinuousTimeUKFConfig,\n", ")\n", - "from dynestyx.evaluation.configs import ObservationScoringConfig\n", + "from dynestyx.configs.scoring import ObservationScoringConfig\n", "\n", "jax.config.update(\"jax_enable_x64\", True)\n", "warnings.filterwarnings(\n", diff --git a/docs/tutorials/gentle_intro/13_enkf_localization.ipynb b/docs/tutorials/gentle_intro/13_enkf_localization.ipynb index 1db7a3edc..29a456d44 100644 --- a/docs/tutorials/gentle_intro/13_enkf_localization.ipynb +++ b/docs/tutorials/gentle_intro/13_enkf_localization.ipynb @@ -56,7 +56,7 @@ "\n", "import dynestyx as dsx\n", "from dynestyx import DynamicalModel, Filter, LinearGaussianObservation\n", - "from dynestyx.inference.configs.discretizer import ODEFlowConfig\n", + "from dynestyx.configs.discretizer import ODEFlowConfig\n", "from dynestyx.inference.filters import EnKFConfig, EnKFLocalizationConfig\n", "\n", "jax.config.update(\"jax_enable_x64\", True)\n", @@ -151,7 +151,7 @@ "\n", "\n", "observation_matrix = jnp.eye(STATE_DIM)[OBSERVED_INDICES]\n", - "ode_config = dsx.ODESimulatorConfig(dt0=MODEL_DT)\n", + "ode_config = dsx.configs.ODESimulatorConfig(dt0=MODEL_DT)\n", "\n", "\n", "def lorenz96_dynamics(initial_condition):\n", diff --git a/dynestyx/__init__.py b/dynestyx/__init__.py index 321178f2e..e08fbf072 100644 --- a/dynestyx/__init__.py +++ b/dynestyx/__init__.py @@ -1,22 +1,21 @@ """Dynestyx package.""" +import warnings from importlib.metadata import version __version__ = version("dynestyx") +# Load the model and handler primitives before configs that use shared types. +from dynestyx.handlers import condition, plate, sample + +# isort: split from dynestyx.api import log_prob, simulate from dynestyx.discretizers import ( Discretizer, discretize_dynamics, discretize_state_evolution, ) -from dynestyx.evaluation import Evaluation, ObservationScoringConfig -from dynestyx.handlers import condition, plate, sample -from dynestyx.inference.configs.simulator import ( - ODESimulatorConfig, - SDESimulatorConfig, - SimulatorConfig, -) +from dynestyx.evaluation import Evaluation from dynestyx.inference.filters import Filter from dynestyx.inference.latent.builder import LatentPathBuilder from dynestyx.inference.smoothers import Smoother @@ -77,7 +76,29 @@ ) from dynestyx.utils import flatten_draws +from . import configs + +_DEPRECATED_CONFIG_EXPORTS = ( + "ObservationScoringConfig", + "ODESimulatorConfig", + "SDESimulatorConfig", + "SimulatorConfig", +) + + +def __getattr__(name: str): + if name in _DEPRECATED_CONFIG_EXPORTS: + warnings.warn( + f"dynestyx.{name} is deprecated; use dynestyx.configs.{name} instead.", + DeprecationWarning, + stacklevel=2, + ) + return getattr(configs, name) + raise AttributeError(f"module {__name__!r} has no attribute {name!r}") + + __all__ = [ + "configs", "Covariance", "ScalarCovariance", "DiagonalCovariance", @@ -125,7 +146,6 @@ "FilterModelInputs", "LatentStateResult", "Result", - "ObservationScoringConfig", "SimulatedResult", "StructuredSimulatedResult", "log_prob", @@ -137,11 +157,9 @@ "LinearGaussianObservation", "LinearGaussianObservationParams", "GaussianObservation", - "ODESimulatorConfig", - "SDESimulatorConfig", - "SimulatorConfig", "DiscreteTimeSimulator", "ODESimulator", "SDESimulator", "Simulator", + *_DEPRECATED_CONFIG_EXPORTS, ] diff --git a/dynestyx/_defaults.py b/dynestyx/_defaults.py index fe424f557..e34fe5876 100644 --- a/dynestyx/_defaults.py +++ b/dynestyx/_defaults.py @@ -65,6 +65,13 @@ def _default_handlers( # Imports stay local: these interpretations themselves import this module. import numpyro.distributions as dist + from dynestyx.configs.discretizer import DiffraxSampleConfig + from dynestyx.configs.filter import ( + EnKFConfig, + HMMConfig, + KFConfig, + PFConfig, + ) from dynestyx.discretization.gaussian import _ConfiguredGaussianStateEvolution from dynestyx.discretization.ode_flow import _ODEFlowStateEvolution from dynestyx.discretizers import ( @@ -73,13 +80,6 @@ def _default_handlers( discretize_dynamics, ) from dynestyx.inference.checkers import _validate_inference_supported_model_classes - from dynestyx.inference.configs.discretizer import DiffraxSampleConfig - from dynestyx.inference.configs.filter import ( - EnKFConfig, - HMMConfig, - KFConfig, - PFConfig, - ) from dynestyx.inference.filters import Filter from dynestyx.inference.latent.builder import LatentPathBuilder from dynestyx.models import ( diff --git a/dynestyx/api.py b/dynestyx/api.py index a4d69fd97..3fa705566 100644 --- a/dynestyx/api.py +++ b/dynestyx/api.py @@ -9,10 +9,10 @@ import jax.random as jr from jaxtyping import Array, PRNGKeyArray, PyTree, Real +from dynestyx.configs.filter import BaseFilterConfig +from dynestyx.configs.simulator import SimulatorConfig from dynestyx.handlers import _validate_and_prepare from dynestyx.inference.checkers import _validate_inference_supported_model_classes -from dynestyx.inference.configs.filter import BaseFilterConfig -from dynestyx.inference.configs.simulator import SimulatorConfig from dynestyx.inference.state_paths.reconstruct import reconstruct_state_path from dynestyx.inference.state_paths.score import compute_state_path_log_prob from dynestyx.models import DynamicalModel diff --git a/dynestyx/configs/__init__.py b/dynestyx/configs/__init__.py new file mode 100644 index 000000000..e39342c32 --- /dev/null +++ b/dynestyx/configs/__init__.py @@ -0,0 +1,109 @@ +"""Public configuration options for Dynestyx handlers and samplers.""" + +from typing import TYPE_CHECKING + +from dynestyx.configs.discretizer import ( + DiffraxSampleConfig, + DiscretizerConfig, + EulerMaruyamaConfig, + ExactAffineConfig, + LocalLinearizationConfig, + MeanTrajectoryLinearizationConfig, + ODEFlowConfig, +) +from dynestyx.configs.filter import ( + ContinuousTimeDPFConfig, + ContinuousTimeEKFConfig, + ContinuousTimeEnKFConfig, + ContinuousTimeKFConfig, + ContinuousTimeUKFConfig, + EKFConfig, + EnKFConfig, + EnKFLocalizationConfig, + EnKFLocalizationFunctions, + HMMConfig, + KFConfig, + PFConfig, + PFResamplingConfig, + UKFConfig, +) +from dynestyx.configs.mcmc import ( + AdaptiveMetropolisConfig, + AdaptiveMWGConfig, + HMCConfig, + MALAConfig, + NUTSConfig, + SGLDConfig, +) +from dynestyx.configs.simulator import ( + ODESimulatorConfig, + SDESimulatorConfig, + SimulatorConfig, +) +from dynestyx.configs.smoother import ( + ContinuousTimeEKFSmootherConfig, + ContinuousTimeKFSmootherConfig, + EKFSmootherConfig, + EnRTSSmootherConfig, + KFSmootherConfig, + PFSmootherConfig, + UKFSmootherConfig, +) + +if TYPE_CHECKING: + from dynestyx.configs.scoring import ObservationScoringConfig + + +def __getattr__(name: str): + if name == "ObservationScoringConfig": + # The evaluation package imports the scoring config for its handler. + from dynestyx.configs.scoring import ObservationScoringConfig + + return ObservationScoringConfig + raise AttributeError(f"module {__name__!r} has no attribute {name!r}") + + +def __dir__() -> list[str]: + return sorted(set(globals()) | set(__all__)) + + +__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/dynestyx/configs/discretizer.py b/dynestyx/configs/discretizer.py new file mode 100644 index 000000000..94b7a7d52 --- /dev/null +++ b/dynestyx/configs/discretizer.py @@ -0,0 +1,425 @@ +"""Configuration objects for continuous-to-discrete approximations.""" + +from __future__ import annotations + +import abc +import dataclasses + +import diffrax as dfx + +from dynestyx.configs.simulator import ( + ODESimulatorConfig, + SDESimulatorConfig, +) +from dynestyx.utils.validation import _validate_nonnegative_float + + +def _default_diffrax_sde_solver() -> SDESimulatorConfig: + return SDESimulatorConfig( + source="diffrax", solver=dfx.Euler(), dt0=1e-2, max_steps=100_000 + ) + + +@dataclasses.dataclass +class BaseDiscretizerConfig(abc.ABC): + r"""Base class for continuous-to-discrete configuration objects. + + Do not instantiate this marker class directly. Pass one of its concrete + subclasses to `Discretizer`. For default settings, pass None + as the config to `Discretizer`. + """ + + +@dataclasses.dataclass +class ODEFlowConfig(BaseDiscretizerConfig): + r"""Numerical flow transition for a deterministic ODE. + + For the controlled ODE + + $$ + \dot X_s=f(X_s,u_k,s), + $$ + + this config numerically integrates from ``t_now`` to ``t_next`` while + holding ``u_k`` fixed. With endpoint + $\phi(x,u_k,t_{\mathrm{now}},t_{\mathrm{next}})$, the returned + transition is a Delta distribution when ``jitter_scale == 0``. For + positive ``jitter_scale`` it is an independent Normal distribution with + mean $\phi$, component scale ``jitter_scale``, and covariance + ``jitter_scale**2 * I``. + + All Diffrax settings come from the existing ``ODESimulatorConfig``. + + Attributes: + simulator_config (ODESimulatorConfig): Diffrax ODE solver settings. + Defaults to ``ODESimulatorConfig()``. + jitter_scale (float): Finite, nonnegative component scale added + after integrating the flow. Defaults to ``0.0``. + """ + + simulator_config: ODESimulatorConfig = dataclasses.field( + default_factory=ODESimulatorConfig + ) + jitter_scale: float = 0.0 + + def __post_init__(self) -> None: + _validate_nonnegative_float("jitter_scale", self.jitter_scale) + + +@dataclasses.dataclass +class EulerMaruyamaConfig(BaseDiscretizerConfig): + r"""Euler--Maruyama Gaussian transition for a general Itô SDE. + + This is the inexpensive, general-purpose discretization. Consider + + $$ + dX_s=f(X_s,u_k,s)\,ds+L(X_s,u_k,s)\,dW_s, + \qquad + a(x,u,s)=L(x,u,s)L(x,u,s)^\top , + $$ + + on \(s\in[t_k,t_{k+1}]\), where \(W_s\) is standard Brownian motion, + \(h=t_{k+1}-t_k>0\), and the control \(u_k\) is held fixed over the + interval. Euler--Maruyama freezes both coefficients at its left endpoint: + + $$ + X_{k+1}\mid X_k=x,u_k + \;\approx\; + \mathcal N\!\left( + x+h f(x,u_k,t_k), + h\,a(x,u_k,t_k)+\epsilon I + \right), + $$ + + where \(\epsilon\) is `covariance_jitter`. + + The method applies to nonlinear drift and state-, time-, or + control-dependent diffusion. Under the usual global Lipschitz and growth + assumptions it has strong order \(1/2\) and weak order \(1\); for additive + noise its strong order improves to \(1\). See Kloeden and Platen (1992) + for more details. It requires one drift and one diffusion evaluation per + transition, but a single large step can poorly represent nonlinear, stiff, + or rapidly varying dynamics. + + Attributes: + covariance_jitter (float): Nonnegative \(\epsilon\) added to the + transition covariance as \(\epsilon I\). Defaults to `0.0`. + Positive jitter changes the stochastic model and should be chosen + explicitly rather than treated as an invisible numerical fix. + + ??? note "Algorithm Reference" + - Särkkä, S., & Solin, A. (2019). *Applied Stochastic Differential + Equations*. Cambridge University Press, Algorithm 8.1 and + Equations (8.28)--(8.30). + [Online book](https://users.aalto.fi/~asolin/sde-book/sde-book.pdf). + - Kloeden, P. E., & Platen, E. (1992). *Numerical Solution of + Stochastic Differential Equations*. Springer, Chapter 10. + [https://doi.org/10.1007/978-3-662-12616-5](https://doi.org/10.1007/978-3-662-12616-5). + """ + + covariance_jitter: float = 0.0 + + def __post_init__(self) -> None: + _validate_nonnegative_float("covariance_jitter", self.covariance_jitter) + + +@dataclasses.dataclass +class ExactAffineConfig(BaseDiscretizerConfig): + r"""Exact discrete transition for an affine SDE with additive noise. + + Use this config only when the continuous transition has an `AffineDrift`, + constant diffusion, and no potential. For the Itô SDE + + $$ + dX_s=(F X_s+B u_k+b)\,ds+L\,dW_s + $$ + + over an interval of length \(h=t_{k+1}-t_k>0\), with standard Brownian + motion and a held control \(u_k\), the exact conditional transition is + + $$ + X_{k+1}\mid X_k=x,u_k + \sim + \mathcal N(A_hx+B_hu_k+b_h,\;Q_h+\epsilon I), + $$ + + with + + $$ + A_h=e^{Fh},\qquad + B_h=\int_0^h e^{Fs}B\,ds,\qquad + b_h=\int_0^h e^{Fs}b\,ds, + $$ + + and + + $$ + Q_h=\int_0^h e^{Fs}LL^\top e^{F^\top s}\,ds. + $$ + + The implementation uses an augmented matrix exponential for the forcing + terms and evaluates the Van Loan covariance on a safely scaled interval + before composing it to the requested interval. This avoids overflowing the + growing block associated with a stable, stiff drift. It never forms + \(F^{-1}\), so singular drift matrices are supported. With + `covariance_jitter=0`, the transition is exact up to floating-point error + for every positive interval length, including nonuniform observation grids. + It preserves a linear Gaussian state-evolution representation and therefore + enables exact Kalman filtering when the rest of the model is also linear + Gaussian. + + Matrix exponentials cost cubic time in the augmented state dimension and + can be expensive when many distinct interval lengths are used. Drifts + not explicitly marked as affine/constant, state-dependent diffusion, and + potentials are rejected. Singular \(Q_h\) requires positive jitter. + + Attributes: + covariance_jitter (float): Nonnegative \(\epsilon\) added to \(Q_h\) + as \(\epsilon I\). Defaults to `0.0`. + + ??? note "Algorithm Reference" + - Van Loan, C. F. (1978). Computing integrals involving the matrix + exponential. *IEEE Transactions on Automatic Control*, 23(3), + 395--404. + [https://doi.org/10.1109/TAC.1978.1101743](https://doi.org/10.1109/TAC.1978.1101743). + - Särkkä, S., & Svensson, L. (2023). *Bayesian Filtering and + Smoothing*, 2nd ed. Cambridge University Press, Theorem 4.3 and + Lemma A.9. + [Online book](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). + - Axelsson, P., & Gustafsson, F. (2015). Discrete-time solutions to + the continuous-time differential Lyapunov equation. *IEEE + Transactions on Automatic Control*, 60(3), 632--643. + [https://doi.org/10.1109/TAC.2014.2353112](https://doi.org/10.1109/TAC.2014.2353112). + """ + + covariance_jitter: float = 0.0 + + def __post_init__(self) -> None: + _validate_nonnegative_float("covariance_jitter", self.covariance_jitter) + + +@dataclasses.dataclass +class LocalLinearizationConfig(BaseDiscretizerConfig): + r"""Locally linearized Gaussian transition with frozen additive noise. + + This method is intended for nonlinear drift with structurally constant, + additive diffusion. For the Itô SDE + + $$ + dX_s=f(X_s,u_k,s)\,ds+L\,dW_s, + $$ + + define, at the left endpoint \(x=X_{t_k}\), + + $$ + f_0=f(x,u_k,t_k),\qquad + J=\left.\frac{\partial f}{\partial x}\right|_{(x,u_k,t_k)} . + $$ + + With standard Brownian motion, \(h=t_{k+1}-t_k>0\), and \(u_k\) held + fixed, approximate the original process by + + $$ + dZ_s=\left[f_0+J(Z_s-x)\right]ds+L\,dW_s,\qquad Z_0=x. + $$ + + Its exact Gaussian transition has + + $$ + m_h=x+\int_0^h e^{Js}f_0\,ds, + \qquad + P_h=\int_0^h e^{Js}LL^\top e^{J^\top s}\,ds, + $$ + + and this config returns + \(\mathcal N(m_h,P_h+\epsilon I)\), where \(\epsilon\) is + `covariance_jitter`. + + The method is exact for affine drift with additive diffusion. With some amount + of nonlinearity, it can be more accurate than Euler--Maruyama, but at higher + cost, since Jacobians must be computed. + + State-, time-, or control-dependent diffusion are rejected. + The returned object is a Gaussian transition distribution, compatible + with any method using Gaussian transitions. Degenerate transition covariance + requires explicit positive jitter. + + Attributes: + covariance_jitter (float): Nonnegative \(\epsilon\) added to \(P_h\) + as \(\epsilon I\). Defaults to `0.0`. + + ??? note "Algorithm Reference" + - Särkkä, S., & Svensson, L. (2023). *Bayesian Filtering and + Smoothing*, 2nd ed. Cambridge University Press, Theorem 4.18. + [Online book](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). + - Ozaki, T. (1992). A bridge between nonlinear time series models and + nonlinear stochastic dynamical systems: A local linearization + approach. *Statistica Sinica*, 2(1), 113--135. + [Article](https://www3.stat.sinica.edu.tw/statistica/j2n1/j2n16/j2n16.htm). + """ + + covariance_jitter: float = 0.0 + + def __post_init__(self) -> None: + _validate_nonnegative_float("covariance_jitter", self.covariance_jitter) + + +@dataclasses.dataclass +class MeanTrajectoryLinearizationConfig(BaseDiscretizerConfig): + r"""Gaussian moment transition linearized along the conditional mean. + + This config integrates a first-order Gaussian assumed-density + approximation for the Itô SDE + + $$ + dX_s=f(X_s,u_k,s)\,ds+L(X_s,u_k,s)\,dW_s,\qquad + a(x,u,s)=L(x,u,s)L(x,u,s)^\top . + $$ + + On \(s\in[t_k,t_{k+1}]\), standard Brownian motion is assumed and \(u_k\) + is held fixed. Starting from the deterministic conditional state + + $$ + m(t_k)=x,\qquad P(t_k)=0, + $$ + + integrate + + $$ + \dot m_s=f(m_s,u_k,s), + $$ + + $$ + \dot P_s=J_sP_s+P_sJ_s^\top+a(m_s,u_k,s), + \qquad + J_s=\frac{\partial f}{\partial x}(m_s,u_k,s), + $$ + + and return + \(\mathcal N(m(t_{k+1}),P(t_{k+1})+\epsilon I)\). + + This approximation supports nonlinear drift and state-, time-, or + control-dependent diffusion. It is exact for affine drift with additive + diffusion up to the numerical ODE solver tolerance. Relative to a + left-endpoint local linearization, it updates the Jacobian along the mean + trajectory. + + Every transition performs a joint mean/covariance ODE solve and evaluates a + state Jacobian at each right-hand-side call, so it is considerably more + expensive than Euler--Maruyama. A singular final covariance requires explicit + positive jitter. + + Attributes: + ode_solver (ODESimulatorConfig): Existing Diffrax ODE configuration + used unchanged for the joint mean/covariance integration. + Defaults to `ODESimulatorConfig()`. + covariance_jitter (float): Nonnegative \(\epsilon\) added to the final + covariance as \(\epsilon I\). Defaults to `0.0`. + + ??? note "Algorithm Reference" + - Särkkä, S., & Solin, A. (2019). *Applied Stochastic Differential + Equations*. Cambridge University Press, Algorithm 9.4, + Equation (9.15), and Algorithm 9.8 with Equation (9.28). + [Online book](https://users.aalto.fi/~asolin/sde-book/sde-book.pdf). + - Särkkä, S., & Svensson, L. (2023). *Bayesian Filtering and + Smoothing*, 2nd ed. Cambridge University Press, Theorem 4.13 and + Algorithm 4.14. + [Online book](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). + - Särkkä, S., & Sarmavuori, J. (2013). Gaussian filtering and + smoothing for continuous-discrete dynamic systems. *Signal + Processing*, 93(2), 500--510. + [https://doi.org/10.1016/j.sigpro.2012.09.002](https://doi.org/10.1016/j.sigpro.2012.09.002). + """ + + ode_solver: ODESimulatorConfig = dataclasses.field( + default_factory=ODESimulatorConfig + ) + covariance_jitter: float = 0.0 + + def __post_init__(self) -> None: + _validate_nonnegative_float("covariance_jitter", self.covariance_jitter) + + +@dataclasses.dataclass +class DiffraxSampleConfig(BaseDiscretizerConfig): + r"""Sample-only transition obtained by solving each interval with Diffrax. + + This config is for simulation, ensemble Kalman filtering, bootstrap + particle filtering, and genealogy-tracing particle smoothing when a + numerical SDE path solver is preferable to an analytic transition + approximation. For + + $$ + dX_s=f(X_s,u_k,s)\,ds+L(X_s,u_k,s)\,dW_s, + $$ + + over \(s\in[t_k,t_{k+1}]\), with \(u_k\) held fixed, it defines the + transition operationally as + + $$ + X_{k+1} + = + \Psi_{\mathrm{Diffrax}} + (x,u_k,t_k,t_{k+1};\omega), + $$ + + where \(\Psi_{\mathrm{Diffrax}}\) is the numerical solution selected by + `sde_solver` and \(\omega\) is generated from the key passed to + `sample` or `rsample`. A fresh Brownian tree is used for each Markov + interval. The transition stores no PRNG key and performs no solve when it + is constructed; solving is deferred until sampling so model shape probes + remain cheap. + + This transition has no tractable density in general. It supports + `sample_shape`, reparameterized `rsample`, JIT compilation, external `vmap`, + deterministic replay with the same key, `DiscreteTimeSimulator`, cuthbert + EnKF, and cuthbert bootstrap PF. A cuthbert `PFSmootherConfig` using + genealogy tracing is also compatible because it follows stored ancestors + without evaluating a transition density. `log_prob`, `mean`, and `variance` + raise targeted errors at the point where they are requested. Kalman, + extended/unscented Kalman, + density-based particle smoothers, latent-path scoring, and proposals that + require transition densities or analytic moments are not supported. + + The implementation supports any Diffrax solver that operates from ordinary + Brownian increments, including `diffrax.Euler()` and `diffrax.Heun()`. + The default inner config selects `diffrax.Euler()`, the Euler--Maruyama + solver, with a default step size of `1e-2`. Cost scales with the number of + internal solver steps and requested samples. `source="em_scan"` is rejected. + Reverse-mode differentiation through the default + `diffrax.RecursiveCheckpointAdjoint()` requires a finite + `sde_solver.max_steps`; the default bound is `100_000` steps per interval. + + Attributes: + sde_solver (SDESimulatorConfig): Existing SDE simulator configuration + used for each interval. It must have `source="diffrax"`. Defaults + to `SDESimulatorConfig(source="diffrax", + solver=diffrax.Euler(), dt0=1e-2, max_steps=100_000)`. + + ??? note "Algorithm Reference" + - Kidger, P. Diffrax documentation: + [SDE solvers](https://docs.kidger.site/diffrax/api/solvers/sde_solvers/) + and the + [SDE solver/order table](https://docs.kidger.site/diffrax/devdocs/SDE_solver_table/). + """ + + sde_solver: SDESimulatorConfig = dataclasses.field( + default_factory=_default_diffrax_sde_solver + ) + + def __post_init__(self) -> None: + if self.sde_solver.source != "diffrax": + raise ValueError( + "DiffraxSampleConfig requires sde_solver.source='diffrax', " + f"got source={self.sde_solver.source!r}." + ) + + +type DiscretizerConfig = ( + ODEFlowConfig + | EulerMaruyamaConfig + | ExactAffineConfig + | LocalLinearizationConfig + | MeanTrajectoryLinearizationConfig + | DiffraxSampleConfig +) diff --git a/dynestyx/configs/filter.py b/dynestyx/configs/filter.py new file mode 100644 index 000000000..3490e3c01 --- /dev/null +++ b/dynestyx/configs/filter.py @@ -0,0 +1,1017 @@ +"""Filter configuration dataclasses. Shared by dispatchers and integration backends.""" + +import abc +import dataclasses +import math +from collections.abc import Callable +from typing import Any, Literal, Protocol + +import jax.numpy as jnp +import jax.random as jr +from cuthbertlib.types import ScalarArrayLike +from jaxtyping import Array, ArrayLike, PRNGKeyArray + +from dynestyx.utils.validation import _validate_nonnegative_float + +ResamplingBaseMethod = Literal["systematic", "multinomial", "stratified"] +ResamplingDifferentiableMethod = Literal["stop_gradient", "straight_through", "soft"] +FilterEmissionOrder = Literal["zeroth", "first", "second"] +FilterStateOrder = Literal["zeroth", "first", "second"] + +CuthbertOnlyFilterSource = Literal["cuthbert"] +CDDynamaxOnlyFilterSource = Literal["cd_dynamax"] +DynestyxOnlyFilterSource = Literal["dynestyx"] +FilterSource = ( + CuthbertOnlyFilterSource | CDDynamaxOnlyFilterSource | DynestyxOnlyFilterSource +) +CuthbertOrCDDynamaxFilterSource = CuthbertOnlyFilterSource | CDDynamaxOnlyFilterSource + +TaperCovarianceFn = Callable[[Array], Array] + + +class ModifyCrossCovariance(Protocol): + """Modify an empirical state-observation cross-covariance.""" + + def __call__( + self, + cross_covariance: Array, + model_inputs: Any, + ) -> Array: + """Return a cross-covariance with the same shape as the input.""" + ... + + +class ConstructCholInnovationCovariance(Protocol): + """Construct a generalized factor of an EnKF innovation covariance.""" + + def __call__( + self, + normalized_observation_deviations: Array, + chol_observation_covariance: Array, + model_inputs: Any, + ) -> Array: + """Return an observation-by-observation innovation factor.""" + ... + + +class ModifyPredictedObservationCovariance(Protocol): + """Modify an empirical covariance used for predictive scoring.""" + + def __call__( + self, + predicted_observation_covariance: Array, + model_inputs: Any, + ) -> Array: + """Return a predictive covariance with the same shape as the input.""" + ... + + +@dataclasses.dataclass(frozen=True) +class EnKFLocalizationConfig: + r"""Distance-based covariance localization for a discrete-time EnKF. + + The state-observation taper modifies the empirical cross-covariance used + in every EnKF update. Supplying ``observation_distances`` additionally + localizes the empirical observation covariance in the innovation matrix + and in Dynestyx predictive-observation scores. + + Built-in ``"gaspari_cohn"`` and ``"gaussian"`` tapers require a positive + scalar ``taper_scale``. A custom callable receives a distance matrix and + must close over any hyperparameters itself, so ``taper_scale`` must then be + ``None``. Custom callables may close over JAX tracers and remain + differentiable. + + Attributes: + state_observation_distances: Matrix with shape + ``(state_dim, observation_dim)``. + taper_scale: Full support radius for Gaspari-Cohn or length scale for + the Gaussian taper. Must be ``None`` for a custom taper callable. + taper: Built-in taper name or a callable mapping distances to taper + values with the same shape. + observation_distances: Optional symmetric observation-by-observation + distance matrix with a zero diagonal. When omitted, only the + state-observation cross-covariance is localized. + """ + + state_observation_distances: ArrayLike + taper_scale: ScalarArrayLike | None = None + taper: Literal["gaspari_cohn", "gaussian"] | TaperCovarianceFn = "gaspari_cohn" + observation_distances: ArrayLike | None = None + + def __post_init__(self): + self._validate() + + def _validate(self): + """Check configuration at construction and again before resolution.""" + if callable(self.taper): + if self.taper_scale is not None: + raise ValueError( + "EnKFLocalizationConfig with a custom taper callable requires " + "taper_scale=None; close over custom hyperparameters in the callable." + ) + return + + if not isinstance(self.taper, str) or self.taper not in { + "gaspari_cohn", + "gaussian", + }: + raise ValueError( + "Unsupported EnKF localization taper " + f"{self.taper!r}; expected 'gaspari_cohn', 'gaussian', or a callable." + ) + if self.taper_scale is None: + raise ValueError( + f"EnKFLocalizationConfig(taper={self.taper!r}) requires a positive " + "scalar taper_scale." + ) + if jnp.asarray(self.taper_scale).shape != (): + raise ValueError("EnKF localization taper_scale must be a scalar.") + + +@dataclasses.dataclass(frozen=True) +class EnKFLocalizationFunctions: + """Advanced callback-based localization for a discrete-time EnKF. + + The first two callbacks follow Cuthbert's high-level EnKF callback + signatures. The predictive covariance callback receives the raw empirical + observation covariance and the same per-time model inputs. An innovation + constructor and predictive covariance modifier must be supplied together + so filtering likelihoods and Dynestyx predictive scores use consistent + covariance localization. + """ + + modify_cross_covariance: ModifyCrossCovariance | None = None + construct_chol_innovation_covariance: ConstructCholInnovationCovariance | None = ( + None + ) + modify_predicted_observation_covariance: ( + ModifyPredictedObservationCovariance | None + ) = None + + def __post_init__(self): + self._validate() + + def _validate(self): + """Check configuration at construction and again before resolution.""" + callbacks = ( + self.modify_cross_covariance, + self.construct_chol_innovation_covariance, + self.modify_predicted_observation_covariance, + ) + if all(callback is None for callback in callbacks): + raise ValueError( + "EnKFLocalizationFunctions requires at least one localization callback." + ) + for callback in callbacks: + if callback is not None and not callable(callback): + raise TypeError("EnKF localization callbacks must be callable or None.") + if (self.construct_chol_innovation_covariance is None) != ( + self.modify_predicted_observation_covariance is None + ): + raise ValueError( + "construct_chol_innovation_covariance and " + "modify_predicted_observation_covariance must be supplied together." + ) + + +@dataclasses.dataclass(frozen=True) +class BaseFilterConfig(abc.ABC): + r"""Shared configuration options inherited by all filter configs. + + You do not instantiate this class directly; use one of the concrete + subclasses (e.g. `KFConfig`, `PFConfig`). + + Config fields are immutable after construction. Use `dataclasses.replace` + to create an updated config; nested objects such as dictionaries are not + recursively frozen. + + The `record_*` fields let you save intermediate filtering outputs into the + NumPyro trace as `numpyro.deterministic` sites, making them accessible + after inference (e.g. for plotting filtered trajectories). `None` defers + to the backend's default for that quantity. + + Attributes: + record_filtered_states_mean (bool | None): Save the posterior mean + \(\mathbb{E}[x_t \mid y_{1:t}]\) at each time step. + record_filtered_states_cov (bool | None): Save the full posterior + covariance at each step. Can be large — prefer + `record_filtered_states_cov_diag` for high-dimensional states. + record_filtered_states_cov_diag (bool | None): Save only the marginal + variances (diagonal of the covariance) at each step. + record_filtered_states_chol_cov (bool | None): Save the Cholesky + factor of the posterior covariance (Gaussian filters only). + record_filtered_particles (bool | None): Save the full particle array + at each step (particle-based filters only). + record_filtered_log_weights (bool | None): Save the log importance + weights at each step (particle-based filters only). + include_predicted_observations (bool): Collect supported one-step-ahead + predictive-observation outputs in ``ConditionedResult``. This is + independent of whether those outputs are recorded to a NumPyro + trace. Defaults to `True`. + record_predicted_observations_mean (bool): Save the one-step-ahead + predicted observation mean at each observation time, before + conditioning on that observation. Defaults to `True`. + record_predicted_observations_cov (bool): Save the backend predicted + observation covariance before observation noise is added. Defaults + to `True`. + record_predicted_observations_ensemble (bool): Save the backend + predicted observation ensemble before observation noise is added + (ensemble filters only). Defaults to `True` when available. + record_max_elems (int): Hard cap on total scalar elements saved across + all `record_*` sites. Prevents accidentally filling device memory + for long sequences or large state spaces. Defaults to `100_000`. + cov_rescaling (float | None): Multiply all predicted covariances by + this factor before the update. Values slightly above `1.0` + implement covariance inflation, which can improve robustness when + the model is misspecified. `None` disables rescaling. + crn_seed (PRNGKeyArray | None): Fix the PRNG key for stochastic filters + (EnKF, PF). Useful when differentiating through the filter: + a fixed key makes the randomness a deterministic function of model + parameters. `None` draws a fresh key each call. + warn (bool): Whether or not to suppress warnings from filtering backends. + Defaults to `True`. + filter_source (FilterSource | None): Internal backend library. Set by + each subclass; rarely needs to be changed manually. + extra_filter_kwargs (dict): Extra keyword arguments passed directly to + the backend. Useful for advanced backend-specific options. + """ + + extra_filter_kwargs: dict = dataclasses.field(default_factory=dict) + warn: bool = True + record_filtered_states_mean: bool | None = None + record_filtered_states_cov: bool | None = None + record_filtered_states_cov_diag: bool | None = None + record_filtered_particles: bool | None = None + record_filtered_log_weights: bool | None = None + record_filtered_states_chol_cov: bool | None = None + include_predicted_observations: bool = True + record_predicted_observations_mean: bool = True + record_predicted_observations_cov: bool = True + record_predicted_observations_ensemble: bool = True + record_max_elems: int = 100_000 + filter_source: FilterSource | None = None + cov_rescaling: float | None = None + crn_seed: PRNGKeyArray | None = None + + +@dataclasses.dataclass(frozen=True) +class EnKFBaseConfig(BaseFilterConfig): + """Shared options for discrete- and continuous-time EnKF configs.""" + + n_particles: int = 30 + crn_seed: PRNGKeyArray | None = dataclasses.field( + default_factory=lambda: jr.PRNGKey(0) + ) + perturb_measurements: bool | None = None + inflation_delta: float | None = None + localization: EnKFLocalizationConfig | EnKFLocalizationFunctions | None = None + recorded_filtered_states_cov_jitter: float = ( + 1e-5 # this is good for float32, may want to reduce for float64 + ) + ensemble_subspace: bool | None = None + + def __post_init__(self): + if self.ensemble_subspace and ( + self.localization is not None or self.filter_source != "cuthbert" + ): + raise ValueError( + "ensemble_subspace=True requires the Cuthbert backend " + "and no localization." + ) + if self.localization is not None and not isinstance( + self.localization, + EnKFLocalizationConfig | EnKFLocalizationFunctions, + ): + raise TypeError( + "EnKFConfig.localization must be EnKFLocalizationConfig, " + "EnKFLocalizationFunctions, or None." + ) + reserved_hooks = { + "modify_cross_covariance", + "construct_chol_innovation_covariance", + "modify_predicted_observation_covariance", + } + conflicts = sorted(reserved_hooks.intersection(self.extra_filter_kwargs)) + if conflicts: + raise ValueError( + "EnKF localization callback names are reserved in " + f"extra_filter_kwargs: {', '.join(conflicts)}. Use " + "EnKFLocalizationFunctions via EnKFConfig.localization instead." + ) + + # Check that the jitter is nonnegative float + _validate_nonnegative_float( + "recorded_filtered_states_cov_jitter", + self.recorded_filtered_states_cov_jitter, + ) + + +@dataclasses.dataclass(frozen=True) +class EnKFConfig(EnKFBaseConfig): + r"""Ensemble Kalman Filter (EnKF) for discrete-time models. + + The **default filter** for discrete-time models. A good general-purpose + filter for nonlinear models with Gaussian observations. Works with any + differentiable or non-differentiable dynamics and scales well to moderate + state dimensions. Cheaper per-step than the particle filter, but assumes + observations are approximately Gaussian given the ensemble. + + The observation noise covariance must be **state-independent** (it may + still depend on time or controls). Using a state-dependent scale with the + cuthbert backend raises a `ValueError`; if you need heteroscedastic noise, + use `PFConfig` instead. + + The primary tuning knob is `n_particles`, with more particles providing + more accurate results at the cost of higher compute. + If the ensemble collapses over long trajectories, increase + `inflation_delta` slightly (e.g. `0.05`–`0.2`). + + Supports missing observations via NaNs. + + Attributes: + n_particles (int): Number of ensemble members. More members give a + better covariance estimate at higher compute cost. Defaults to + `30`. + crn_seed (PRNGKeyArray | None): Fixed PRNG key for the ensemble. Defaults + to `jr.PRNGKey(0)`, i.e., common random numbers are used. This + can reduce variance in gradient-based learning, but introduces + further bias. + perturb_measurements (bool | None): Add noise to observations before + the ensemble update (stochastic EnKF). Set `False` for the + square-root variant. `None` defers to the backend default. + inflation_delta (float | None): Scale ensemble anomalies by + \(\sqrt{1 + \delta}\) before the update to prevent collapse. + `None` disables inflation. + localization (EnKFLocalizationConfig | EnKFLocalizationFunctions | None): + Optional structured covariance localization. Distance-based + localization provides built-in Gaussian and Gaspari-Cohn tapers or + accepts a custom covariance callable. Advanced users can instead + supply Cuthbert-compatible callbacks. + ensemble_subspace (bool | None): Perform the update in ensemble space. + `None` selects it when `n_particles < observation_dim` and + localization is absent. `True` forces it and `False` disables it. + Available only with the Cuthbert backend and without localization. + This may be more efficient when `n_particles` < `state_dim`, and almost + certainly more efficient if `n_particles` << `state_dim`, but may interfere + with localization. See [the Cuthbert documentation](https://state-space-models.github.io/cuthbert/api_cuthbert/ensemble_kalman/ensemble_kalman_filter/) + for more details. + recorded_filtered_states_cov_jitter (float): Nonnegative \(\epsilon\) added to + the **recorded** filtered-state covariance as \(\epsilon I\). + This only affects the covariance when converted to a `MultivariateNormal` or `LowRankMultivariateNormal` + distribution (notably those returned in `ConditionedResult.dists`); it never + enters the EnKF update, the filter recursion, or the marginal + likelihood. + When `n_particles - 1 < state_dim`, the ensemble covariance is singular, + this regularization is necessary to give the recorded distributions a well-defined density (sampling will work nonetheless). + Defaults to `1e-5`. Will work for variance around 1, but may need a bigger value + for larger magnitudes and may want to reduce when using float64. Pass `0.0` for the exact, unregularised covariance. + filter_source (FilterSource): Backend. Defaults to `"cuthbert"`. + + ??? note "Algorithm Reference" + The ensemble Kalman filter comprises ensemble members $x_t^{(i)}, i = 1, \ldots, N_{\text{particles}}$. + There are many implementation tricks in the EnKF; we describe the basic version here. + + For each time step \(t\), the ensemble is propagated forward by the transition model: + + $$ + \hat{x}_t^{(i)} = f(x_t^{(i)}, u_t, t_t) + \epsilon_t^{(i)}, + $$ + + where \(u_t\) is the control input at time \(t\) and \(t_t\) is the time of the transition, + and \(\epsilon_t^{(i)} \sim \mathcal{N}(0, Q)\) is the process noise. + + Each ensemble member is then updated using observations: + + $$ + x_t^{(i)} = \hat{x}_t^{(i)} + \hat{K}_t^{(i)} \left(y_t - h(x_t^{(i)}, u_t, t_t)\right), + $$ + + where $\hat{K}_t^{(i)}$ is the Kalman gain for the \(i\)-th ensemble member, computed as + + $$ + \hat{K}_t^{(i)} = \hat{P}_t^{(i)} H^\top (H \hat{P}_t^{(i)} H^\top + R)^{-1}, + $$ + + where $\hat{P}_t^{(i)}$ is the empirical covariance of the particles, and $R$ is the + covariance of the observation model. + + The resulting estimator is known to be biased for non-linear observations, but is often rather + robust in practice to moderate nonlinearities. It is particualrly effective for high-dimensional + inverse problems, where other particle methods like particle filters often struggle. + + References: + + - The implementation details are due to: Sanz-Alonso, D., Stuart, A. M., & Taeb, A. (2018). + Inverse problems and data assimilation. [arXiv:1810.06191](https://arxiv.org/abs/1810.06191). + - For a classical reference to the ensemble Kalman filter, see: Evensen, G. (2003). + The ensemble Kalman filter: Theoretical formulation and practical implementation. Ocean Dynamics, 53(4), 343-367. + - The solution using automatic differentiation for nonlinear dynamics is due to: Chen, Y., Sanz-Alonso, D., & Willett, R. (2022). + Autodifferentiable ensemble Kalman filters. SIAM Journal on Mathematics of Data Science, 4(2), 801-833. + [Available Online](https://epubs.siam.org/doi/abs/10.1137/21M1434477). + """ + + filter_source: CuthbertOnlyFilterSource = "cuthbert" + + +@dataclasses.dataclass(frozen=True) +class PFResamplingConfig: + """Resampling strategy for particle-based filters. + + The defaults (`"systematic"`, `"stop_gradient"`) are appropriate for most + workflows. The resampling step includes both a non-differentiable base method, + and a differentiable method for handling gradients. + + For most problems, especially with bootstrap particle filters, the `stop_gradient` method is preferred. + The `soft` method can be useful when a non-bootstrap PF is used and gradients are required to flow through the resampling step. + The `straight_through` approach is biased on the backwards pass, and is not recommended, but is okay to use for gradient-free inference. + + Attributes: + base_method (ResamplingBaseMethod): Algorithm used to draw new + particles from the weight distribution. `"systematic"` *(default)* + has the lowest variance and is preferred in most cases. + `"multinomial"` and `"stratified"` are also available. + differential_method (ResamplingDifferentiableMethod): How gradients + are handled across the discrete resampling step. + `"stop_gradient"` *(default)* treats indices as constants. + `"straight_through"` or `"soft"` allow gradients to pass through + (needed for gradient-based training of model parameters). + softness (float): Temperature for soft resampling. Only used when + `differential_method="soft"`. Lower values are closer to non-differentiable resampling, + and higher values are closer to the differentiable method. Defaults to `0.7`. + + ??? note "Algorithm Reference" + The stop gradient method provides an unbiased score estimate for the marginal likelihood via the classical Fisher estimate. + This is accomplished directly through automatic differentiation. For non-bootstrap filters, the proposal estimates will be biased. + + The soft resampling method provides biased score estimates, but propagates gradients through the reasmpling step. It is fast. + + References: + + - For the stop_gradient method, see: Ścibior, A., & Wood, F. (2021). + Differentiable particle filtering without modifying the forward pass. [arXiv:2106.10314](https://arxiv.org/abs/2106.10314). + - For the soft method, see: Karkus, P., Hsu, D., & Lee, W. S. (2018, October). Particle filter networks with application to visual localization. + In Conference on Robot Learning (pp. 169-178). [Available Online](https://proceedings.mlr.press/v87/karkus18a.html). + - For a recent review of differentiable particle filters, see: Brady, J. J., Cox, B., Li, Y., & Elvira, V. (2025). + PyDPF: A Python Package for Differentiable Particle Filtering. [arXiv:2510.25693](https://arxiv.org/abs/2510.25693). + """ + + base_method: ResamplingBaseMethod = "systematic" + differential_method: ResamplingDifferentiableMethod = "stop_gradient" + softness: float = 0.7 + + +@dataclasses.dataclass(frozen=True) +class PFBaseConfig(BaseFilterConfig): + """Shared options for discrete- and continuous-time PF configs.""" + + n_particles: int = 1_000 + resampling_method: PFResamplingConfig = dataclasses.field( + default_factory=PFResamplingConfig + ) + ess_threshold_ratio: float = 0.7 + + +@dataclasses.dataclass(frozen=True) +class PFConfig(PFBaseConfig): + r"""Bootstrap Particle Filter (PF) for discrete-time models. + + The most flexible filter: works with any model, including non-Gaussian + observations and highly nonlinear dynamics. + The main cost is that accuracy scales with the number of particles, so + large state dimensions can become expensive. + + The primary tuning knob is `n_particles`. Estimates will generally get better + and less noisy with more particles, but introduces a linear computational cost. + `ess_threshold_ratio` controls the frequency of resampling; sampling more frequently + can help avoid particle degeneracy, but also increases variance. + + NaN-valued `obs_values` are allowed, but they are not treated specially by + the particle filter. Whether missing observations work correctly is up to + the user-specified transition and observation functions to handle NaNs + appropriately. A warning is emitted when NaNs are detected in `obs_values`. + + Attributes: + n_particles (int): Number of particles. More particles give a lower- + variance log-likelihood estimate at linear compute cost. Defaults + to `1_000`. + resampling_method (PFResamplingConfig): Controls the resampling + algorithm and gradient behaviour. See `PFResamplingConfig`. + Defaults to systematic resampling with stop-gradient. + ess_threshold_ratio (float): Resampling fires when the effective + sample size drops below `ess_threshold_ratio * n_particles`. + `1.0` → always resample; `0.0` → never. Defaults to `0.7`. + filter_source (FilterSource): Backend. Defaults to `"cuthbert"`, which is currently the only available implementation. + + ??? note "Algorithm Reference" + At each step, particles are propagated through the transition and + reweighted by the observation likelihood. The resulting empirical distribution + is asymptotically exact to the true filtering distribution as the number of particles goes to infinity. + The marginal log-likelihood without a resampling step is estimated as: + + \[ + \log p(y_{1:T}) \approx \sum_{t=1}^T \log \frac{1}{N} + \sum_{i=1}^N \tilde{w}_t^{(i)} + \] + + where $\tilde{w}_t^{(i)}$ is the are unnormalized weights of each particle. + + There are several different resampling algorithms available, which result in different + approximations of the score function $\nabla_\theta \log p(y_{1:T} | \theta)$. + For more information on these options, see `PFResamplingConfig`. + + References: + + - For a classical reference to particle filters, see: Doucet, A., De Freitas, N., & Gordon, N. (2001). An Introduction to Sequential Monte Carlo Methods. + In Sequential Monte Carlo Methods in Practice (pp. 3-14). New York, NY: Springer New York. + - For a more modern textbook, see Chapter 11.4 of: Särkkä, S., & Svensson, L. (2023). + Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. + [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). + - For a more recent review of differentiable particle filters, see: Brady, J. J., Cox, B., Li, Y., & Elvira, V. (2025). + PyDPF: A Python Package for Differentiable Particle Filtering. [arXiv:2510.25693](https://arxiv.org/abs/2510.25693). + """ + + filter_source: CuthbertOnlyFilterSource = "cuthbert" + + +@dataclasses.dataclass(frozen=True) +class EKFConfig(BaseFilterConfig): + r"""Extended Kalman Filter (EKF) for discrete-time models. + + The EKF linearizes nonlinear dynamics at the current mean estimate + via a first-order Taylor expansion. It is fast and simple, but may + not work well for strongly nonlinear models. The Taylor series expansion + is automatically performed via Jax autodiff. + + This is exact (but wasteful) for linear-Gaussian models. + + In the current interface with the `cd_dynamax` discrete-time backend, + time-varying models silently ignore absolute time arguments. + For genuinely time-varying discrete-time models, use a + backend/configuration that preserves absolute time semantics, such as + `EnKFConfig(filter_source="cuthbert")`. Only use + `filter_source="cd_dynamax"` for time-invariant models. + + Does not support missing observations (data cannot have NaNs). + + Attributes: + filter_emission_order (FilterEmissionOrder): Linearisation order for + the observation function. `"first"` *(default)* is the standard + Jacobian-based EKF. `"second"` reduces bias for strongly curved + observation maps at the cost of Hessian computation. `"zeroth"` + skips observation linearisation. + filter_source (FilterSource): Backend. Defaults to `"cuthbert"`. + + ??? note "Algorithm Reference" + The EKF propagates a Gaussian approximation + \(\mathcal{N}(\hat x_{t|t}, P_{t|t})\) through Jacobian + linearizations of \(f\) and \(h\): + + \[ + \hat x_{t|t-1} = f(\hat x_{t-1|t-1}), + \quad P_{t|t-1} = F_t P_{t-1|t-1} F_t^\top + Q_t + \] + + where $F_t$ is the Jacobian of $f$ at $\hat x_{t|t-1}$, + and proceeds via the typical Kalman update. + + References: + + - The `cuthbert` implementation of the EKF is based on the `taylor_kf` module therein. + See the [cuthbert documentation](https://state-space-models.github.io/cuthbert/cuthbert_api/gaussian/taylor/) for more information. + - For a more modern textbook reference, see Chapter 7 of: Särkkä, S., & Svensson, L. (2023). + Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. + [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). + """ + + filter_source: CuthbertOrCDDynamaxFilterSource = "cuthbert" + filter_emission_order: FilterEmissionOrder = "first" + + +@dataclasses.dataclass(frozen=True) +class KFConfig(BaseFilterConfig): + r"""Kalman Filter (KF) for discrete-time linear-Gaussian models. + + The exact Bayesian filter for linear-Gaussian state-space models; requires + a model built with `LTI_discrete` or using + `LinearGaussianStateEvolution` + `LinearGaussianObservation`. For + nonlinear Gaussian models, use `EKFConfig`, `UKFConfig`, or `EnKFConfig` instead. + + Supports missing observations via NaNs when `filter_source="cuthbert"`. Does not support missing observations (data cannot have NaNs) when `filter_source="cd_dynamax"`. + + Time-varying linear-Gaussian models (callable `(t_now, t_next)` / `(t,)` + parameters on `LinearGaussianStateEvolution` / + `LinearGaussianObservation`) are supported only with + `filter_source="cuthbert"`; `filter_source="cd_dynamax"` raises + `TypeError` for callable parameters. + + Attributes: + filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. + associative (bool | None): Whether to enable cuthbert's associative + parallel-in-time scan. This is only supported when + `filter_source="cuthbert"`. Defaults to `None`, which selects + an associative scan if `filter_source="cuthbert"`, and a + sequential scan otherwise. + + ??? note "Algorithm Reference" + When the dynamics and observation process of a dynamical system are both linear-Gaussian, + the recursive updates can be computed in closed form. + + This proceeds via a "prediction" step, where the mean and covariance are propagated forward in time, + and an "update" step, where the mean and covariance are updated with the observation. + + The prediction step is given by: + + $$ + \hat x_{t|t-1} = A \hat x_{t-1|t-1} + b, + \quad P_{t|t-1} = A P_{t-1|t-1} A^\top + Q + $$ + + The update step is given by: + + $$ + \hat x_{t|t} = \hat x_{t|t-1} + K_t (y_t - H \hat x_{t|t-1}), + \quad P_{t|t} = (I - K_t H) P_{t|t-1} + $$ + + where $K_t$ is the Kalman gain. + + The Kalman gain is given by: + + $$ + K_t = P_{t|t-1} H^\top (H P_{t|t-1} H^\top + R)^{-1} + $$ + + where $H$ is the Jacobian of $h$ at $\hat x_{t|t-1}$. + + There are variants to the particular algorithm; the `cuthbert` implementation is the so-called "square root" form. + This provides a more numerically stable implementation of the Kalman filter. + + References: + + - For the classsical reference, see: Kalman, R. E. (1960). + A New Approach to Linear Filtering and Prediction Problems. Journal of Basic Engineering, 82(1), 35-45. + - For a more modern textbook reference, see Chapter 6 of: Särkkä, S., & Svensson, L. (2023). + Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. + [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). + - For more details on the `cuthbert` implementation, see the [cuthbert documentation](https://state-space-models.github.io/cuthbert/cuthbert_api/gaussian/kalman/). + """ + + filter_source: CuthbertOrCDDynamaxFilterSource = "cd_dynamax" + associative: bool | None = None + + def __post_init__(self): + if self.associative is None: + object.__setattr__(self, "associative", self.filter_source == "cuthbert") + + if self.associative and self.filter_source != "cuthbert": + raise ValueError( + "KFConfig(associative=True) is only supported with " + "filter_source='cuthbert'." + ) + + +@dataclasses.dataclass(frozen=True) +class UKFConfig(BaseFilterConfig): + r"""Unscented Kalman Filter (UKF) for discrete-time models. + + A derivative-free Gaussian filter that handles stronger nonlinearities + than the EKF by propagating a small, deterministic set of *sigma points* + through the dynamics. No Jacobians are computed. Slightly more expensive + than the EKF but often more accurate on curved manifolds. + + The default parameters (`alpha`, `beta`, `kappa`) work well for most + problems; they rarely need to be changed. + + In the current interface with the `cd_dynamax` discrete-time backend, + time-varying models silently ignore absolute time arguments. + For genuinely time-varying discrete-time models, use a + backend/configuration that preserves absolute time semantics, such as + `EKFConfig(filter_source="cuthbert")`. Only use + `filter_source="cd_dynamax"` for time-invariant models. + + Does not support missing observations (data cannot have NaNs). + + Attributes: + alpha (float): Spread of sigma points around the current mean. + Smaller → tighter cluster; larger → sigma points reach further. + Defaults to \(\sqrt{3}\). + beta (int): Encodes prior knowledge about the distribution shape. + `2` is optimal for Gaussians. Defaults to `2`. + kappa (int): Secondary scaling parameter. Defaults to `1`. + filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. + + ??? note "Algorithm Reference" + For a state of dimension \(n\), \(2n+1\) sigma points are placed as: + + $$ + \mathcal{X}_0 = \hat x, \quad + \mathcal{X}_i = \hat x \pm \sqrt{(n + \lambda) P}_i, \quad + \lambda = \alpha^2 (n + \kappa) - n + $$ + + Each sigma point is propagated through \(f\) and \(h\); the outputs + are recombined with weights depending on \(\alpha, \beta, \kappa\) to + recover the predicted mean and covariance. + + References: + - For the original paper, see: Julier, S. J., & Uhlmann, J. K. (1997). New extension of the Kalman filter to nonlinear systems. SPIE Proceedings, 3068. + - For a more modern textbook reference, see Section 8.8 of: Särkkä, S., & Svensson, L. (2023). + Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. + [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). + """ + + alpha: float = math.sqrt(3) + beta: int = 2 + kappa: int = 1 + filter_source: CDDynamaxOnlyFilterSource = "cd_dynamax" + + +@dataclasses.dataclass(frozen=True) +class ContinuousTimeConfig: + """Solver options shared by all continuous-discrete filter configs. + + Between observation times, the filter propagates a distribution (or + ensemble/particles) forward in continuous time by solving an ODE/SDE + numerically. These options control that solver. + + Attributes: + filter_state_order (FilterStateOrder): Accuracy of the continuous-time + propagation between observations. `"first"` *(default)* propagates + both mean and covariance (sufficient for most problems). `"zeroth"` + propagates only the mean (faster, less accurate). `"second"` adds + a higher-order correction for strongly nonlinear drifts. + diffeqsolve_max_steps (int): Maximum ODE solver steps between any two + consecutive observations. Increase if the solver hits this limit + (stiff dynamics or very long inter-observation gaps). Defaults to + `1_000`. + diffeqsolve_dt0 (float): Initial step-size hint for the solver. + Adaptive solvers adjust this automatically; fixed-step solvers + use it as the constant step. Defaults to `0.01`. + diffeqsolve_kwargs (dict): Additional kwargs forwarded to + `diffrax.diffeqsolve` (e.g. `solver`, `stepsize_controller`, + `adjoint`). Defaults to `{}`. + """ + + filter_state_order: FilterStateOrder = "first" + diffeqsolve_max_steps: int = 1_000 + diffeqsolve_dt0: float = 0.01 + diffeqsolve_kwargs: dict = dataclasses.field(default_factory=dict) + + +@dataclasses.dataclass(frozen=True) +class ContinuousTimeKFConfig(BaseFilterConfig, ContinuousTimeConfig): + r"""Continuous-discrete Kalman Filter (CD-KF). + + The exact Bayesian filter for continuous-time linear-Gaussian models. + Use this when your model was built with `LTI_continuous`. For nonlinear + SDEs, use `ContinuousTimeEKFConfig`, `ContinuousTimeUKFConfig`, or + `ContinuousTimeEnKFConfig`. + + Does not support missing observations (data cannot have NaNs). + + Inherits solver options from `ContinuousTimeConfig` and recording + options from `BaseFilterConfig`. + + Attributes: + filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. + + ??? note "Algorithm Reference" + Between observations the mean and covariance evolve via the + Kalman–Bucy ODEs: + + $$ + \dot{\hat x} = A \hat x + B u, + \quad \dot P = A P + P A^\top + L Q L^\top + $$ + + At each observation the standard Kalman update is applied. + + References: + + - For a modern textbook reference, see Chapter 10.6 of: Särkkä, S., & Solin, A. (2019). + Applied Stochastic Differential Equations. Cambridge University Press. + [Available Online](https://users.aalto.fi/~asolin/sde-book/sde-book.pdf). + """ + + filter_source: CDDynamaxOnlyFilterSource = "cd_dynamax" + + +@dataclasses.dataclass(frozen=True) +class ContinuousTimeEnKFConfig(EnKFBaseConfig, ContinuousTimeConfig): + r"""Continuous-discrete Ensemble Kalman Filter (CD-EnKF). + + The **default filter** for continuous-time models. Each ensemble member + is propagated forward by solving the SDE between observations; the + ensemble Kalman update is applied at observation times. Works with any + SDE model without requiring gradients. + + Does not support missing observations (data cannot have NaNs). + + Localization is not available in this continuous-time backend. To localize + a deterministic continuous-time model, wrap it in `Discretizer` and use + the Cuthbert-backed discrete `EnKFConfig`. + + See `EnKFConfig` for particle/ensemble tuning options and + `ContinuousTimeConfig` for solver options. + + Attributes: + filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. + + ??? note "Algorithm Reference" + References: + + - The implementation details are due to: Sanz-Alonso, D., Stuart, A. M., & Taeb, A. (2018). + Inverse problems and data assimilation. [arXiv:1810.06191](https://arxiv.org/abs/1810.06191). + - For a classical reference to the ensemble Kalman filter, see: Evensen, G. (2003). + The ensemble Kalman filter: Theoretical formulation and practical implementation. Ocean Dynamics, 53(4), 343-367. + - The solution using automatic differentiation for nonlinear dynamics is due to: Chen, Y., Sanz-Alonso, D., & Willett, R. (2022). + Autodifferentiable ensemble Kalman filters. SIAM Journal on Mathematics of Data Science, 4(2), 801-833. + [Available Online](https://epubs.siam.org/doi/abs/10.1137/21M1434477). + """ + + filter_source: CDDynamaxOnlyFilterSource = "cd_dynamax" + + def __post_init__(self): + super().__post_init__() + if self.localization is not None: + raise ValueError( + "ContinuousTimeEnKFConfig does not support localization. Wrap the " + "continuous model in Discretizer and use the Cuthbert-backed " + "discrete EnKFConfig instead." + ) + + +@dataclasses.dataclass(frozen=True) +class ContinuousTimeDPFConfig(PFBaseConfig, ContinuousTimeConfig): + r"""Continuous-discrete Differentiable Particle Filter (CD-DPF). + + Particle filter for continuous-time SDEs. Particles are propagated by + solving the SDE between observations; importance weights are updated at + each observation time. Supports non-Gaussian observations and arbitrary + nonlinear dynamics. + + Does not support missing observations (data cannot have NaNs). + + Uses multinomial resampling by default (vs. systematic in `PFConfig`) + for better compatibility with gradient-based training. + + See `PFConfig` for particle tuning options and `ContinuousTimeConfig` + for solver options. + + Attributes: + filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. + resampling_method (PFResamplingConfig): Defaults to + `PFResamplingConfig(base_method="multinomial")`. + + ??? note "Algorithm Reference" + The bootstrap version of the continuous-discrete PF is the same as the discrete-time PF version. + See `PFConfig` for more information. + """ + + filter_source: CDDynamaxOnlyFilterSource = "cd_dynamax" + resampling_method: PFResamplingConfig = dataclasses.field( + default_factory=lambda: PFResamplingConfig(base_method="multinomial") + ) + + +@dataclasses.dataclass(frozen=True) +class ContinuousTimeEKFConfig(EKFConfig, ContinuousTimeConfig): + r"""Continuous-discrete Extended Kalman Filter (CD-EKF). + + Fast Gaussian filter for mildly nonlinear SDEs. Requires differentiable + dynamics (JAX autodiff is used). The moment equations for the Gaussian + approximation are solved between observations and a Kalman update is + applied at each observation. + + Does not support missing observations (data cannot have NaNs). + + See `EKFConfig` for linearisation options and `ContinuousTimeConfig` + for solver options. + + Attributes: + filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. + + ??? note "Algorithm Reference" + References: + + - For a modern textbook reference, see Chapter 10.7 of: Särkkä, S., & Solin, A. (2019). + Applied Stochastic Differential Equations. Cambridge University Press. + [Available Online](https://users.aalto.fi/~asolin/sde-book/sde-book.pdf). + """ + + filter_source: CDDynamaxOnlyFilterSource = "cd_dynamax" + + +@dataclasses.dataclass(frozen=True) +class ContinuousTimeUKFConfig(UKFConfig, ContinuousTimeConfig): + """Continuous-discrete Unscented Kalman Filter (CD-UKF). + + Derivative-free Gaussian filter for nonlinear SDEs. Sigma points are + propagated through the SDE between observations; the unscented transform + is applied at each observation update. More accurate than CD-EKF for + strongly nonlinear drifts without requiring Jacobians. + + Does not support missing observations (data cannot have NaNs). + + See `UKFConfig` for sigma-point tuning options and `ContinuousTimeConfig` + for solver options. + + Attributes: + filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. + + ??? note "Algorithm Reference" + References: + + - For a modern textbook reference, see Section 10.8 of: Särkkä, S., & Solin, A. (2019). + Applied Stochastic Differential Equations. Cambridge University Press. + [Available Online](https://users.aalto.fi/~asolin/sde-book/sde-book.pdf). + """ + + filter_source: CDDynamaxOnlyFilterSource = "cd_dynamax" + + +DiscreteTimeConfigs: tuple[type, ...] = ( + EnKFConfig, + PFConfig, + EKFConfig, + KFConfig, + UKFConfig, +) + +ContinuousTimeConfigs: tuple[type, ...] = ( + ContinuousTimeKFConfig, + ContinuousTimeEnKFConfig, + ContinuousTimeDPFConfig, + ContinuousTimeEKFConfig, + ContinuousTimeUKFConfig, +) + + +@dataclasses.dataclass(frozen=True) +class HMMConfig(BaseFilterConfig): + r"""Exact filter for Hidden Markov Models (finite discrete state space). + + Use this when your latent state takes values in a finite set (e.g. a + discrete regime model). The forward algorithm computes the exact marginal + log-likelihood and filtered belief over states at each time step. + + For continuous latent-state models, use any other filter config. + + Supports missing observations via NaNs. Fully missing rows are skipped by + neutralizing the observation term, and partial missing rows are supported for + exact-marginalizable observation families such as `MultivariateNormal` and + factorizable `Independent(..., 1)` observations. + + For categorical observations, encode observed entries as zero-based integer + labels `0..K-1` and represent missing entries with `NaN`. + + Attributes: + record_filtered (bool | None): Save the filtered state probabilities + \(p(z_t \mid y_{1:t})\) as a deterministic site. `None` defers to + the backend default. + record_log_filtered (bool | None): Save the log of the filtered state + probabilities as a deterministic site. `None` defers to the + backend default. + filter_source (FilterSource): Backend. Defaults to `"dynestyx"`. + + ??? note "Algorithm Reference" + At each step the belief vector \(\pi_t = p(z_t \mid y_{1:t})\) is + updated exactly: + + \[ + \pi_t^{\text{pred}} = T^\top \pi_{t-1}, \quad + \pi_t \propto \ell(y_t \mid z_t) \, \pi_t^{\text{pred}} + \] + + The log-likelihood is the sum of the log normalisation constants. + """ + + record_filtered: bool | None = None + record_log_filtered: bool | None = None + filter_source: DynestyxOnlyFilterSource = "dynestyx" + + +HMMConfigs: tuple[type, ...] = (HMMConfig,) + + +def _config_to_record_kwargs(config: BaseFilterConfig) -> dict: + """Build record_kwargs dict from config. Config must have all record_* fields.""" + if isinstance(config, HMMConfig): + return { + "record_filtered": config.record_filtered, + "record_log_filtered": config.record_log_filtered, + "record_max_elems": config.record_max_elems, + } + else: + return { + "record_filtered_states_mean": config.record_filtered_states_mean, + "record_filtered_states_cov": config.record_filtered_states_cov, + "record_filtered_states_cov_diag": config.record_filtered_states_cov_diag, + "record_filtered_particles": config.record_filtered_particles, + "record_filtered_log_weights": config.record_filtered_log_weights, + "record_filtered_states_chol_cov": config.record_filtered_states_chol_cov, + "record_predicted_observations_mean": config.record_predicted_observations_mean, + "record_predicted_observations_cov": config.record_predicted_observations_cov, + "record_predicted_observations_ensemble": config.record_predicted_observations_ensemble, + "record_max_elems": config.record_max_elems, + } diff --git a/dynestyx/configs/mcmc.py b/dynestyx/configs/mcmc.py new file mode 100644 index 000000000..304585d6e --- /dev/null +++ b/dynestyx/configs/mcmc.py @@ -0,0 +1,229 @@ +import dataclasses +import math +from collections.abc import Callable +from typing import Literal + +import jax.numpy as jnp +from jax.typing import ArrayLike +from numpyro.infer.initialization import init_to_sample + +MCMCSource = Literal["numpyro", "blackjax"] + + +@dataclasses.dataclass +class BaseMCMCConfig: + """Shared configuration options inherited by all MCMC configs. + + You do not instantiate this class directly; use one of the concrete + subclasses (`NUTSConfig`, `HMCConfig`, `AdaptiveMWGConfig`, `AdaptiveMetropolisConfig`, + `SGLDConfig`, `MALAConfig`, `AdjustedMCLMCDynamicConfig`). + + Attributes: + num_samples (int): Number of post-warmup samples to return. + num_warmup (int): Number of warmup/burn-in transitions. + num_chains (int): Number of Markov chains to run in parallel. + mcmc_source (MCMCSource): Backend library used for inference. + Supported values are `"numpyro"` and `"blackjax"`. + init_strategy (callable): NumPyro initialization strategy used when + constructing unconstrained initial parameters. + """ + + num_samples: int + num_warmup: int + num_chains: int + mcmc_source: MCMCSource + init_strategy: Callable = init_to_sample + + +@dataclasses.dataclass +class HMCConfig(BaseMCMCConfig): + """Hamiltonian Monte Carlo (HMC) configuration. + + Attributes: + step_size (float): Integrator step size used by the leapfrog solver. + Ignored when ``adapt=True`` (step size is tuned during warmup). + num_steps (int): Number of leapfrog steps per HMC proposal. + adapt (bool): Whether to tune step size and mass matrix during warmup. + Defaults to ``True``. Set to ``False`` to use a fixed ``step_size`` + and identity mass matrix (useful when warmup is expensive or the + step size is known in advance). + """ + + step_size: float = 1e-2 + num_steps: int = 10 + adapt: bool = True + + +@dataclasses.dataclass +class NUTSConfig(BaseMCMCConfig): + """No-U-Turn Sampler (NUTS) configuration. + + Attributes: + target_acceptance_rate (float): Target acceptance probability used + during warmup. Must lie strictly between zero and one. + """ + + target_acceptance_rate: float = 0.8 + + def __post_init__(self) -> None: + if not 0.0 < self.target_acceptance_rate < 1.0: + raise ValueError("target_acceptance_rate must be between 0 and 1") + + +@dataclasses.dataclass +class _BaseAdaptiveRandomWalkConfig(BaseMCMCConfig): + """Shared options and validation for adaptive random-walk samplers.""" + + mcmc_source: MCMCSource = "blackjax" + initial_proposal_scale: ArrayLike = 1.0 + target_acceptance_rate: float = 0.44 + adaptation_rate: float = 0.5 + + def __post_init__(self) -> None: + if self.mcmc_source != "blackjax": + raise ValueError( + f"{type(self).__name__} only supports mcmc_source='blackjax'" + ) + if not 0.0 < self.target_acceptance_rate < 1.0: + raise ValueError("target_acceptance_rate must be between 0 and 1") + + if self.adaptation_rate <= 0.0: + raise ValueError("adaptation_rate must be positive") + + proposal_scale = jnp.asarray(self.initial_proposal_scale) + if proposal_scale.ndim > 1: + raise ValueError("initial_proposal_scale must be a scalar or 1D array") + if proposal_scale.size == 0 or not jnp.all(jnp.isfinite(proposal_scale)): + raise ValueError("initial_proposal_scale must contain finite values") + if jnp.any(proposal_scale <= 0.0): + raise ValueError("initial_proposal_scale must be positive") + + +@dataclasses.dataclass +class AdaptiveMWGConfig(_BaseAdaptiveRandomWalkConfig): + """Adaptive random-walk Metropolis-within-Gibbs configuration. + + One transition updates each flattened unconstrained coordinate in order. + Each coordinate update uses a one-dimensional Gaussian random-walk proposal + that is accepted or rejected before the next coordinate is visited; the + sampler does not make a single joint multivariate-normal proposal. Proposal + scales adapt during warmup toward the requested acceptance rate and remain + fixed while retained samples are generated. + + This sampler is currently implemented by the BlackJAX integration only. + + Attributes: + initial_proposal_scale (ArrayLike): Positive scalar proposal scale, or + one positive scale per flattened unconstrained coordinate. + target_acceptance_rate (float): Shared target acceptance rate applied + to each coordinate update. + adaptation_rate (float): Exponent in the diminishing adaptation step + ``n_iter ** -adaptation_rate``. + max_adaptation (float): Maximum change to a log proposal scale in one + warmup transition. + """ + + max_adaptation: float = 0.01 + + def __post_init__(self) -> None: + super().__post_init__() + if self.max_adaptation <= 0.0: + raise ValueError("max_adaptation must be positive") + + +@dataclasses.dataclass +class AdaptiveMetropolisConfig(_BaseAdaptiveRandomWalkConfig): + """Joint adaptive Gaussian random-walk Metropolis configuration. + + Each transition proposes the entire flattened unconstrained parameter + vector at once. The running mean, full covariance, and global covariance + multiplier adapt during warmup using Andrieu & Thoms (2008), Algorithm 4, + and remain frozen during sampling. The current log-density estimate is + cached across rejections, supporting pseudo-marginal inference when the + likelihood estimator is nonnegative and unbiased. + + This sampler supports only BlackJAX. + + Attributes: + initial_proposal_scale (ArrayLike): Positive finite scalar or vector + of initial scales for the flattened unconstrained coordinates. + The initial covariance is ``diag(scale ** 2)`` and the initial + global multiplier is ``2.38 ** 2 / d`` for dimension ``d``. + target_acceptance_rate (float): Target joint acceptance probability. + adaptation_rate (float): Exponent in the Robbins-Monro gain + ``initial_gain * (iteration + 1) ** -adaptation_rate``, + in ``(0.5, 1]``. + initial_gain (float): First warmup gain, finite and in ``(0, 1]``. + Defaults to ``2 ** -0.6``, retaining some initial covariance. + """ + + initial_proposal_scale: ArrayLike = 0.02 + target_acceptance_rate: float = 0.234 + adaptation_rate: float = 0.6 + initial_gain: float = 2**-0.6 + + def __post_init__(self) -> None: + super().__post_init__() + if not math.isfinite(self.adaptation_rate) or not ( + 0.5 < self.adaptation_rate <= 1.0 + ): + raise ValueError("adaptation_rate must be finite and in (0.5, 1]") + if not math.isfinite(self.initial_gain) or not (0.0 < self.initial_gain <= 1.0): + raise ValueError("initial_gain must be finite and in (0, 1]") + + +@dataclasses.dataclass +class SGLDConfig(BaseMCMCConfig): + r"""Stochastic Gradient Langevin Dynamics (SGLD) configuration. + + SGLD performs first-order Langevin updates using noisy gradients and + injected Gaussian noise. In this implementation, gradients are computed + on the full dataset (no minibatching), so the method behaves as + full-batch Langevin dynamics with an annealed step schedule. + + Attributes: + step_size (float): Base learning rate used in the SGLD schedule. + This should generally be small. + schedule_power (float): Power in the polynomial decay schedule + \(\epsilon_t = \text{step_size} \cdot t^{-\text{schedule_power}}\). + Values in `(0.5, 1.0]` are common for asymptotic convergence. + """ + + step_size: float = 1e-4 + schedule_power: float = 0.55 + + +@dataclasses.dataclass +class MALAConfig(BaseMCMCConfig): + """Metropolis-Adjusted Langevin Algorithm (MALA) configuration. + + Attributes: + step_size (float): Proposal step size used by `blackjax.mala`. + """ + + step_size: float = 1e-2 + + +@dataclasses.dataclass +class AdjustedMCLMCDynamicConfig(BaseMCMCConfig): + """Dynamic adjusted MCLMC (MHMCHMC) configuration. + + This maps to `blackjax.adjusted_mclmc_dynamic(...)` and uses its + top-level API arguments. + + Attributes: + step_size (float): Integrator step size. + L_proposal_factor (float): Proposal length scaling factor. + divergence_threshold (float): Energy-difference threshold used to flag + divergences. + integration_steps_min (int): Minimum random integration steps per + proposal. + integration_steps_max (int): Exclusive upper bound for random + integration steps per proposal. + """ + + step_size: float = 1e-2 + L_proposal_factor: float = float("inf") + divergence_threshold: float = 1000.0 + integration_steps_min: int = 1 + integration_steps_max: int = 10 diff --git a/dynestyx/configs/scoring.py b/dynestyx/configs/scoring.py new file mode 100644 index 000000000..99bf2a7f4 --- /dev/null +++ b/dynestyx/configs/scoring.py @@ -0,0 +1,28 @@ +"""Configuration for evaluating conditioned dynamical-model results.""" + +from __future__ import annotations + +import dataclasses + +from dynestyx.evaluation.scoring import ( + BaseObservationScore, + ObservationEnsembleSampleSource, +) + + +@dataclasses.dataclass(frozen=True) +class ObservationScoringConfig: + """Configure proper scoring rules for predictive observations. + + Attach this configuration to ``Evaluation``. Scores are computed from the + observed values and one-step-ahead predictive-observation outputs carried + by the forwarded ``ConditionedResult``. + """ + + rules: tuple[BaseObservationScore, ...] = dataclasses.field(default_factory=tuple) + record_as_numpyro_sites: bool = True + sample_source: ObservationEnsembleSampleSource = "auto" + sample_seed: int = 0 + + +__all__ = ["ObservationScoringConfig"] diff --git a/dynestyx/configs/simulator.py b/dynestyx/configs/simulator.py new file mode 100644 index 000000000..ccb8ae9b5 --- /dev/null +++ b/dynestyx/configs/simulator.py @@ -0,0 +1,172 @@ +"""Configuration objects for continuous-time simulators.""" + +from __future__ import annotations + +import dataclasses +from typing import Any, Literal + +import diffrax as dfx +from jaxtyping import Array, Real + +from dynestyx.types import as_scalar_time_array +from dynestyx.utils.validation import _raise_now_or_error_if + + +@dataclasses.dataclass +class ODESimulatorConfig: + """Configuration object for ODE simulators. + + Attributes: + solver (diffrax.AbstractSolver): Diffrax solver used for integration. + Defaults to `diffrax.Tsit5()`. See Diffrax's + [solver guide](https://docs.kidger.site/diffrax/usage/how-to-choose-a-solver/) + when selecting an alternative. IMEX solvers (e.g. `diffrax.KenCarp3/4/5`, + `diffrax.Sil3`) are supported, but require the state evolution's + `drift` to be an `ImExDrift` instance (see + `dynestyx.models.drifts.ImExDrift`), splitting the vector + field into `explicit_term`/`implicit_term`; conversely, using a + plain (non-`ImExDrift`) `drift` with an IMEX solver raises an + error. Using an `ImExDrift` with a non-IMEX solver is allowed + (both terms are summed) but emits a warning, since the split + goes unused. + adjoint (diffrax.AbstractAdjoint): Strategy used to differentiate + through the solve. Defaults to + `diffrax.RecursiveCheckpointAdjoint()`. + stepsize_controller (diffrax.AbstractStepSizeController): Step-size + policy used by Diffrax. Defaults to + `diffrax.ConstantStepSize()`; supply an adaptive controller when + error-controlled stepping is required. + dt0 (float | int | jax.Array): Initial step size passed to + `diffrax.diffeqsolve`. With the default constant-step controller, + this is the fixed integration step. Defaults to `1e-3`. + max_steps (int): Maximum number of integration steps permitted by + `diffrax.diffeqsolve`. Defaults to `100_000`. + throw (bool): Whether Diffrax raises when a solve fails. Set this to + `False` when inference should reject invalid parameter proposals + instead of aborting the complete run. Defaults to `True`. + + Properties: + diffeqsolve_settings (dict[str, Any]): Normalized keyword arguments passed + to `diffrax.diffeqsolve`; scalar time values are converted to JAX + arrays. + """ + + solver: dfx.AbstractSolver = dataclasses.field(default_factory=dfx.Tsit5) + adjoint: dfx.AbstractAdjoint = dataclasses.field( + default_factory=dfx.RecursiveCheckpointAdjoint + ) + stepsize_controller: dfx.AbstractStepSizeController = dataclasses.field( + default_factory=dfx.ConstantStepSize + ) + dt0: float | int | Real[Array, ""] = 1e-3 + max_steps: int = 100_000 + throw: bool = True + + @property + def diffeqsolve_settings(self) -> dict[str, Any]: + """Return normalized Diffrax settings for ``diffeqsolve``.""" + return { + "solver": self.solver, + "stepsize_controller": self.stepsize_controller, + "adjoint": self.adjoint, + "dt0": as_scalar_time_array(self.dt0, name="dt0"), + "max_steps": self.max_steps, + "throw": self.throw, + } + + +@dataclasses.dataclass +class SDESimulatorConfig: + """SDE Solver Settings for SDE Simulation. Supports diffrax-based solvers + or a faster, hand-rolled Euler-Maruyama scan backend. + + !! Note: The choice of solver can imply convergence to different paths + for the same model. For example, the default `diffrax.Heun()` converges + to the Stratonovich SDE, while `diffrax.Euler()` converges to the Itô SDE. + This likely doesn't matter for most models, but can cause issues with state-dependent diffusions. + + Attributes: + solver (diffrax.AbstractSolver): Diffrax SDE solver. Defaults to + `diffrax.Heun()`. This setting is used only when `source="diffrax"`. + stepsize_controller (diffrax.AbstractStepSizeController): Diffrax + step-size policy. Defaults to `diffrax.ConstantStepSize()` and is + used only when `source="diffrax"`. + adjoint (diffrax.AbstractAdjoint): Strategy used to differentiate + through the Diffrax solve. Defaults to + `diffrax.RecursiveCheckpointAdjoint()` and is used only when + `source="diffrax"`. + dt0 (float | int | jax.Array): Integration step size. It is passed to + Diffrax as the initial step size and used as the fixed + Euler-Maruyama step by the `"em_scan"` backend. Defaults to `1e-4`. + tol_vbt (float | int | jax.Array | None): Tolerance for Diffrax's + `VirtualBrownianTree`. When `source="diffrax"`, `None` resolves to + `dt0 / 2`; an explicit value must be smaller than `dt0` for + statistically correct simulation. Ignored by `"em_scan"`. + max_steps (int | None): Maximum number of Diffrax integration steps. + `None` leaves the Diffrax default in effect. The `"em_scan"` + backend does not use this setting. + source (Literal["diffrax", "em_scan"]): Simulation backend. + `"diffrax"` uses the configured Diffrax solver and a virtual + Brownian tree. `"em_scan"` uses a fixed-step Euler-Maruyama + `jax.lax.scan` and is the default for speed. + + Properties: + diffeqsolve_settings (dict[str, Any]): Normalized Diffrax keyword + arguments derived from the config; scalar time values are + converted to JAX arrays. + resolved_tol_vbt (jax.Array | None): Effective virtual-Brownian-tree + tolerance for the selected backend. Returns `None` for `"em_scan"` + and validates the tolerance for `"diffrax"`. + """ + + solver: dfx.AbstractSolver = dataclasses.field(default_factory=dfx.Heun) + stepsize_controller: dfx.AbstractStepSizeController = dataclasses.field( + default_factory=dfx.ConstantStepSize + ) + adjoint: dfx.AbstractAdjoint = dataclasses.field( + default_factory=dfx.RecursiveCheckpointAdjoint + ) + dt0: float | int | Real[Array, ""] = 1e-4 + tol_vbt: float | int | Real[Array, ""] | None = None + max_steps: int | None = None + source: Literal["diffrax", "em_scan"] = "em_scan" + + def __post_init__(self) -> None: + if self.source not in {"diffrax", "em_scan"}: + raise ValueError( + "SDESimulatorConfig.source must be one of {'diffrax', 'em_scan'}, " + f"got source={self.source!r}." + ) + + @property + def diffeqsolve_settings(self) -> dict[str, Any]: + """Return normalized Diffrax-style backend settings.""" + return { + "solver": self.solver, + "stepsize_controller": self.stepsize_controller, + "adjoint": self.adjoint, + "dt0": as_scalar_time_array(self.dt0, name="dt0"), + "max_steps": self.max_steps, + } + + @property + def resolved_tol_vbt(self) -> Real[Array, ""] | None: + """Return the resolved Brownian-tree tolerance for the active backend.""" + if self.source != "diffrax": + return None + + dt0_arr = as_scalar_time_array(self.dt0, name="dt0") + tol_vbt_arr = ( + dt0_arr / 2.0 + if self.tol_vbt is None + else as_scalar_time_array(self.tol_vbt, name="tol_vbt") + ) + tol_vbt_arr = _raise_now_or_error_if( + tol_vbt_arr, + tol_vbt_arr >= dt0_arr, + "tol_vbt must be smaller than dt0 for statistically correct simulation.", + ) + return tol_vbt_arr + + +type SimulatorConfig = ODESimulatorConfig | SDESimulatorConfig diff --git a/dynestyx/configs/smoother.py b/dynestyx/configs/smoother.py new file mode 100644 index 000000000..902ac878f --- /dev/null +++ b/dynestyx/configs/smoother.py @@ -0,0 +1,460 @@ +"""Smoother configuration dataclasses. Shared by dispatchers and integration backends.""" + +import abc +import dataclasses +from typing import Literal + +from dynestyx.configs.filter import ( + ContinuousTimeEKFConfig, + ContinuousTimeKFConfig, + EKFConfig, + EnKFConfig, + KFConfig, + PFConfig, + UKFConfig, +) + +PFBackwardSamplingMethod = Literal["tracing", "exact", "mcmc"] +CDKFSmootherType = Literal["cd_smoother_1", "cd_smoother_2"] + + +@dataclasses.dataclass(frozen=True) +class BaseSmootherConfig(abc.ABC): + r"""Shared base class for all smoother configs. + + You do not instantiate this class directly; use one of the concrete + subclasses (e.g. `KFSmootherConfig`, `PFSmootherConfig`). + + Concrete smoother configs inherit from their corresponding filter configs, + so backend selection, filter tuning, continuous-time solver options, and + filter recording fields follow the same conventions as + `dynestyx.configs.filter`. + + Config fields are immutable after construction. Use `dataclasses.replace` + to create an updated config. + + The `record_smoothed_*` fields let you save intermediate smoothing outputs + into the NumPyro trace as `numpyro.deterministic` sites, making them + accessible after inference (e.g. for plotting smoothed trajectories). + `None` defers to the backend's default for that quantity. + + Attributes: + record_smoothed_states_mean (bool | None): Save the posterior smoothing + mean \(\mathbb{E}[x_t \mid y_{1:T}]\) at each time step. + record_smoothed_states_cov (bool | None): Save the full smoothing + covariance at each time step. Can be large; prefer + `record_smoothed_states_cov_diag` for high-dimensional states. + record_smoothed_states_cov_diag (bool | None): Save only the marginal + smoothing variances at each time step. + record_smoothed_particles (bool | None): Save smoothed particles for + particle smoothers. + record_smoothed_log_weights (bool | None): Save smoothed particle log + weights for particle smoothers. + record_smoothed_states_chol_cov (bool | None): Save the Cholesky factor + of the smoothing covariance when exposed by the backend. + record_max_elems (int): Hard cap on total scalar elements saved across + all `record_*` sites. Prevents accidentally filling device memory + for long sequences or large state spaces. Defaults to `100_000`. + """ + + record_smoothed_states_mean: bool | None = None + record_smoothed_states_cov: bool | None = None + record_smoothed_states_cov_diag: bool | None = None + record_smoothed_particles: bool | None = None + record_smoothed_log_weights: bool | None = None + record_smoothed_states_chol_cov: bool | None = None + record_max_elems: int = 100_000 + + def __post_init__(self): + if type(self) is BaseSmootherConfig: + raise TypeError( + "BaseSmootherConfig is abstract and cannot be instantiated." + ) + + +@dataclasses.dataclass(frozen=True) +class KFSmootherConfig(KFConfig, BaseSmootherConfig): + r"""Rauch-Tung-Striebel Kalman Smoother (RTS) for discrete-time models. + + The exact Bayesian smoother for discrete-time linear-Gaussian state-space + models. Use this when your model was built with `LTI_discrete` or with + `LinearGaussianStateEvolution` + `LinearGaussianObservation`. + + The smoother computes \(p(x_t \mid y_{1:T})\), while `KFConfig` computes + \(p(x_t \mid y_{1:t})\). Use the inherited `record_smoothed_*` fields to + save smoothed means, covariances, or covariance diagonals in the NumPyro + trace. + + Supports missing observations via NaNs when `filter_source="cuthbert"`. Does not support missing observations (data cannot have NaNs) when `filter_source="cd_dynamax"`. + + Time-varying linear-Gaussian models (callable `(t_now, t_next)` / `(t,)` + parameters on `LinearGaussianStateEvolution` / + `LinearGaussianObservation`) are supported only with + `filter_source="cuthbert"`; `filter_source="cd_dynamax"` raises + `TypeError` for callable parameters. + + Attributes: + filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. + associative (bool | None): Whether to enable cuthbert's associative + parallel-in-time scan. This is only supported when + `filter_source="cuthbert"`. Defaults to `None`, which selects + an associative scan if `filter_source="cuthbert"`, and a + sequential scan otherwise. + + ??? note "Algorithm Reference" + After a forward Kalman filtering pass, the RTS smoother runs a backward + recursion over the filtered and one-step-ahead predicted Gaussian + states. For a linear transition matrix \(A_t\), the smoothing gain is + + $$ + G_t = P_{t|t} A_t^\top P_{t+1|t}^{-1}. + $$ + + The smoothed mean and covariance are then + + $$ + m_{t|T} = m_{t|t} + G_t (m_{t+1|T} - m_{t+1|t}), + $$ + + and + + $$ + P_{t|T} = P_{t|t} + + G_t (P_{t+1|T} - P_{t+1|t}) G_t^\top. + $$ + + References: + + - For the original smoother, see: Rauch, H. E., Tung, F., & Striebel, C. T. (1965). + Maximum likelihood estimates of linear dynamic systems. AIAA Journal, 3(8), 1445-1450. + - For a modern textbook reference, see: Särkkä, S., & Svensson, L. (2023). + Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. + [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). + """ + + +@dataclasses.dataclass(frozen=True) +class EKFSmootherConfig(EKFConfig, BaseSmootherConfig): + r"""Extended Kalman Smoother (EKS) for discrete-time models. + + The Gaussian smoother corresponding to `EKFConfig`. Use this for + differentiable nonlinear dynamics when local linearization is a reasonable + approximation to the filtering and smoothing distributions. + + This is exact (but wasteful) for linear-Gaussian models. For those models, + prefer `KFSmootherConfig`. + + Does not support missing observations (data cannot have NaNs). + + Attributes: + filter_source (FilterSource): Backend. Defaults to `"cuthbert"`. + + ??? note "Algorithm Reference" + The EKS applies the RTS backward recursion to the linear-Gaussian + approximations produced by an EKF filtering pass. The transition matrix + in the smoothing gain is the Jacobian of the transition function at the + filtered mean: + + $$ + G_t = P_{t|t} F_t^\top P_{t+1|t}^{-1}. + $$ + + Smoothed means and covariances are then computed with the same + backward recursion as `KFSmootherConfig`. + + References: + + - For a classical textbook treatment, see: Jazwinski, A. H. (1970). + Stochastic Processes and Filtering Theory. Academic Press. + - For a modern textbook reference, see: Särkkä, S., & Svensson, L. (2023). + Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. + [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). + """ + + +@dataclasses.dataclass(frozen=True) +class EnRTSSmootherConfig(EnKFConfig, BaseSmootherConfig): + r"""Ensemble Rauch-Tung-Striebel smoother (EnRTS) for discrete-time models. + + The EnRTS runs an ensemble Kalman filter forward pass followed by an + RTS-like backward recursion over the filtered and forecast ensembles. Use + this for nonlinear models with Gaussian, state-independent observation + noise when an ensemble approximation is preferable to local + linearization. + + The inherited `n_particles`, `inflation_delta`, and + `perturb_measurements` fields configure the forward EnKF. The cuthbert + backend retains the forecast ensemble required by the backward pass. + The inherited `localization` field localizes that forward EnKF only; the + backward EnRTS gain remains the standard, unlocalized empirical gain. + + Supports missing observations via NaNs. + + Attributes: + n_particles (int): Number of ensemble members. Defaults to `30`. + crn_seed (PRNGKeyArray | None): Fixed PRNG key for the ensemble. + perturb_measurements (bool | None): Whether to use stochastic + perturbed-observation EnKF updates. + inflation_delta (float | None): Ensemble inflation applied during the + forward pass. + localization (EnKFLocalizationConfig | EnKFLocalizationFunctions | None): + Optional localization for the forward EnKF pass only. + filter_source (FilterSource): Backend. Always `"cuthbert"`. + + ??? note "Algorithm Reference" + The EnRTS smooths each ensemble member with an empirical RTS gain: + + $$ + x_{t \mid T}^{(i)} + = x_{t \mid t}^{(i)} + + J_t \left( + x_{t+1 \mid T}^{(i)} + - x_{t+1 \mid t}^{(i)} + \right). + $$ + + The gain \(J_t\) is estimated from the filtered ensemble at time \(t\) + and its forecast at time \(t+1\). + + References: + + - Raanes, P. N. (2016). On the ensemble Rauch-Tung-Striebel smoother and its equivalence to the ensemble Kalman smoother. Quarterly Journal of the Royal Meteorological Society, 142(696), 1259-1264. + """ + + +@dataclasses.dataclass(frozen=True) +class UKFSmootherConfig(UKFConfig, BaseSmootherConfig): + r"""Unscented Kalman Smoother (UKS) for discrete-time models. + + A derivative-free Gaussian smoother that handles nonlinearities by + propagating deterministic sigma points rather than Jacobians. Use this when + sigma-point propagation is a better local approximation than EKF + linearization. + + This smoother is currently supported with `filter_source="cd_dynamax"` only. + Cuthbert UKF smoothing is not implemented. + + Does not support missing observations (data cannot have NaNs). + + Attributes: + alpha (float): Spread of sigma points around the current mean. + Smaller → tighter cluster; larger → sigma points reach further. + Defaults to \(\sqrt{3}\). + beta (int): Encodes prior knowledge about the distribution shape. + `2` is optimal for Gaussians. Defaults to `2`. + kappa (int): Secondary scaling parameter. Defaults to `1`. + filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. + + ??? note "Algorithm Reference" + The UKS uses a forward UKF pass followed by an RTS-style backward pass. + Instead of using a Jacobian in the smoothing gain, it estimates the + lag-one cross-covariance \(P_{t,t+1|t}\) by propagating sigma points: + + $$ + G_t = P_{t,t+1|t} P_{t+1|t}^{-1}. + $$ + + The smoothed mean and covariance then follow the same correction form + as the Kalman and extended Kalman smoothers. + + References: + + - For the original unscented Kalman filter paper, see: Julier, S. J., & Uhlmann, J. K. (1997). + New extension of the Kalman filter to nonlinear systems. SPIE Proceedings, 3068. + - For the unscented RTS smoother, see: Särkkä, S. (2008). + Unscented Rauch-Tung-Striebel smoother. IEEE Transactions on Automatic Control, 53(3), 845-849. + - For a modern textbook reference, see: Särkkä, S., & Svensson, L. (2023). + Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. + [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). + """ + + +@dataclasses.dataclass(frozen=True) +class PFSmootherConfig(PFConfig, BaseSmootherConfig): + r"""Particle smoother for discrete-time models. + + Use this for nonlinear or non-Gaussian discrete-time models. Particle + smoothing is more flexible than Gaussian smoothing, but accuracy scales + with the number of particles and backward-sampled smoother trajectories. + + This smoother is currently supported with `filter_source="cuthbert"` only. + + Does not support missing observations (data cannot have NaNs). + + Attributes: + n_particles (int): Number of particles in the forward particle filter. + More particles give a lower-variance log-likelihood and smoothing + approximation at linear compute cost. Defaults to `1_000`. + pf_backward_sampling_method (PFBackwardSamplingMethod): Backward + simulation method. `"tracing"` is the default, `"exact"` performs + exact backward sampling where available, and `"mcmc"` uses an MCMC + backward kernel. + pf_mcmc_n_steps (int): Number of MCMC steps used when + `pf_backward_sampling_method="mcmc"`. + pf_n_smoother_particles (int | None): Number of backward-sampled + smoother particles. `None` inherits `n_particles` from `PFConfig`. + filter_source (FilterSource): Backend. Defaults to `"cuthbert"`, which + is currently the only available implementation. + + ??? note "Algorithm Reference" + Particle smoothers augment a forward particle filter with a backward + pass that reconstructs trajectories from the particle approximation to + the filtering distributions. + + In backward simulation, a sampled state \(x_{t+1}^{(j)}\) chooses an + ancestor at time \(t\) with probabilities proportional to + + $$ + w_t^{(i)} p(x_{t+1}^{(j)} \mid x_t^{(i)}). + $$ + + The `"tracing"` method follows stored particle ancestors. The `"exact"` + and `"mcmc"` methods use backward kernels that can better approximate + the full smoothing distribution at higher compute cost. + + References: + + - For backward simulation particle smoothing, see: Godsill, S. J., Doucet, A., & West, M. (2004). + Monte Carlo smoothing for nonlinear time series. Journal of the American Statistical Association, 99(465), 156-168. + - For a general SMC/particle filtering reference, see: Doucet, A., De Freitas, N., & Gordon, N. (2001). + An Introduction to Sequential Monte Carlo Methods. In Sequential Monte Carlo Methods in Practice (pp. 3-14). + New York, NY: Springer New York. + - For a modern textbook reference, see: Särkkä, S., & Svensson, L. (2023). + Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. + [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). + """ + + pf_backward_sampling_method: PFBackwardSamplingMethod = "tracing" + pf_mcmc_n_steps: int = 10 + pf_n_smoother_particles: int | None = None + + +@dataclasses.dataclass(frozen=True) +class ContinuousTimeKFSmootherConfig(ContinuousTimeKFConfig, BaseSmootherConfig): + r"""Continuous-discrete Kalman Smoother (CD-KS). + + The exact Bayesian smoother for continuous-time linear-Gaussian models with + discrete observations. Use this when your model was built with + `LTI_continuous`. + + This smoother is currently implemented through the `cd_dynamax` backend. + Inherited differential-equation solver options control the continuous-time + filtering pass, and inherited `record_smoothed_*` fields control trace + recording. + + Does not support missing observations (data cannot have NaNs). + + Attributes: + cdlgssm_smoother_type (CDKFSmootherType): CD-Dynamax smoother variant. + `"cd_smoother_1"` is the default; `"cd_smoother_2"` exposes the + backend's alternate continuous-discrete RTS implementation. + filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. + + ??? note "Algorithm Reference" + Continuous-discrete Kalman smoothing runs a continuous-time Kalman + filtering pass between observations, applies discrete Kalman updates at + observation times, and then integrates the corresponding backward + smoothing equations through the filtered trajectory. + + The result is the continuous-discrete analogue of the RTS smoother: + each state is conditioned on all observations \(y_{1:T}\), not just the + observations available up to that time. + + References: + + - For continuous-discrete smoothing equations, see: Särkkä, S. (2006). + Recursive Bayesian Inference on Stochastic Differential Equations. + - For a modern textbook reference, see Chapter 10.6 of: + Särkkä, S., & Solin, A. (2019). Applied Stochastic Differential Equations. + Cambridge University Press. [Available Online](https://users.aalto.fi/~asolin/sde-book/sde-book.pdf). + - For general Gaussian smoothing background, see: Särkkä, S., & Svensson, L. (2023). + Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. + [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). + """ + + cdlgssm_smoother_type: CDKFSmootherType = "cd_smoother_1" + + +@dataclasses.dataclass(frozen=True) +class ContinuousTimeEKFSmootherConfig(ContinuousTimeEKFConfig, BaseSmootherConfig): + r"""Continuous-discrete Extended Kalman Smoother (CD-EKS). + + Gaussian smoother for mildly nonlinear continuous-time dynamics with + discrete observations. Requires differentiable dynamics; JAX autodiff is + used to construct the local linearizations. + + This smoother is currently implemented through the `cd_dynamax` backend. + See `ContinuousTimeEKFConfig` for linearisation and solver options. + + Does not support missing observations (data cannot have NaNs). + + Attributes: + filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. + + ??? note "Algorithm Reference" + The CD-EKS combines a continuous-discrete EKF filtering pass with a + backward smoothing pass through the locally linear Gaussian + approximations. It is the continuous-discrete analogue of + `EKFSmootherConfig`. + + The inherited `filter_state_order` and `filter_emission_order` options + control the Taylor approximation used during the continuous-time + filtering and smoothing computation. + + References: + + - For continuous-discrete smoothing equations, see: Särkkä, S. (2006). + Recursive Bayesian Inference on Stochastic Differential Equations. + - For a modern textbook reference, see Chapter 10.9 of: + Särkkä, S., & Solin, A. (2019). Applied Stochastic Differential Equations. + Cambridge University Press. [Available Online](https://users.aalto.fi/~asolin/sde-book/sde-book.pdf). + - For general Gaussian smoothing background, see: Särkkä, S., & Svensson, L. (2023). + Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. + [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). + """ + + +DiscreteTimeSmootherConfigs: tuple[type, ...] = ( + KFSmootherConfig, + EKFSmootherConfig, + EnRTSSmootherConfig, + UKFSmootherConfig, + PFSmootherConfig, +) + +ContinuousTimeSmootherConfigs: tuple[type, ...] = ( + ContinuousTimeKFSmootherConfig, + ContinuousTimeEKFSmootherConfig, +) + + +def _config_to_smoother_record_kwargs(config: BaseSmootherConfig) -> dict: + """Build smoother record kwargs dict from config.""" + return { + "record_smoothed_states_mean": config.record_smoothed_states_mean, + "record_smoothed_states_cov": config.record_smoothed_states_cov, + "record_smoothed_states_cov_diag": config.record_smoothed_states_cov_diag, + "record_smoothed_particles": config.record_smoothed_particles, + "record_smoothed_log_weights": config.record_smoothed_log_weights, + "record_smoothed_states_chol_cov": config.record_smoothed_states_chol_cov, + "record_max_elems": config.record_max_elems, + } + + +__all__ = [ + "BaseSmootherConfig", + "CDKFSmootherType", + "ContinuousTimeEKFSmootherConfig", + "ContinuousTimeKFSmootherConfig", + "ContinuousTimeSmootherConfigs", + "DiscreteTimeSmootherConfigs", + "EKFSmootherConfig", + "EnRTSSmootherConfig", + "KFSmootherConfig", + "PFBackwardSamplingMethod", + "PFSmootherConfig", + "UKFSmootherConfig", +] + + +SmootherConfig = BaseSmootherConfig diff --git a/dynestyx/control/discrete_controller_simulators.py b/dynestyx/control/discrete_controller_simulators.py index 36a69fd40..f9a066952 100644 --- a/dynestyx/control/discrete_controller_simulators.py +++ b/dynestyx/control/discrete_controller_simulators.py @@ -11,7 +11,7 @@ from jaxtyping import PRNGKeyArray, PyTree, Real from numpyro.distributions import Delta, Distribution -from dynestyx.inference.configs.filter import BaseFilterConfig, PFConfig +from dynestyx.configs.filter import BaseFilterConfig, PFConfig from dynestyx.inference.filters import _default_filter_config from dynestyx.inference.integrations.cuthbert.discrete_filter import ( CuthbertInputs, diff --git a/dynestyx/discretization/diffrax_sample.py b/dynestyx/discretization/diffrax_sample.py index 05865eae4..b0d000b42 100644 --- a/dynestyx/discretization/diffrax_sample.py +++ b/dynestyx/discretization/diffrax_sample.py @@ -12,7 +12,7 @@ from jaxtyping import Array, PRNGKeyArray, Real from numpyro.distributions import constraints -from dynestyx.inference.configs.discretizer import DiffraxSampleConfig +from dynestyx.configs.discretizer import DiffraxSampleConfig from dynestyx.models import ( DiscreteTimeStateEvolution, StochasticContinuousTimeStateEvolution, diff --git a/dynestyx/discretization/gaussian.py b/dynestyx/discretization/gaussian.py index 4a70e0233..3c4dae9e4 100644 --- a/dynestyx/discretization/gaussian.py +++ b/dynestyx/discretization/gaussian.py @@ -9,18 +9,18 @@ import numpyro.distributions as dist from jaxtyping import Array, Real +from dynestyx.configs.discretizer import ( + BaseDiscretizerConfig, + EulerMaruyamaConfig, + LocalLinearizationConfig, + MeanTrajectoryLinearizationConfig, +) from dynestyx.discretization.exact_affine import _affine_transition_parameters from dynestyx.discretization.numerics import ( _finalize_covariance, _positive_interval, _symmetrize, ) -from dynestyx.inference.configs.discretizer import ( - BaseDiscretizerConfig, - EulerMaruyamaConfig, - LocalLinearizationConfig, - MeanTrajectoryLinearizationConfig, -) from dynestyx.models import ( DiscreteTimeStateEvolution, StochasticContinuousTimeStateEvolution, diff --git a/dynestyx/discretization/ode_flow.py b/dynestyx/discretization/ode_flow.py index ef53ff181..f75c1a9a1 100644 --- a/dynestyx/discretization/ode_flow.py +++ b/dynestyx/discretization/ode_flow.py @@ -6,7 +6,7 @@ import jax.numpy as jnp import numpyro.distributions as dist -from dynestyx.inference.configs.discretizer import ODEFlowConfig +from dynestyx.configs.discretizer import ODEFlowConfig from dynestyx.models import ( DeterministicContinuousTimeStateEvolution, DiscreteTimeStateEvolution, diff --git a/dynestyx/discretizers.py b/dynestyx/discretizers.py index 6405b691b..15965af4c 100644 --- a/dynestyx/discretizers.py +++ b/dynestyx/discretizers.py @@ -6,6 +6,16 @@ from effectful.ops.syntax import ObjectInterpretation, implements from jaxtyping import Array, Real +from dynestyx.configs.discretizer import ( + BaseDiscretizerConfig, + DiffraxSampleConfig, + DiscretizerConfig, + EulerMaruyamaConfig, + ExactAffineConfig, + LocalLinearizationConfig, + MeanTrajectoryLinearizationConfig, + ODEFlowConfig, +) from dynestyx.discretization.diffrax_sample import _DiffraxSampleStateEvolution from dynestyx.discretization.exact_affine import _ExactAffineStateEvolution from dynestyx.discretization.gaussian import _ConfiguredGaussianStateEvolution @@ -16,16 +26,6 @@ _dynestyx_stack_kind, _DynestyxStackKind, ) -from dynestyx.inference.configs.discretizer import ( - BaseDiscretizerConfig, - DiffraxSampleConfig, - DiscretizerConfig, - EulerMaruyamaConfig, - ExactAffineConfig, - LocalLinearizationConfig, - MeanTrajectoryLinearizationConfig, - ODEFlowConfig, -) from dynestyx.models import ( AffineDrift, DeterministicContinuousTimeStateEvolution, diff --git a/dynestyx/evaluation/__init__.py b/dynestyx/evaluation/__init__.py index 9b1652b94..91e2ac35f 100644 --- a/dynestyx/evaluation/__init__.py +++ b/dynestyx/evaluation/__init__.py @@ -1,6 +1,6 @@ """Evaluation handlers, configurations, and scoring rules for Dynestyx.""" -from dynestyx.evaluation.configs import ObservationScoringConfig +from dynestyx.configs.scoring import ObservationScoringConfig from dynestyx.evaluation.handlers import Evaluation __all__ = ["Evaluation", "ObservationScoringConfig"] diff --git a/dynestyx/evaluation/configs.py b/dynestyx/evaluation/configs.py index 99bf2a7f4..fea440c65 100644 --- a/dynestyx/evaluation/configs.py +++ b/dynestyx/evaluation/configs.py @@ -1,28 +1,13 @@ -"""Configuration for evaluating conditioned dynamical-model results.""" +"""Deprecated compatibility module for :mod:`dynestyx.configs.scoring`.""" -from __future__ import annotations - -import dataclasses - -from dynestyx.evaluation.scoring import ( - BaseObservationScore, - ObservationEnsembleSampleSource, -) - - -@dataclasses.dataclass(frozen=True) -class ObservationScoringConfig: - """Configure proper scoring rules for predictive observations. - - Attach this configuration to ``Evaluation``. Scores are computed from the - observed values and one-step-ahead predictive-observation outputs carried - by the forwarded ``ConditionedResult``. - """ - - rules: tuple[BaseObservationScore, ...] = dataclasses.field(default_factory=tuple) - record_as_numpyro_sites: bool = True - sample_source: ObservationEnsembleSampleSource = "auto" - sample_seed: int = 0 +import warnings +from dynestyx.configs.scoring import ObservationScoringConfig __all__ = ["ObservationScoringConfig"] + +warnings.warn( + "dynestyx.evaluation.configs is deprecated; use dynestyx.configs.scoring instead.", + DeprecationWarning, + stacklevel=2, +) diff --git a/dynestyx/evaluation/handlers.py b/dynestyx/evaluation/handlers.py index da40d64a2..1812fa41d 100644 --- a/dynestyx/evaluation/handlers.py +++ b/dynestyx/evaluation/handlers.py @@ -10,7 +10,7 @@ from jaxtyping import Array, Bool, Real from dynestyx._defaults import _complete_defaults -from dynestyx.evaluation.configs import ObservationScoringConfig +from dynestyx.configs.scoring import ObservationScoringConfig from dynestyx.evaluation.observation_scoring import build_evaluation_result from dynestyx.handlers import ( HandlesSelf, diff --git a/dynestyx/evaluation/observation_scoring.py b/dynestyx/evaluation/observation_scoring.py index 061cb5947..749e1a6d2 100644 --- a/dynestyx/evaluation/observation_scoring.py +++ b/dynestyx/evaluation/observation_scoring.py @@ -8,7 +8,7 @@ import numpyro.distributions as dist from jaxtyping import Array, Float -from dynestyx.evaluation.configs import ObservationScoringConfig +from dynestyx.configs.scoring import ObservationScoringConfig from dynestyx.evaluation.scoring import EnergyScore from dynestyx.inference.observation_predictions import PredictedObservationOutputs from dynestyx.types import EvaluationResult diff --git a/dynestyx/inference/checkers.py b/dynestyx/inference/checkers.py index 9e0f97262..45d844394 100644 --- a/dynestyx/inference/checkers.py +++ b/dynestyx/inference/checkers.py @@ -7,7 +7,7 @@ import numpyro from jaxtyping import Array, Real, Shaped -from dynestyx.inference.configs.filter import ( +from dynestyx.configs.filter import ( BaseFilterConfig, ContinuousTimeConfigs, DiscreteTimeConfigs, @@ -16,7 +16,7 @@ KFConfig, PFConfig, ) -from dynestyx.inference.configs.smoother import ( +from dynestyx.configs.smoother import ( BaseSmootherConfig, ContinuousTimeSmootherConfigs, DiscreteTimeSmootherConfigs, diff --git a/dynestyx/inference/configs/__init__.py b/dynestyx/inference/configs/__init__.py index 38391dcb0..fb91e6dbf 100644 --- a/dynestyx/inference/configs/__init__.py +++ b/dynestyx/inference/configs/__init__.py @@ -1 +1 @@ -"""Configuration subpackage for inference and simulation.""" +"""Compatibility package for config modules moved to :mod:`dynestyx.configs`.""" diff --git a/dynestyx/inference/configs/discretizer.py b/dynestyx/inference/configs/discretizer.py index 420309ad3..2dbe9a2f7 100644 --- a/dynestyx/inference/configs/discretizer.py +++ b/dynestyx/inference/configs/discretizer.py @@ -1,425 +1,12 @@ -"""Configuration objects for continuous-to-discrete approximations.""" +"""Deprecated compatibility module for :mod:`dynestyx.configs.discretizer`.""" -from __future__ import annotations +import warnings -import abc -import dataclasses +from dynestyx.configs.discretizer import * # noqa: F403 -import diffrax as dfx - -from dynestyx.inference.configs.simulator import ( - ODESimulatorConfig, - SDESimulatorConfig, -) -from dynestyx.utils.validation import _validate_nonnegative_float - - -def _default_diffrax_sde_solver() -> SDESimulatorConfig: - return SDESimulatorConfig( - source="diffrax", solver=dfx.Euler(), dt0=1e-2, max_steps=100_000 - ) - - -@dataclasses.dataclass -class BaseDiscretizerConfig(abc.ABC): - r"""Base class for continuous-to-discrete configuration objects. - - Do not instantiate this marker class directly. Pass one of its concrete - subclasses to `Discretizer`. For default settings, pass None - as the config to `Discretizer`. - """ - - -@dataclasses.dataclass -class ODEFlowConfig(BaseDiscretizerConfig): - r"""Numerical flow transition for a deterministic ODE. - - For the controlled ODE - - $$ - \dot X_s=f(X_s,u_k,s), - $$ - - this config numerically integrates from ``t_now`` to ``t_next`` while - holding ``u_k`` fixed. With endpoint - $\phi(x,u_k,t_{\mathrm{now}},t_{\mathrm{next}})$, the returned - transition is a Delta distribution when ``jitter_scale == 0``. For - positive ``jitter_scale`` it is an independent Normal distribution with - mean $\phi$, component scale ``jitter_scale``, and covariance - ``jitter_scale**2 * I``. - - All Diffrax settings come from the existing ``ODESimulatorConfig``. - - Attributes: - simulator_config (ODESimulatorConfig): Diffrax ODE solver settings. - Defaults to ``ODESimulatorConfig()``. - jitter_scale (float): Finite, nonnegative component scale added - after integrating the flow. Defaults to ``0.0``. - """ - - simulator_config: ODESimulatorConfig = dataclasses.field( - default_factory=ODESimulatorConfig - ) - jitter_scale: float = 0.0 - - def __post_init__(self) -> None: - _validate_nonnegative_float("jitter_scale", self.jitter_scale) - - -@dataclasses.dataclass -class EulerMaruyamaConfig(BaseDiscretizerConfig): - r"""Euler--Maruyama Gaussian transition for a general Itô SDE. - - This is the inexpensive, general-purpose discretization. Consider - - $$ - dX_s=f(X_s,u_k,s)\,ds+L(X_s,u_k,s)\,dW_s, - \qquad - a(x,u,s)=L(x,u,s)L(x,u,s)^\top , - $$ - - on \(s\in[t_k,t_{k+1}]\), where \(W_s\) is standard Brownian motion, - \(h=t_{k+1}-t_k>0\), and the control \(u_k\) is held fixed over the - interval. Euler--Maruyama freezes both coefficients at its left endpoint: - - $$ - X_{k+1}\mid X_k=x,u_k - \;\approx\; - \mathcal N\!\left( - x+h f(x,u_k,t_k), - h\,a(x,u_k,t_k)+\epsilon I - \right), - $$ - - where \(\epsilon\) is `covariance_jitter`. - - The method applies to nonlinear drift and state-, time-, or - control-dependent diffusion. Under the usual global Lipschitz and growth - assumptions it has strong order \(1/2\) and weak order \(1\); for additive - noise its strong order improves to \(1\). See Kloeden and Platen (1992) - for more details. It requires one drift and one diffusion evaluation per - transition, but a single large step can poorly represent nonlinear, stiff, - or rapidly varying dynamics. - - Attributes: - covariance_jitter (float): Nonnegative \(\epsilon\) added to the - transition covariance as \(\epsilon I\). Defaults to `0.0`. - Positive jitter changes the stochastic model and should be chosen - explicitly rather than treated as an invisible numerical fix. - - ??? note "Algorithm Reference" - - Särkkä, S., & Solin, A. (2019). *Applied Stochastic Differential - Equations*. Cambridge University Press, Algorithm 8.1 and - Equations (8.28)--(8.30). - [Online book](https://users.aalto.fi/~asolin/sde-book/sde-book.pdf). - - Kloeden, P. E., & Platen, E. (1992). *Numerical Solution of - Stochastic Differential Equations*. Springer, Chapter 10. - [https://doi.org/10.1007/978-3-662-12616-5](https://doi.org/10.1007/978-3-662-12616-5). - """ - - covariance_jitter: float = 0.0 - - def __post_init__(self) -> None: - _validate_nonnegative_float("covariance_jitter", self.covariance_jitter) - - -@dataclasses.dataclass -class ExactAffineConfig(BaseDiscretizerConfig): - r"""Exact discrete transition for an affine SDE with additive noise. - - Use this config only when the continuous transition has an `AffineDrift`, - constant diffusion, and no potential. For the Itô SDE - - $$ - dX_s=(F X_s+B u_k+b)\,ds+L\,dW_s - $$ - - over an interval of length \(h=t_{k+1}-t_k>0\), with standard Brownian - motion and a held control \(u_k\), the exact conditional transition is - - $$ - X_{k+1}\mid X_k=x,u_k - \sim - \mathcal N(A_hx+B_hu_k+b_h,\;Q_h+\epsilon I), - $$ - - with - - $$ - A_h=e^{Fh},\qquad - B_h=\int_0^h e^{Fs}B\,ds,\qquad - b_h=\int_0^h e^{Fs}b\,ds, - $$ - - and - - $$ - Q_h=\int_0^h e^{Fs}LL^\top e^{F^\top s}\,ds. - $$ - - The implementation uses an augmented matrix exponential for the forcing - terms and evaluates the Van Loan covariance on a safely scaled interval - before composing it to the requested interval. This avoids overflowing the - growing block associated with a stable, stiff drift. It never forms - \(F^{-1}\), so singular drift matrices are supported. With - `covariance_jitter=0`, the transition is exact up to floating-point error - for every positive interval length, including nonuniform observation grids. - It preserves a linear Gaussian state-evolution representation and therefore - enables exact Kalman filtering when the rest of the model is also linear - Gaussian. - - Matrix exponentials cost cubic time in the augmented state dimension and - can be expensive when many distinct interval lengths are used. Drifts - not explicitly marked as affine/constant, state-dependent diffusion, and - potentials are rejected. Singular \(Q_h\) requires positive jitter. - - Attributes: - covariance_jitter (float): Nonnegative \(\epsilon\) added to \(Q_h\) - as \(\epsilon I\). Defaults to `0.0`. - - ??? note "Algorithm Reference" - - Van Loan, C. F. (1978). Computing integrals involving the matrix - exponential. *IEEE Transactions on Automatic Control*, 23(3), - 395--404. - [https://doi.org/10.1109/TAC.1978.1101743](https://doi.org/10.1109/TAC.1978.1101743). - - Särkkä, S., & Svensson, L. (2023). *Bayesian Filtering and - Smoothing*, 2nd ed. Cambridge University Press, Theorem 4.3 and - Lemma A.9. - [Online book](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). - - Axelsson, P., & Gustafsson, F. (2015). Discrete-time solutions to - the continuous-time differential Lyapunov equation. *IEEE - Transactions on Automatic Control*, 60(3), 632--643. - [https://doi.org/10.1109/TAC.2014.2353112](https://doi.org/10.1109/TAC.2014.2353112). - """ - - covariance_jitter: float = 0.0 - - def __post_init__(self) -> None: - _validate_nonnegative_float("covariance_jitter", self.covariance_jitter) - - -@dataclasses.dataclass -class LocalLinearizationConfig(BaseDiscretizerConfig): - r"""Locally linearized Gaussian transition with frozen additive noise. - - This method is intended for nonlinear drift with structurally constant, - additive diffusion. For the Itô SDE - - $$ - dX_s=f(X_s,u_k,s)\,ds+L\,dW_s, - $$ - - define, at the left endpoint \(x=X_{t_k}\), - - $$ - f_0=f(x,u_k,t_k),\qquad - J=\left.\frac{\partial f}{\partial x}\right|_{(x,u_k,t_k)} . - $$ - - With standard Brownian motion, \(h=t_{k+1}-t_k>0\), and \(u_k\) held - fixed, approximate the original process by - - $$ - dZ_s=\left[f_0+J(Z_s-x)\right]ds+L\,dW_s,\qquad Z_0=x. - $$ - - Its exact Gaussian transition has - - $$ - m_h=x+\int_0^h e^{Js}f_0\,ds, - \qquad - P_h=\int_0^h e^{Js}LL^\top e^{J^\top s}\,ds, - $$ - - and this config returns - \(\mathcal N(m_h,P_h+\epsilon I)\), where \(\epsilon\) is - `covariance_jitter`. - - The method is exact for affine drift with additive diffusion. With some amount - of nonlinearity, it can be more accurate than Euler--Maruyama, but at higher - cost, since Jacobians must be computed. - - State-, time-, or control-dependent diffusion are rejected. - The returned object is a Gaussian transition distribution, compatible - with any method using Gaussian transitions. Degenerate transition covariance - requires explicit positive jitter. - - Attributes: - covariance_jitter (float): Nonnegative \(\epsilon\) added to \(P_h\) - as \(\epsilon I\). Defaults to `0.0`. - - ??? note "Algorithm Reference" - - Särkkä, S., & Svensson, L. (2023). *Bayesian Filtering and - Smoothing*, 2nd ed. Cambridge University Press, Theorem 4.18. - [Online book](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). - - Ozaki, T. (1992). A bridge between nonlinear time series models and - nonlinear stochastic dynamical systems: A local linearization - approach. *Statistica Sinica*, 2(1), 113--135. - [Article](https://www3.stat.sinica.edu.tw/statistica/j2n1/j2n16/j2n16.htm). - """ - - covariance_jitter: float = 0.0 - - def __post_init__(self) -> None: - _validate_nonnegative_float("covariance_jitter", self.covariance_jitter) - - -@dataclasses.dataclass -class MeanTrajectoryLinearizationConfig(BaseDiscretizerConfig): - r"""Gaussian moment transition linearized along the conditional mean. - - This config integrates a first-order Gaussian assumed-density - approximation for the Itô SDE - - $$ - dX_s=f(X_s,u_k,s)\,ds+L(X_s,u_k,s)\,dW_s,\qquad - a(x,u,s)=L(x,u,s)L(x,u,s)^\top . - $$ - - On \(s\in[t_k,t_{k+1}]\), standard Brownian motion is assumed and \(u_k\) - is held fixed. Starting from the deterministic conditional state - - $$ - m(t_k)=x,\qquad P(t_k)=0, - $$ - - integrate - - $$ - \dot m_s=f(m_s,u_k,s), - $$ - - $$ - \dot P_s=J_sP_s+P_sJ_s^\top+a(m_s,u_k,s), - \qquad - J_s=\frac{\partial f}{\partial x}(m_s,u_k,s), - $$ - - and return - \(\mathcal N(m(t_{k+1}),P(t_{k+1})+\epsilon I)\). - - This approximation supports nonlinear drift and state-, time-, or - control-dependent diffusion. It is exact for affine drift with additive - diffusion up to the numerical ODE solver tolerance. Relative to a - left-endpoint local linearization, it updates the Jacobian along the mean - trajectory. - - Every transition performs a joint mean/covariance ODE solve and evaluates a - state Jacobian at each right-hand-side call, so it is considerably more - expensive than Euler--Maruyama. A singular final covariance requires explicit - positive jitter. - - Attributes: - ode_solver (ODESimulatorConfig): Existing Diffrax ODE configuration - used unchanged for the joint mean/covariance integration. - Defaults to `ODESimulatorConfig()`. - covariance_jitter (float): Nonnegative \(\epsilon\) added to the final - covariance as \(\epsilon I\). Defaults to `0.0`. - - ??? note "Algorithm Reference" - - Särkkä, S., & Solin, A. (2019). *Applied Stochastic Differential - Equations*. Cambridge University Press, Algorithm 9.4, - Equation (9.15), and Algorithm 9.8 with Equation (9.28). - [Online book](https://users.aalto.fi/~asolin/sde-book/sde-book.pdf). - - Särkkä, S., & Svensson, L. (2023). *Bayesian Filtering and - Smoothing*, 2nd ed. Cambridge University Press, Theorem 4.13 and - Algorithm 4.14. - [Online book](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). - - Särkkä, S., & Sarmavuori, J. (2013). Gaussian filtering and - smoothing for continuous-discrete dynamic systems. *Signal - Processing*, 93(2), 500--510. - [https://doi.org/10.1016/j.sigpro.2012.09.002](https://doi.org/10.1016/j.sigpro.2012.09.002). - """ - - ode_solver: ODESimulatorConfig = dataclasses.field( - default_factory=ODESimulatorConfig - ) - covariance_jitter: float = 0.0 - - def __post_init__(self) -> None: - _validate_nonnegative_float("covariance_jitter", self.covariance_jitter) - - -@dataclasses.dataclass -class DiffraxSampleConfig(BaseDiscretizerConfig): - r"""Sample-only transition obtained by solving each interval with Diffrax. - - This config is for simulation, ensemble Kalman filtering, bootstrap - particle filtering, and genealogy-tracing particle smoothing when a - numerical SDE path solver is preferable to an analytic transition - approximation. For - - $$ - dX_s=f(X_s,u_k,s)\,ds+L(X_s,u_k,s)\,dW_s, - $$ - - over \(s\in[t_k,t_{k+1}]\), with \(u_k\) held fixed, it defines the - transition operationally as - - $$ - X_{k+1} - = - \Psi_{\mathrm{Diffrax}} - (x,u_k,t_k,t_{k+1};\omega), - $$ - - where \(\Psi_{\mathrm{Diffrax}}\) is the numerical solution selected by - `sde_solver` and \(\omega\) is generated from the key passed to - `sample` or `rsample`. A fresh Brownian tree is used for each Markov - interval. The transition stores no PRNG key and performs no solve when it - is constructed; solving is deferred until sampling so model shape probes - remain cheap. - - This transition has no tractable density in general. It supports - `sample_shape`, reparameterized `rsample`, JIT compilation, external `vmap`, - deterministic replay with the same key, `DiscreteTimeSimulator`, cuthbert - EnKF, and cuthbert bootstrap PF. A cuthbert `PFSmootherConfig` using - genealogy tracing is also compatible because it follows stored ancestors - without evaluating a transition density. `log_prob`, `mean`, and `variance` - raise targeted errors at the point where they are requested. Kalman, - extended/unscented Kalman, - density-based particle smoothers, latent-path scoring, and proposals that - require transition densities or analytic moments are not supported. - - The implementation supports any Diffrax solver that operates from ordinary - Brownian increments, including `diffrax.Euler()` and `diffrax.Heun()`. - The default inner config selects `diffrax.Euler()`, the Euler--Maruyama - solver, with a default step size of `1e-2`. Cost scales with the number of - internal solver steps and requested samples. `source="em_scan"` is rejected. - Reverse-mode differentiation through the default - `diffrax.RecursiveCheckpointAdjoint()` requires a finite - `sde_solver.max_steps`; the default bound is `100_000` steps per interval. - - Attributes: - sde_solver (SDESimulatorConfig): Existing SDE simulator configuration - used for each interval. It must have `source="diffrax"`. Defaults - to `SDESimulatorConfig(source="diffrax", - solver=diffrax.Euler(), dt0=1e-2, max_steps=100_000)`. - - ??? note "Algorithm Reference" - - Kidger, P. Diffrax documentation: - [SDE solvers](https://docs.kidger.site/diffrax/api/solvers/sde_solvers/) - and the - [SDE solver/order table](https://docs.kidger.site/diffrax/devdocs/SDE_solver_table/). - """ - - sde_solver: SDESimulatorConfig = dataclasses.field( - default_factory=_default_diffrax_sde_solver - ) - - def __post_init__(self) -> None: - if self.sde_solver.source != "diffrax": - raise ValueError( - "DiffraxSampleConfig requires sde_solver.source='diffrax', " - f"got source={self.sde_solver.source!r}." - ) - - -type DiscretizerConfig = ( - ODEFlowConfig - | EulerMaruyamaConfig - | ExactAffineConfig - | LocalLinearizationConfig - | MeanTrajectoryLinearizationConfig - | DiffraxSampleConfig +warnings.warn( + "dynestyx.inference.configs.discretizer is deprecated; use " + "dynestyx.configs.discretizer instead.", + DeprecationWarning, + stacklevel=2, ) diff --git a/dynestyx/inference/configs/filter.py b/dynestyx/inference/configs/filter.py index 3490e3c01..3ac766eff 100644 --- a/dynestyx/inference/configs/filter.py +++ b/dynestyx/inference/configs/filter.py @@ -1,1017 +1,12 @@ -"""Filter configuration dataclasses. Shared by dispatchers and integration backends.""" +"""Deprecated compatibility module for :mod:`dynestyx.configs.filter`.""" -import abc -import dataclasses -import math -from collections.abc import Callable -from typing import Any, Literal, Protocol +import warnings -import jax.numpy as jnp -import jax.random as jr -from cuthbertlib.types import ScalarArrayLike -from jaxtyping import Array, ArrayLike, PRNGKeyArray +from dynestyx.configs.filter import * # noqa: F403 -from dynestyx.utils.validation import _validate_nonnegative_float - -ResamplingBaseMethod = Literal["systematic", "multinomial", "stratified"] -ResamplingDifferentiableMethod = Literal["stop_gradient", "straight_through", "soft"] -FilterEmissionOrder = Literal["zeroth", "first", "second"] -FilterStateOrder = Literal["zeroth", "first", "second"] - -CuthbertOnlyFilterSource = Literal["cuthbert"] -CDDynamaxOnlyFilterSource = Literal["cd_dynamax"] -DynestyxOnlyFilterSource = Literal["dynestyx"] -FilterSource = ( - CuthbertOnlyFilterSource | CDDynamaxOnlyFilterSource | DynestyxOnlyFilterSource +warnings.warn( + "dynestyx.inference.configs.filter is deprecated; use " + "dynestyx.configs.filter instead.", + DeprecationWarning, + stacklevel=2, ) -CuthbertOrCDDynamaxFilterSource = CuthbertOnlyFilterSource | CDDynamaxOnlyFilterSource - -TaperCovarianceFn = Callable[[Array], Array] - - -class ModifyCrossCovariance(Protocol): - """Modify an empirical state-observation cross-covariance.""" - - def __call__( - self, - cross_covariance: Array, - model_inputs: Any, - ) -> Array: - """Return a cross-covariance with the same shape as the input.""" - ... - - -class ConstructCholInnovationCovariance(Protocol): - """Construct a generalized factor of an EnKF innovation covariance.""" - - def __call__( - self, - normalized_observation_deviations: Array, - chol_observation_covariance: Array, - model_inputs: Any, - ) -> Array: - """Return an observation-by-observation innovation factor.""" - ... - - -class ModifyPredictedObservationCovariance(Protocol): - """Modify an empirical covariance used for predictive scoring.""" - - def __call__( - self, - predicted_observation_covariance: Array, - model_inputs: Any, - ) -> Array: - """Return a predictive covariance with the same shape as the input.""" - ... - - -@dataclasses.dataclass(frozen=True) -class EnKFLocalizationConfig: - r"""Distance-based covariance localization for a discrete-time EnKF. - - The state-observation taper modifies the empirical cross-covariance used - in every EnKF update. Supplying ``observation_distances`` additionally - localizes the empirical observation covariance in the innovation matrix - and in Dynestyx predictive-observation scores. - - Built-in ``"gaspari_cohn"`` and ``"gaussian"`` tapers require a positive - scalar ``taper_scale``. A custom callable receives a distance matrix and - must close over any hyperparameters itself, so ``taper_scale`` must then be - ``None``. Custom callables may close over JAX tracers and remain - differentiable. - - Attributes: - state_observation_distances: Matrix with shape - ``(state_dim, observation_dim)``. - taper_scale: Full support radius for Gaspari-Cohn or length scale for - the Gaussian taper. Must be ``None`` for a custom taper callable. - taper: Built-in taper name or a callable mapping distances to taper - values with the same shape. - observation_distances: Optional symmetric observation-by-observation - distance matrix with a zero diagonal. When omitted, only the - state-observation cross-covariance is localized. - """ - - state_observation_distances: ArrayLike - taper_scale: ScalarArrayLike | None = None - taper: Literal["gaspari_cohn", "gaussian"] | TaperCovarianceFn = "gaspari_cohn" - observation_distances: ArrayLike | None = None - - def __post_init__(self): - self._validate() - - def _validate(self): - """Check configuration at construction and again before resolution.""" - if callable(self.taper): - if self.taper_scale is not None: - raise ValueError( - "EnKFLocalizationConfig with a custom taper callable requires " - "taper_scale=None; close over custom hyperparameters in the callable." - ) - return - - if not isinstance(self.taper, str) or self.taper not in { - "gaspari_cohn", - "gaussian", - }: - raise ValueError( - "Unsupported EnKF localization taper " - f"{self.taper!r}; expected 'gaspari_cohn', 'gaussian', or a callable." - ) - if self.taper_scale is None: - raise ValueError( - f"EnKFLocalizationConfig(taper={self.taper!r}) requires a positive " - "scalar taper_scale." - ) - if jnp.asarray(self.taper_scale).shape != (): - raise ValueError("EnKF localization taper_scale must be a scalar.") - - -@dataclasses.dataclass(frozen=True) -class EnKFLocalizationFunctions: - """Advanced callback-based localization for a discrete-time EnKF. - - The first two callbacks follow Cuthbert's high-level EnKF callback - signatures. The predictive covariance callback receives the raw empirical - observation covariance and the same per-time model inputs. An innovation - constructor and predictive covariance modifier must be supplied together - so filtering likelihoods and Dynestyx predictive scores use consistent - covariance localization. - """ - - modify_cross_covariance: ModifyCrossCovariance | None = None - construct_chol_innovation_covariance: ConstructCholInnovationCovariance | None = ( - None - ) - modify_predicted_observation_covariance: ( - ModifyPredictedObservationCovariance | None - ) = None - - def __post_init__(self): - self._validate() - - def _validate(self): - """Check configuration at construction and again before resolution.""" - callbacks = ( - self.modify_cross_covariance, - self.construct_chol_innovation_covariance, - self.modify_predicted_observation_covariance, - ) - if all(callback is None for callback in callbacks): - raise ValueError( - "EnKFLocalizationFunctions requires at least one localization callback." - ) - for callback in callbacks: - if callback is not None and not callable(callback): - raise TypeError("EnKF localization callbacks must be callable or None.") - if (self.construct_chol_innovation_covariance is None) != ( - self.modify_predicted_observation_covariance is None - ): - raise ValueError( - "construct_chol_innovation_covariance and " - "modify_predicted_observation_covariance must be supplied together." - ) - - -@dataclasses.dataclass(frozen=True) -class BaseFilterConfig(abc.ABC): - r"""Shared configuration options inherited by all filter configs. - - You do not instantiate this class directly; use one of the concrete - subclasses (e.g. `KFConfig`, `PFConfig`). - - Config fields are immutable after construction. Use `dataclasses.replace` - to create an updated config; nested objects such as dictionaries are not - recursively frozen. - - The `record_*` fields let you save intermediate filtering outputs into the - NumPyro trace as `numpyro.deterministic` sites, making them accessible - after inference (e.g. for plotting filtered trajectories). `None` defers - to the backend's default for that quantity. - - Attributes: - record_filtered_states_mean (bool | None): Save the posterior mean - \(\mathbb{E}[x_t \mid y_{1:t}]\) at each time step. - record_filtered_states_cov (bool | None): Save the full posterior - covariance at each step. Can be large — prefer - `record_filtered_states_cov_diag` for high-dimensional states. - record_filtered_states_cov_diag (bool | None): Save only the marginal - variances (diagonal of the covariance) at each step. - record_filtered_states_chol_cov (bool | None): Save the Cholesky - factor of the posterior covariance (Gaussian filters only). - record_filtered_particles (bool | None): Save the full particle array - at each step (particle-based filters only). - record_filtered_log_weights (bool | None): Save the log importance - weights at each step (particle-based filters only). - include_predicted_observations (bool): Collect supported one-step-ahead - predictive-observation outputs in ``ConditionedResult``. This is - independent of whether those outputs are recorded to a NumPyro - trace. Defaults to `True`. - record_predicted_observations_mean (bool): Save the one-step-ahead - predicted observation mean at each observation time, before - conditioning on that observation. Defaults to `True`. - record_predicted_observations_cov (bool): Save the backend predicted - observation covariance before observation noise is added. Defaults - to `True`. - record_predicted_observations_ensemble (bool): Save the backend - predicted observation ensemble before observation noise is added - (ensemble filters only). Defaults to `True` when available. - record_max_elems (int): Hard cap on total scalar elements saved across - all `record_*` sites. Prevents accidentally filling device memory - for long sequences or large state spaces. Defaults to `100_000`. - cov_rescaling (float | None): Multiply all predicted covariances by - this factor before the update. Values slightly above `1.0` - implement covariance inflation, which can improve robustness when - the model is misspecified. `None` disables rescaling. - crn_seed (PRNGKeyArray | None): Fix the PRNG key for stochastic filters - (EnKF, PF). Useful when differentiating through the filter: - a fixed key makes the randomness a deterministic function of model - parameters. `None` draws a fresh key each call. - warn (bool): Whether or not to suppress warnings from filtering backends. - Defaults to `True`. - filter_source (FilterSource | None): Internal backend library. Set by - each subclass; rarely needs to be changed manually. - extra_filter_kwargs (dict): Extra keyword arguments passed directly to - the backend. Useful for advanced backend-specific options. - """ - - extra_filter_kwargs: dict = dataclasses.field(default_factory=dict) - warn: bool = True - record_filtered_states_mean: bool | None = None - record_filtered_states_cov: bool | None = None - record_filtered_states_cov_diag: bool | None = None - record_filtered_particles: bool | None = None - record_filtered_log_weights: bool | None = None - record_filtered_states_chol_cov: bool | None = None - include_predicted_observations: bool = True - record_predicted_observations_mean: bool = True - record_predicted_observations_cov: bool = True - record_predicted_observations_ensemble: bool = True - record_max_elems: int = 100_000 - filter_source: FilterSource | None = None - cov_rescaling: float | None = None - crn_seed: PRNGKeyArray | None = None - - -@dataclasses.dataclass(frozen=True) -class EnKFBaseConfig(BaseFilterConfig): - """Shared options for discrete- and continuous-time EnKF configs.""" - - n_particles: int = 30 - crn_seed: PRNGKeyArray | None = dataclasses.field( - default_factory=lambda: jr.PRNGKey(0) - ) - perturb_measurements: bool | None = None - inflation_delta: float | None = None - localization: EnKFLocalizationConfig | EnKFLocalizationFunctions | None = None - recorded_filtered_states_cov_jitter: float = ( - 1e-5 # this is good for float32, may want to reduce for float64 - ) - ensemble_subspace: bool | None = None - - def __post_init__(self): - if self.ensemble_subspace and ( - self.localization is not None or self.filter_source != "cuthbert" - ): - raise ValueError( - "ensemble_subspace=True requires the Cuthbert backend " - "and no localization." - ) - if self.localization is not None and not isinstance( - self.localization, - EnKFLocalizationConfig | EnKFLocalizationFunctions, - ): - raise TypeError( - "EnKFConfig.localization must be EnKFLocalizationConfig, " - "EnKFLocalizationFunctions, or None." - ) - reserved_hooks = { - "modify_cross_covariance", - "construct_chol_innovation_covariance", - "modify_predicted_observation_covariance", - } - conflicts = sorted(reserved_hooks.intersection(self.extra_filter_kwargs)) - if conflicts: - raise ValueError( - "EnKF localization callback names are reserved in " - f"extra_filter_kwargs: {', '.join(conflicts)}. Use " - "EnKFLocalizationFunctions via EnKFConfig.localization instead." - ) - - # Check that the jitter is nonnegative float - _validate_nonnegative_float( - "recorded_filtered_states_cov_jitter", - self.recorded_filtered_states_cov_jitter, - ) - - -@dataclasses.dataclass(frozen=True) -class EnKFConfig(EnKFBaseConfig): - r"""Ensemble Kalman Filter (EnKF) for discrete-time models. - - The **default filter** for discrete-time models. A good general-purpose - filter for nonlinear models with Gaussian observations. Works with any - differentiable or non-differentiable dynamics and scales well to moderate - state dimensions. Cheaper per-step than the particle filter, but assumes - observations are approximately Gaussian given the ensemble. - - The observation noise covariance must be **state-independent** (it may - still depend on time or controls). Using a state-dependent scale with the - cuthbert backend raises a `ValueError`; if you need heteroscedastic noise, - use `PFConfig` instead. - - The primary tuning knob is `n_particles`, with more particles providing - more accurate results at the cost of higher compute. - If the ensemble collapses over long trajectories, increase - `inflation_delta` slightly (e.g. `0.05`–`0.2`). - - Supports missing observations via NaNs. - - Attributes: - n_particles (int): Number of ensemble members. More members give a - better covariance estimate at higher compute cost. Defaults to - `30`. - crn_seed (PRNGKeyArray | None): Fixed PRNG key for the ensemble. Defaults - to `jr.PRNGKey(0)`, i.e., common random numbers are used. This - can reduce variance in gradient-based learning, but introduces - further bias. - perturb_measurements (bool | None): Add noise to observations before - the ensemble update (stochastic EnKF). Set `False` for the - square-root variant. `None` defers to the backend default. - inflation_delta (float | None): Scale ensemble anomalies by - \(\sqrt{1 + \delta}\) before the update to prevent collapse. - `None` disables inflation. - localization (EnKFLocalizationConfig | EnKFLocalizationFunctions | None): - Optional structured covariance localization. Distance-based - localization provides built-in Gaussian and Gaspari-Cohn tapers or - accepts a custom covariance callable. Advanced users can instead - supply Cuthbert-compatible callbacks. - ensemble_subspace (bool | None): Perform the update in ensemble space. - `None` selects it when `n_particles < observation_dim` and - localization is absent. `True` forces it and `False` disables it. - Available only with the Cuthbert backend and without localization. - This may be more efficient when `n_particles` < `state_dim`, and almost - certainly more efficient if `n_particles` << `state_dim`, but may interfere - with localization. See [the Cuthbert documentation](https://state-space-models.github.io/cuthbert/api_cuthbert/ensemble_kalman/ensemble_kalman_filter/) - for more details. - recorded_filtered_states_cov_jitter (float): Nonnegative \(\epsilon\) added to - the **recorded** filtered-state covariance as \(\epsilon I\). - This only affects the covariance when converted to a `MultivariateNormal` or `LowRankMultivariateNormal` - distribution (notably those returned in `ConditionedResult.dists`); it never - enters the EnKF update, the filter recursion, or the marginal - likelihood. - When `n_particles - 1 < state_dim`, the ensemble covariance is singular, - this regularization is necessary to give the recorded distributions a well-defined density (sampling will work nonetheless). - Defaults to `1e-5`. Will work for variance around 1, but may need a bigger value - for larger magnitudes and may want to reduce when using float64. Pass `0.0` for the exact, unregularised covariance. - filter_source (FilterSource): Backend. Defaults to `"cuthbert"`. - - ??? note "Algorithm Reference" - The ensemble Kalman filter comprises ensemble members $x_t^{(i)}, i = 1, \ldots, N_{\text{particles}}$. - There are many implementation tricks in the EnKF; we describe the basic version here. - - For each time step \(t\), the ensemble is propagated forward by the transition model: - - $$ - \hat{x}_t^{(i)} = f(x_t^{(i)}, u_t, t_t) + \epsilon_t^{(i)}, - $$ - - where \(u_t\) is the control input at time \(t\) and \(t_t\) is the time of the transition, - and \(\epsilon_t^{(i)} \sim \mathcal{N}(0, Q)\) is the process noise. - - Each ensemble member is then updated using observations: - - $$ - x_t^{(i)} = \hat{x}_t^{(i)} + \hat{K}_t^{(i)} \left(y_t - h(x_t^{(i)}, u_t, t_t)\right), - $$ - - where $\hat{K}_t^{(i)}$ is the Kalman gain for the \(i\)-th ensemble member, computed as - - $$ - \hat{K}_t^{(i)} = \hat{P}_t^{(i)} H^\top (H \hat{P}_t^{(i)} H^\top + R)^{-1}, - $$ - - where $\hat{P}_t^{(i)}$ is the empirical covariance of the particles, and $R$ is the - covariance of the observation model. - - The resulting estimator is known to be biased for non-linear observations, but is often rather - robust in practice to moderate nonlinearities. It is particualrly effective for high-dimensional - inverse problems, where other particle methods like particle filters often struggle. - - References: - - - The implementation details are due to: Sanz-Alonso, D., Stuart, A. M., & Taeb, A. (2018). - Inverse problems and data assimilation. [arXiv:1810.06191](https://arxiv.org/abs/1810.06191). - - For a classical reference to the ensemble Kalman filter, see: Evensen, G. (2003). - The ensemble Kalman filter: Theoretical formulation and practical implementation. Ocean Dynamics, 53(4), 343-367. - - The solution using automatic differentiation for nonlinear dynamics is due to: Chen, Y., Sanz-Alonso, D., & Willett, R. (2022). - Autodifferentiable ensemble Kalman filters. SIAM Journal on Mathematics of Data Science, 4(2), 801-833. - [Available Online](https://epubs.siam.org/doi/abs/10.1137/21M1434477). - """ - - filter_source: CuthbertOnlyFilterSource = "cuthbert" - - -@dataclasses.dataclass(frozen=True) -class PFResamplingConfig: - """Resampling strategy for particle-based filters. - - The defaults (`"systematic"`, `"stop_gradient"`) are appropriate for most - workflows. The resampling step includes both a non-differentiable base method, - and a differentiable method for handling gradients. - - For most problems, especially with bootstrap particle filters, the `stop_gradient` method is preferred. - The `soft` method can be useful when a non-bootstrap PF is used and gradients are required to flow through the resampling step. - The `straight_through` approach is biased on the backwards pass, and is not recommended, but is okay to use for gradient-free inference. - - Attributes: - base_method (ResamplingBaseMethod): Algorithm used to draw new - particles from the weight distribution. `"systematic"` *(default)* - has the lowest variance and is preferred in most cases. - `"multinomial"` and `"stratified"` are also available. - differential_method (ResamplingDifferentiableMethod): How gradients - are handled across the discrete resampling step. - `"stop_gradient"` *(default)* treats indices as constants. - `"straight_through"` or `"soft"` allow gradients to pass through - (needed for gradient-based training of model parameters). - softness (float): Temperature for soft resampling. Only used when - `differential_method="soft"`. Lower values are closer to non-differentiable resampling, - and higher values are closer to the differentiable method. Defaults to `0.7`. - - ??? note "Algorithm Reference" - The stop gradient method provides an unbiased score estimate for the marginal likelihood via the classical Fisher estimate. - This is accomplished directly through automatic differentiation. For non-bootstrap filters, the proposal estimates will be biased. - - The soft resampling method provides biased score estimates, but propagates gradients through the reasmpling step. It is fast. - - References: - - - For the stop_gradient method, see: Ścibior, A., & Wood, F. (2021). - Differentiable particle filtering without modifying the forward pass. [arXiv:2106.10314](https://arxiv.org/abs/2106.10314). - - For the soft method, see: Karkus, P., Hsu, D., & Lee, W. S. (2018, October). Particle filter networks with application to visual localization. - In Conference on Robot Learning (pp. 169-178). [Available Online](https://proceedings.mlr.press/v87/karkus18a.html). - - For a recent review of differentiable particle filters, see: Brady, J. J., Cox, B., Li, Y., & Elvira, V. (2025). - PyDPF: A Python Package for Differentiable Particle Filtering. [arXiv:2510.25693](https://arxiv.org/abs/2510.25693). - """ - - base_method: ResamplingBaseMethod = "systematic" - differential_method: ResamplingDifferentiableMethod = "stop_gradient" - softness: float = 0.7 - - -@dataclasses.dataclass(frozen=True) -class PFBaseConfig(BaseFilterConfig): - """Shared options for discrete- and continuous-time PF configs.""" - - n_particles: int = 1_000 - resampling_method: PFResamplingConfig = dataclasses.field( - default_factory=PFResamplingConfig - ) - ess_threshold_ratio: float = 0.7 - - -@dataclasses.dataclass(frozen=True) -class PFConfig(PFBaseConfig): - r"""Bootstrap Particle Filter (PF) for discrete-time models. - - The most flexible filter: works with any model, including non-Gaussian - observations and highly nonlinear dynamics. - The main cost is that accuracy scales with the number of particles, so - large state dimensions can become expensive. - - The primary tuning knob is `n_particles`. Estimates will generally get better - and less noisy with more particles, but introduces a linear computational cost. - `ess_threshold_ratio` controls the frequency of resampling; sampling more frequently - can help avoid particle degeneracy, but also increases variance. - - NaN-valued `obs_values` are allowed, but they are not treated specially by - the particle filter. Whether missing observations work correctly is up to - the user-specified transition and observation functions to handle NaNs - appropriately. A warning is emitted when NaNs are detected in `obs_values`. - - Attributes: - n_particles (int): Number of particles. More particles give a lower- - variance log-likelihood estimate at linear compute cost. Defaults - to `1_000`. - resampling_method (PFResamplingConfig): Controls the resampling - algorithm and gradient behaviour. See `PFResamplingConfig`. - Defaults to systematic resampling with stop-gradient. - ess_threshold_ratio (float): Resampling fires when the effective - sample size drops below `ess_threshold_ratio * n_particles`. - `1.0` → always resample; `0.0` → never. Defaults to `0.7`. - filter_source (FilterSource): Backend. Defaults to `"cuthbert"`, which is currently the only available implementation. - - ??? note "Algorithm Reference" - At each step, particles are propagated through the transition and - reweighted by the observation likelihood. The resulting empirical distribution - is asymptotically exact to the true filtering distribution as the number of particles goes to infinity. - The marginal log-likelihood without a resampling step is estimated as: - - \[ - \log p(y_{1:T}) \approx \sum_{t=1}^T \log \frac{1}{N} - \sum_{i=1}^N \tilde{w}_t^{(i)} - \] - - where $\tilde{w}_t^{(i)}$ is the are unnormalized weights of each particle. - - There are several different resampling algorithms available, which result in different - approximations of the score function $\nabla_\theta \log p(y_{1:T} | \theta)$. - For more information on these options, see `PFResamplingConfig`. - - References: - - - For a classical reference to particle filters, see: Doucet, A., De Freitas, N., & Gordon, N. (2001). An Introduction to Sequential Monte Carlo Methods. - In Sequential Monte Carlo Methods in Practice (pp. 3-14). New York, NY: Springer New York. - - For a more modern textbook, see Chapter 11.4 of: Särkkä, S., & Svensson, L. (2023). - Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. - [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). - - For a more recent review of differentiable particle filters, see: Brady, J. J., Cox, B., Li, Y., & Elvira, V. (2025). - PyDPF: A Python Package for Differentiable Particle Filtering. [arXiv:2510.25693](https://arxiv.org/abs/2510.25693). - """ - - filter_source: CuthbertOnlyFilterSource = "cuthbert" - - -@dataclasses.dataclass(frozen=True) -class EKFConfig(BaseFilterConfig): - r"""Extended Kalman Filter (EKF) for discrete-time models. - - The EKF linearizes nonlinear dynamics at the current mean estimate - via a first-order Taylor expansion. It is fast and simple, but may - not work well for strongly nonlinear models. The Taylor series expansion - is automatically performed via Jax autodiff. - - This is exact (but wasteful) for linear-Gaussian models. - - In the current interface with the `cd_dynamax` discrete-time backend, - time-varying models silently ignore absolute time arguments. - For genuinely time-varying discrete-time models, use a - backend/configuration that preserves absolute time semantics, such as - `EnKFConfig(filter_source="cuthbert")`. Only use - `filter_source="cd_dynamax"` for time-invariant models. - - Does not support missing observations (data cannot have NaNs). - - Attributes: - filter_emission_order (FilterEmissionOrder): Linearisation order for - the observation function. `"first"` *(default)* is the standard - Jacobian-based EKF. `"second"` reduces bias for strongly curved - observation maps at the cost of Hessian computation. `"zeroth"` - skips observation linearisation. - filter_source (FilterSource): Backend. Defaults to `"cuthbert"`. - - ??? note "Algorithm Reference" - The EKF propagates a Gaussian approximation - \(\mathcal{N}(\hat x_{t|t}, P_{t|t})\) through Jacobian - linearizations of \(f\) and \(h\): - - \[ - \hat x_{t|t-1} = f(\hat x_{t-1|t-1}), - \quad P_{t|t-1} = F_t P_{t-1|t-1} F_t^\top + Q_t - \] - - where $F_t$ is the Jacobian of $f$ at $\hat x_{t|t-1}$, - and proceeds via the typical Kalman update. - - References: - - - The `cuthbert` implementation of the EKF is based on the `taylor_kf` module therein. - See the [cuthbert documentation](https://state-space-models.github.io/cuthbert/cuthbert_api/gaussian/taylor/) for more information. - - For a more modern textbook reference, see Chapter 7 of: Särkkä, S., & Svensson, L. (2023). - Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. - [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). - """ - - filter_source: CuthbertOrCDDynamaxFilterSource = "cuthbert" - filter_emission_order: FilterEmissionOrder = "first" - - -@dataclasses.dataclass(frozen=True) -class KFConfig(BaseFilterConfig): - r"""Kalman Filter (KF) for discrete-time linear-Gaussian models. - - The exact Bayesian filter for linear-Gaussian state-space models; requires - a model built with `LTI_discrete` or using - `LinearGaussianStateEvolution` + `LinearGaussianObservation`. For - nonlinear Gaussian models, use `EKFConfig`, `UKFConfig`, or `EnKFConfig` instead. - - Supports missing observations via NaNs when `filter_source="cuthbert"`. Does not support missing observations (data cannot have NaNs) when `filter_source="cd_dynamax"`. - - Time-varying linear-Gaussian models (callable `(t_now, t_next)` / `(t,)` - parameters on `LinearGaussianStateEvolution` / - `LinearGaussianObservation`) are supported only with - `filter_source="cuthbert"`; `filter_source="cd_dynamax"` raises - `TypeError` for callable parameters. - - Attributes: - filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. - associative (bool | None): Whether to enable cuthbert's associative - parallel-in-time scan. This is only supported when - `filter_source="cuthbert"`. Defaults to `None`, which selects - an associative scan if `filter_source="cuthbert"`, and a - sequential scan otherwise. - - ??? note "Algorithm Reference" - When the dynamics and observation process of a dynamical system are both linear-Gaussian, - the recursive updates can be computed in closed form. - - This proceeds via a "prediction" step, where the mean and covariance are propagated forward in time, - and an "update" step, where the mean and covariance are updated with the observation. - - The prediction step is given by: - - $$ - \hat x_{t|t-1} = A \hat x_{t-1|t-1} + b, - \quad P_{t|t-1} = A P_{t-1|t-1} A^\top + Q - $$ - - The update step is given by: - - $$ - \hat x_{t|t} = \hat x_{t|t-1} + K_t (y_t - H \hat x_{t|t-1}), - \quad P_{t|t} = (I - K_t H) P_{t|t-1} - $$ - - where $K_t$ is the Kalman gain. - - The Kalman gain is given by: - - $$ - K_t = P_{t|t-1} H^\top (H P_{t|t-1} H^\top + R)^{-1} - $$ - - where $H$ is the Jacobian of $h$ at $\hat x_{t|t-1}$. - - There are variants to the particular algorithm; the `cuthbert` implementation is the so-called "square root" form. - This provides a more numerically stable implementation of the Kalman filter. - - References: - - - For the classsical reference, see: Kalman, R. E. (1960). - A New Approach to Linear Filtering and Prediction Problems. Journal of Basic Engineering, 82(1), 35-45. - - For a more modern textbook reference, see Chapter 6 of: Särkkä, S., & Svensson, L. (2023). - Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. - [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). - - For more details on the `cuthbert` implementation, see the [cuthbert documentation](https://state-space-models.github.io/cuthbert/cuthbert_api/gaussian/kalman/). - """ - - filter_source: CuthbertOrCDDynamaxFilterSource = "cd_dynamax" - associative: bool | None = None - - def __post_init__(self): - if self.associative is None: - object.__setattr__(self, "associative", self.filter_source == "cuthbert") - - if self.associative and self.filter_source != "cuthbert": - raise ValueError( - "KFConfig(associative=True) is only supported with " - "filter_source='cuthbert'." - ) - - -@dataclasses.dataclass(frozen=True) -class UKFConfig(BaseFilterConfig): - r"""Unscented Kalman Filter (UKF) for discrete-time models. - - A derivative-free Gaussian filter that handles stronger nonlinearities - than the EKF by propagating a small, deterministic set of *sigma points* - through the dynamics. No Jacobians are computed. Slightly more expensive - than the EKF but often more accurate on curved manifolds. - - The default parameters (`alpha`, `beta`, `kappa`) work well for most - problems; they rarely need to be changed. - - In the current interface with the `cd_dynamax` discrete-time backend, - time-varying models silently ignore absolute time arguments. - For genuinely time-varying discrete-time models, use a - backend/configuration that preserves absolute time semantics, such as - `EKFConfig(filter_source="cuthbert")`. Only use - `filter_source="cd_dynamax"` for time-invariant models. - - Does not support missing observations (data cannot have NaNs). - - Attributes: - alpha (float): Spread of sigma points around the current mean. - Smaller → tighter cluster; larger → sigma points reach further. - Defaults to \(\sqrt{3}\). - beta (int): Encodes prior knowledge about the distribution shape. - `2` is optimal for Gaussians. Defaults to `2`. - kappa (int): Secondary scaling parameter. Defaults to `1`. - filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. - - ??? note "Algorithm Reference" - For a state of dimension \(n\), \(2n+1\) sigma points are placed as: - - $$ - \mathcal{X}_0 = \hat x, \quad - \mathcal{X}_i = \hat x \pm \sqrt{(n + \lambda) P}_i, \quad - \lambda = \alpha^2 (n + \kappa) - n - $$ - - Each sigma point is propagated through \(f\) and \(h\); the outputs - are recombined with weights depending on \(\alpha, \beta, \kappa\) to - recover the predicted mean and covariance. - - References: - - For the original paper, see: Julier, S. J., & Uhlmann, J. K. (1997). New extension of the Kalman filter to nonlinear systems. SPIE Proceedings, 3068. - - For a more modern textbook reference, see Section 8.8 of: Särkkä, S., & Svensson, L. (2023). - Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. - [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). - """ - - alpha: float = math.sqrt(3) - beta: int = 2 - kappa: int = 1 - filter_source: CDDynamaxOnlyFilterSource = "cd_dynamax" - - -@dataclasses.dataclass(frozen=True) -class ContinuousTimeConfig: - """Solver options shared by all continuous-discrete filter configs. - - Between observation times, the filter propagates a distribution (or - ensemble/particles) forward in continuous time by solving an ODE/SDE - numerically. These options control that solver. - - Attributes: - filter_state_order (FilterStateOrder): Accuracy of the continuous-time - propagation between observations. `"first"` *(default)* propagates - both mean and covariance (sufficient for most problems). `"zeroth"` - propagates only the mean (faster, less accurate). `"second"` adds - a higher-order correction for strongly nonlinear drifts. - diffeqsolve_max_steps (int): Maximum ODE solver steps between any two - consecutive observations. Increase if the solver hits this limit - (stiff dynamics or very long inter-observation gaps). Defaults to - `1_000`. - diffeqsolve_dt0 (float): Initial step-size hint for the solver. - Adaptive solvers adjust this automatically; fixed-step solvers - use it as the constant step. Defaults to `0.01`. - diffeqsolve_kwargs (dict): Additional kwargs forwarded to - `diffrax.diffeqsolve` (e.g. `solver`, `stepsize_controller`, - `adjoint`). Defaults to `{}`. - """ - - filter_state_order: FilterStateOrder = "first" - diffeqsolve_max_steps: int = 1_000 - diffeqsolve_dt0: float = 0.01 - diffeqsolve_kwargs: dict = dataclasses.field(default_factory=dict) - - -@dataclasses.dataclass(frozen=True) -class ContinuousTimeKFConfig(BaseFilterConfig, ContinuousTimeConfig): - r"""Continuous-discrete Kalman Filter (CD-KF). - - The exact Bayesian filter for continuous-time linear-Gaussian models. - Use this when your model was built with `LTI_continuous`. For nonlinear - SDEs, use `ContinuousTimeEKFConfig`, `ContinuousTimeUKFConfig`, or - `ContinuousTimeEnKFConfig`. - - Does not support missing observations (data cannot have NaNs). - - Inherits solver options from `ContinuousTimeConfig` and recording - options from `BaseFilterConfig`. - - Attributes: - filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. - - ??? note "Algorithm Reference" - Between observations the mean and covariance evolve via the - Kalman–Bucy ODEs: - - $$ - \dot{\hat x} = A \hat x + B u, - \quad \dot P = A P + P A^\top + L Q L^\top - $$ - - At each observation the standard Kalman update is applied. - - References: - - - For a modern textbook reference, see Chapter 10.6 of: Särkkä, S., & Solin, A. (2019). - Applied Stochastic Differential Equations. Cambridge University Press. - [Available Online](https://users.aalto.fi/~asolin/sde-book/sde-book.pdf). - """ - - filter_source: CDDynamaxOnlyFilterSource = "cd_dynamax" - - -@dataclasses.dataclass(frozen=True) -class ContinuousTimeEnKFConfig(EnKFBaseConfig, ContinuousTimeConfig): - r"""Continuous-discrete Ensemble Kalman Filter (CD-EnKF). - - The **default filter** for continuous-time models. Each ensemble member - is propagated forward by solving the SDE between observations; the - ensemble Kalman update is applied at observation times. Works with any - SDE model without requiring gradients. - - Does not support missing observations (data cannot have NaNs). - - Localization is not available in this continuous-time backend. To localize - a deterministic continuous-time model, wrap it in `Discretizer` and use - the Cuthbert-backed discrete `EnKFConfig`. - - See `EnKFConfig` for particle/ensemble tuning options and - `ContinuousTimeConfig` for solver options. - - Attributes: - filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. - - ??? note "Algorithm Reference" - References: - - - The implementation details are due to: Sanz-Alonso, D., Stuart, A. M., & Taeb, A. (2018). - Inverse problems and data assimilation. [arXiv:1810.06191](https://arxiv.org/abs/1810.06191). - - For a classical reference to the ensemble Kalman filter, see: Evensen, G. (2003). - The ensemble Kalman filter: Theoretical formulation and practical implementation. Ocean Dynamics, 53(4), 343-367. - - The solution using automatic differentiation for nonlinear dynamics is due to: Chen, Y., Sanz-Alonso, D., & Willett, R. (2022). - Autodifferentiable ensemble Kalman filters. SIAM Journal on Mathematics of Data Science, 4(2), 801-833. - [Available Online](https://epubs.siam.org/doi/abs/10.1137/21M1434477). - """ - - filter_source: CDDynamaxOnlyFilterSource = "cd_dynamax" - - def __post_init__(self): - super().__post_init__() - if self.localization is not None: - raise ValueError( - "ContinuousTimeEnKFConfig does not support localization. Wrap the " - "continuous model in Discretizer and use the Cuthbert-backed " - "discrete EnKFConfig instead." - ) - - -@dataclasses.dataclass(frozen=True) -class ContinuousTimeDPFConfig(PFBaseConfig, ContinuousTimeConfig): - r"""Continuous-discrete Differentiable Particle Filter (CD-DPF). - - Particle filter for continuous-time SDEs. Particles are propagated by - solving the SDE between observations; importance weights are updated at - each observation time. Supports non-Gaussian observations and arbitrary - nonlinear dynamics. - - Does not support missing observations (data cannot have NaNs). - - Uses multinomial resampling by default (vs. systematic in `PFConfig`) - for better compatibility with gradient-based training. - - See `PFConfig` for particle tuning options and `ContinuousTimeConfig` - for solver options. - - Attributes: - filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. - resampling_method (PFResamplingConfig): Defaults to - `PFResamplingConfig(base_method="multinomial")`. - - ??? note "Algorithm Reference" - The bootstrap version of the continuous-discrete PF is the same as the discrete-time PF version. - See `PFConfig` for more information. - """ - - filter_source: CDDynamaxOnlyFilterSource = "cd_dynamax" - resampling_method: PFResamplingConfig = dataclasses.field( - default_factory=lambda: PFResamplingConfig(base_method="multinomial") - ) - - -@dataclasses.dataclass(frozen=True) -class ContinuousTimeEKFConfig(EKFConfig, ContinuousTimeConfig): - r"""Continuous-discrete Extended Kalman Filter (CD-EKF). - - Fast Gaussian filter for mildly nonlinear SDEs. Requires differentiable - dynamics (JAX autodiff is used). The moment equations for the Gaussian - approximation are solved between observations and a Kalman update is - applied at each observation. - - Does not support missing observations (data cannot have NaNs). - - See `EKFConfig` for linearisation options and `ContinuousTimeConfig` - for solver options. - - Attributes: - filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. - - ??? note "Algorithm Reference" - References: - - - For a modern textbook reference, see Chapter 10.7 of: Särkkä, S., & Solin, A. (2019). - Applied Stochastic Differential Equations. Cambridge University Press. - [Available Online](https://users.aalto.fi/~asolin/sde-book/sde-book.pdf). - """ - - filter_source: CDDynamaxOnlyFilterSource = "cd_dynamax" - - -@dataclasses.dataclass(frozen=True) -class ContinuousTimeUKFConfig(UKFConfig, ContinuousTimeConfig): - """Continuous-discrete Unscented Kalman Filter (CD-UKF). - - Derivative-free Gaussian filter for nonlinear SDEs. Sigma points are - propagated through the SDE between observations; the unscented transform - is applied at each observation update. More accurate than CD-EKF for - strongly nonlinear drifts without requiring Jacobians. - - Does not support missing observations (data cannot have NaNs). - - See `UKFConfig` for sigma-point tuning options and `ContinuousTimeConfig` - for solver options. - - Attributes: - filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. - - ??? note "Algorithm Reference" - References: - - - For a modern textbook reference, see Section 10.8 of: Särkkä, S., & Solin, A. (2019). - Applied Stochastic Differential Equations. Cambridge University Press. - [Available Online](https://users.aalto.fi/~asolin/sde-book/sde-book.pdf). - """ - - filter_source: CDDynamaxOnlyFilterSource = "cd_dynamax" - - -DiscreteTimeConfigs: tuple[type, ...] = ( - EnKFConfig, - PFConfig, - EKFConfig, - KFConfig, - UKFConfig, -) - -ContinuousTimeConfigs: tuple[type, ...] = ( - ContinuousTimeKFConfig, - ContinuousTimeEnKFConfig, - ContinuousTimeDPFConfig, - ContinuousTimeEKFConfig, - ContinuousTimeUKFConfig, -) - - -@dataclasses.dataclass(frozen=True) -class HMMConfig(BaseFilterConfig): - r"""Exact filter for Hidden Markov Models (finite discrete state space). - - Use this when your latent state takes values in a finite set (e.g. a - discrete regime model). The forward algorithm computes the exact marginal - log-likelihood and filtered belief over states at each time step. - - For continuous latent-state models, use any other filter config. - - Supports missing observations via NaNs. Fully missing rows are skipped by - neutralizing the observation term, and partial missing rows are supported for - exact-marginalizable observation families such as `MultivariateNormal` and - factorizable `Independent(..., 1)` observations. - - For categorical observations, encode observed entries as zero-based integer - labels `0..K-1` and represent missing entries with `NaN`. - - Attributes: - record_filtered (bool | None): Save the filtered state probabilities - \(p(z_t \mid y_{1:t})\) as a deterministic site. `None` defers to - the backend default. - record_log_filtered (bool | None): Save the log of the filtered state - probabilities as a deterministic site. `None` defers to the - backend default. - filter_source (FilterSource): Backend. Defaults to `"dynestyx"`. - - ??? note "Algorithm Reference" - At each step the belief vector \(\pi_t = p(z_t \mid y_{1:t})\) is - updated exactly: - - \[ - \pi_t^{\text{pred}} = T^\top \pi_{t-1}, \quad - \pi_t \propto \ell(y_t \mid z_t) \, \pi_t^{\text{pred}} - \] - - The log-likelihood is the sum of the log normalisation constants. - """ - - record_filtered: bool | None = None - record_log_filtered: bool | None = None - filter_source: DynestyxOnlyFilterSource = "dynestyx" - - -HMMConfigs: tuple[type, ...] = (HMMConfig,) - - -def _config_to_record_kwargs(config: BaseFilterConfig) -> dict: - """Build record_kwargs dict from config. Config must have all record_* fields.""" - if isinstance(config, HMMConfig): - return { - "record_filtered": config.record_filtered, - "record_log_filtered": config.record_log_filtered, - "record_max_elems": config.record_max_elems, - } - else: - return { - "record_filtered_states_mean": config.record_filtered_states_mean, - "record_filtered_states_cov": config.record_filtered_states_cov, - "record_filtered_states_cov_diag": config.record_filtered_states_cov_diag, - "record_filtered_particles": config.record_filtered_particles, - "record_filtered_log_weights": config.record_filtered_log_weights, - "record_filtered_states_chol_cov": config.record_filtered_states_chol_cov, - "record_predicted_observations_mean": config.record_predicted_observations_mean, - "record_predicted_observations_cov": config.record_predicted_observations_cov, - "record_predicted_observations_ensemble": config.record_predicted_observations_ensemble, - "record_max_elems": config.record_max_elems, - } diff --git a/dynestyx/inference/configs/mcmc.py b/dynestyx/inference/configs/mcmc.py index 304585d6e..b8b94eebc 100644 --- a/dynestyx/inference/configs/mcmc.py +++ b/dynestyx/inference/configs/mcmc.py @@ -1,229 +1,11 @@ -import dataclasses -import math -from collections.abc import Callable -from typing import Literal +"""Deprecated compatibility module for :mod:`dynestyx.configs.mcmc`.""" -import jax.numpy as jnp -from jax.typing import ArrayLike -from numpyro.infer.initialization import init_to_sample +import warnings -MCMCSource = Literal["numpyro", "blackjax"] +from dynestyx.configs.mcmc import * # noqa: F403 - -@dataclasses.dataclass -class BaseMCMCConfig: - """Shared configuration options inherited by all MCMC configs. - - You do not instantiate this class directly; use one of the concrete - subclasses (`NUTSConfig`, `HMCConfig`, `AdaptiveMWGConfig`, `AdaptiveMetropolisConfig`, - `SGLDConfig`, `MALAConfig`, `AdjustedMCLMCDynamicConfig`). - - Attributes: - num_samples (int): Number of post-warmup samples to return. - num_warmup (int): Number of warmup/burn-in transitions. - num_chains (int): Number of Markov chains to run in parallel. - mcmc_source (MCMCSource): Backend library used for inference. - Supported values are `"numpyro"` and `"blackjax"`. - init_strategy (callable): NumPyro initialization strategy used when - constructing unconstrained initial parameters. - """ - - num_samples: int - num_warmup: int - num_chains: int - mcmc_source: MCMCSource - init_strategy: Callable = init_to_sample - - -@dataclasses.dataclass -class HMCConfig(BaseMCMCConfig): - """Hamiltonian Monte Carlo (HMC) configuration. - - Attributes: - step_size (float): Integrator step size used by the leapfrog solver. - Ignored when ``adapt=True`` (step size is tuned during warmup). - num_steps (int): Number of leapfrog steps per HMC proposal. - adapt (bool): Whether to tune step size and mass matrix during warmup. - Defaults to ``True``. Set to ``False`` to use a fixed ``step_size`` - and identity mass matrix (useful when warmup is expensive or the - step size is known in advance). - """ - - step_size: float = 1e-2 - num_steps: int = 10 - adapt: bool = True - - -@dataclasses.dataclass -class NUTSConfig(BaseMCMCConfig): - """No-U-Turn Sampler (NUTS) configuration. - - Attributes: - target_acceptance_rate (float): Target acceptance probability used - during warmup. Must lie strictly between zero and one. - """ - - target_acceptance_rate: float = 0.8 - - def __post_init__(self) -> None: - if not 0.0 < self.target_acceptance_rate < 1.0: - raise ValueError("target_acceptance_rate must be between 0 and 1") - - -@dataclasses.dataclass -class _BaseAdaptiveRandomWalkConfig(BaseMCMCConfig): - """Shared options and validation for adaptive random-walk samplers.""" - - mcmc_source: MCMCSource = "blackjax" - initial_proposal_scale: ArrayLike = 1.0 - target_acceptance_rate: float = 0.44 - adaptation_rate: float = 0.5 - - def __post_init__(self) -> None: - if self.mcmc_source != "blackjax": - raise ValueError( - f"{type(self).__name__} only supports mcmc_source='blackjax'" - ) - if not 0.0 < self.target_acceptance_rate < 1.0: - raise ValueError("target_acceptance_rate must be between 0 and 1") - - if self.adaptation_rate <= 0.0: - raise ValueError("adaptation_rate must be positive") - - proposal_scale = jnp.asarray(self.initial_proposal_scale) - if proposal_scale.ndim > 1: - raise ValueError("initial_proposal_scale must be a scalar or 1D array") - if proposal_scale.size == 0 or not jnp.all(jnp.isfinite(proposal_scale)): - raise ValueError("initial_proposal_scale must contain finite values") - if jnp.any(proposal_scale <= 0.0): - raise ValueError("initial_proposal_scale must be positive") - - -@dataclasses.dataclass -class AdaptiveMWGConfig(_BaseAdaptiveRandomWalkConfig): - """Adaptive random-walk Metropolis-within-Gibbs configuration. - - One transition updates each flattened unconstrained coordinate in order. - Each coordinate update uses a one-dimensional Gaussian random-walk proposal - that is accepted or rejected before the next coordinate is visited; the - sampler does not make a single joint multivariate-normal proposal. Proposal - scales adapt during warmup toward the requested acceptance rate and remain - fixed while retained samples are generated. - - This sampler is currently implemented by the BlackJAX integration only. - - Attributes: - initial_proposal_scale (ArrayLike): Positive scalar proposal scale, or - one positive scale per flattened unconstrained coordinate. - target_acceptance_rate (float): Shared target acceptance rate applied - to each coordinate update. - adaptation_rate (float): Exponent in the diminishing adaptation step - ``n_iter ** -adaptation_rate``. - max_adaptation (float): Maximum change to a log proposal scale in one - warmup transition. - """ - - max_adaptation: float = 0.01 - - def __post_init__(self) -> None: - super().__post_init__() - if self.max_adaptation <= 0.0: - raise ValueError("max_adaptation must be positive") - - -@dataclasses.dataclass -class AdaptiveMetropolisConfig(_BaseAdaptiveRandomWalkConfig): - """Joint adaptive Gaussian random-walk Metropolis configuration. - - Each transition proposes the entire flattened unconstrained parameter - vector at once. The running mean, full covariance, and global covariance - multiplier adapt during warmup using Andrieu & Thoms (2008), Algorithm 4, - and remain frozen during sampling. The current log-density estimate is - cached across rejections, supporting pseudo-marginal inference when the - likelihood estimator is nonnegative and unbiased. - - This sampler supports only BlackJAX. - - Attributes: - initial_proposal_scale (ArrayLike): Positive finite scalar or vector - of initial scales for the flattened unconstrained coordinates. - The initial covariance is ``diag(scale ** 2)`` and the initial - global multiplier is ``2.38 ** 2 / d`` for dimension ``d``. - target_acceptance_rate (float): Target joint acceptance probability. - adaptation_rate (float): Exponent in the Robbins-Monro gain - ``initial_gain * (iteration + 1) ** -adaptation_rate``, - in ``(0.5, 1]``. - initial_gain (float): First warmup gain, finite and in ``(0, 1]``. - Defaults to ``2 ** -0.6``, retaining some initial covariance. - """ - - initial_proposal_scale: ArrayLike = 0.02 - target_acceptance_rate: float = 0.234 - adaptation_rate: float = 0.6 - initial_gain: float = 2**-0.6 - - def __post_init__(self) -> None: - super().__post_init__() - if not math.isfinite(self.adaptation_rate) or not ( - 0.5 < self.adaptation_rate <= 1.0 - ): - raise ValueError("adaptation_rate must be finite and in (0.5, 1]") - if not math.isfinite(self.initial_gain) or not (0.0 < self.initial_gain <= 1.0): - raise ValueError("initial_gain must be finite and in (0, 1]") - - -@dataclasses.dataclass -class SGLDConfig(BaseMCMCConfig): - r"""Stochastic Gradient Langevin Dynamics (SGLD) configuration. - - SGLD performs first-order Langevin updates using noisy gradients and - injected Gaussian noise. In this implementation, gradients are computed - on the full dataset (no minibatching), so the method behaves as - full-batch Langevin dynamics with an annealed step schedule. - - Attributes: - step_size (float): Base learning rate used in the SGLD schedule. - This should generally be small. - schedule_power (float): Power in the polynomial decay schedule - \(\epsilon_t = \text{step_size} \cdot t^{-\text{schedule_power}}\). - Values in `(0.5, 1.0]` are common for asymptotic convergence. - """ - - step_size: float = 1e-4 - schedule_power: float = 0.55 - - -@dataclasses.dataclass -class MALAConfig(BaseMCMCConfig): - """Metropolis-Adjusted Langevin Algorithm (MALA) configuration. - - Attributes: - step_size (float): Proposal step size used by `blackjax.mala`. - """ - - step_size: float = 1e-2 - - -@dataclasses.dataclass -class AdjustedMCLMCDynamicConfig(BaseMCMCConfig): - """Dynamic adjusted MCLMC (MHMCHMC) configuration. - - This maps to `blackjax.adjusted_mclmc_dynamic(...)` and uses its - top-level API arguments. - - Attributes: - step_size (float): Integrator step size. - L_proposal_factor (float): Proposal length scaling factor. - divergence_threshold (float): Energy-difference threshold used to flag - divergences. - integration_steps_min (int): Minimum random integration steps per - proposal. - integration_steps_max (int): Exclusive upper bound for random - integration steps per proposal. - """ - - step_size: float = 1e-2 - L_proposal_factor: float = float("inf") - divergence_threshold: float = 1000.0 - integration_steps_min: int = 1 - integration_steps_max: int = 10 +warnings.warn( + "dynestyx.inference.configs.mcmc is deprecated; use dynestyx.configs.mcmc instead.", + DeprecationWarning, + stacklevel=2, +) diff --git a/dynestyx/inference/configs/simulator.py b/dynestyx/inference/configs/simulator.py index ccb8ae9b5..fece3f4ba 100644 --- a/dynestyx/inference/configs/simulator.py +++ b/dynestyx/inference/configs/simulator.py @@ -1,172 +1,12 @@ -"""Configuration objects for continuous-time simulators.""" +"""Deprecated compatibility module for :mod:`dynestyx.configs.simulator`.""" -from __future__ import annotations +import warnings -import dataclasses -from typing import Any, Literal +from dynestyx.configs.simulator import * # noqa: F403 -import diffrax as dfx -from jaxtyping import Array, Real - -from dynestyx.types import as_scalar_time_array -from dynestyx.utils.validation import _raise_now_or_error_if - - -@dataclasses.dataclass -class ODESimulatorConfig: - """Configuration object for ODE simulators. - - Attributes: - solver (diffrax.AbstractSolver): Diffrax solver used for integration. - Defaults to `diffrax.Tsit5()`. See Diffrax's - [solver guide](https://docs.kidger.site/diffrax/usage/how-to-choose-a-solver/) - when selecting an alternative. IMEX solvers (e.g. `diffrax.KenCarp3/4/5`, - `diffrax.Sil3`) are supported, but require the state evolution's - `drift` to be an `ImExDrift` instance (see - `dynestyx.models.drifts.ImExDrift`), splitting the vector - field into `explicit_term`/`implicit_term`; conversely, using a - plain (non-`ImExDrift`) `drift` with an IMEX solver raises an - error. Using an `ImExDrift` with a non-IMEX solver is allowed - (both terms are summed) but emits a warning, since the split - goes unused. - adjoint (diffrax.AbstractAdjoint): Strategy used to differentiate - through the solve. Defaults to - `diffrax.RecursiveCheckpointAdjoint()`. - stepsize_controller (diffrax.AbstractStepSizeController): Step-size - policy used by Diffrax. Defaults to - `diffrax.ConstantStepSize()`; supply an adaptive controller when - error-controlled stepping is required. - dt0 (float | int | jax.Array): Initial step size passed to - `diffrax.diffeqsolve`. With the default constant-step controller, - this is the fixed integration step. Defaults to `1e-3`. - max_steps (int): Maximum number of integration steps permitted by - `diffrax.diffeqsolve`. Defaults to `100_000`. - throw (bool): Whether Diffrax raises when a solve fails. Set this to - `False` when inference should reject invalid parameter proposals - instead of aborting the complete run. Defaults to `True`. - - Properties: - diffeqsolve_settings (dict[str, Any]): Normalized keyword arguments passed - to `diffrax.diffeqsolve`; scalar time values are converted to JAX - arrays. - """ - - solver: dfx.AbstractSolver = dataclasses.field(default_factory=dfx.Tsit5) - adjoint: dfx.AbstractAdjoint = dataclasses.field( - default_factory=dfx.RecursiveCheckpointAdjoint - ) - stepsize_controller: dfx.AbstractStepSizeController = dataclasses.field( - default_factory=dfx.ConstantStepSize - ) - dt0: float | int | Real[Array, ""] = 1e-3 - max_steps: int = 100_000 - throw: bool = True - - @property - def diffeqsolve_settings(self) -> dict[str, Any]: - """Return normalized Diffrax settings for ``diffeqsolve``.""" - return { - "solver": self.solver, - "stepsize_controller": self.stepsize_controller, - "adjoint": self.adjoint, - "dt0": as_scalar_time_array(self.dt0, name="dt0"), - "max_steps": self.max_steps, - "throw": self.throw, - } - - -@dataclasses.dataclass -class SDESimulatorConfig: - """SDE Solver Settings for SDE Simulation. Supports diffrax-based solvers - or a faster, hand-rolled Euler-Maruyama scan backend. - - !! Note: The choice of solver can imply convergence to different paths - for the same model. For example, the default `diffrax.Heun()` converges - to the Stratonovich SDE, while `diffrax.Euler()` converges to the Itô SDE. - This likely doesn't matter for most models, but can cause issues with state-dependent diffusions. - - Attributes: - solver (diffrax.AbstractSolver): Diffrax SDE solver. Defaults to - `diffrax.Heun()`. This setting is used only when `source="diffrax"`. - stepsize_controller (diffrax.AbstractStepSizeController): Diffrax - step-size policy. Defaults to `diffrax.ConstantStepSize()` and is - used only when `source="diffrax"`. - adjoint (diffrax.AbstractAdjoint): Strategy used to differentiate - through the Diffrax solve. Defaults to - `diffrax.RecursiveCheckpointAdjoint()` and is used only when - `source="diffrax"`. - dt0 (float | int | jax.Array): Integration step size. It is passed to - Diffrax as the initial step size and used as the fixed - Euler-Maruyama step by the `"em_scan"` backend. Defaults to `1e-4`. - tol_vbt (float | int | jax.Array | None): Tolerance for Diffrax's - `VirtualBrownianTree`. When `source="diffrax"`, `None` resolves to - `dt0 / 2`; an explicit value must be smaller than `dt0` for - statistically correct simulation. Ignored by `"em_scan"`. - max_steps (int | None): Maximum number of Diffrax integration steps. - `None` leaves the Diffrax default in effect. The `"em_scan"` - backend does not use this setting. - source (Literal["diffrax", "em_scan"]): Simulation backend. - `"diffrax"` uses the configured Diffrax solver and a virtual - Brownian tree. `"em_scan"` uses a fixed-step Euler-Maruyama - `jax.lax.scan` and is the default for speed. - - Properties: - diffeqsolve_settings (dict[str, Any]): Normalized Diffrax keyword - arguments derived from the config; scalar time values are - converted to JAX arrays. - resolved_tol_vbt (jax.Array | None): Effective virtual-Brownian-tree - tolerance for the selected backend. Returns `None` for `"em_scan"` - and validates the tolerance for `"diffrax"`. - """ - - solver: dfx.AbstractSolver = dataclasses.field(default_factory=dfx.Heun) - stepsize_controller: dfx.AbstractStepSizeController = dataclasses.field( - default_factory=dfx.ConstantStepSize - ) - adjoint: dfx.AbstractAdjoint = dataclasses.field( - default_factory=dfx.RecursiveCheckpointAdjoint - ) - dt0: float | int | Real[Array, ""] = 1e-4 - tol_vbt: float | int | Real[Array, ""] | None = None - max_steps: int | None = None - source: Literal["diffrax", "em_scan"] = "em_scan" - - def __post_init__(self) -> None: - if self.source not in {"diffrax", "em_scan"}: - raise ValueError( - "SDESimulatorConfig.source must be one of {'diffrax', 'em_scan'}, " - f"got source={self.source!r}." - ) - - @property - def diffeqsolve_settings(self) -> dict[str, Any]: - """Return normalized Diffrax-style backend settings.""" - return { - "solver": self.solver, - "stepsize_controller": self.stepsize_controller, - "adjoint": self.adjoint, - "dt0": as_scalar_time_array(self.dt0, name="dt0"), - "max_steps": self.max_steps, - } - - @property - def resolved_tol_vbt(self) -> Real[Array, ""] | None: - """Return the resolved Brownian-tree tolerance for the active backend.""" - if self.source != "diffrax": - return None - - dt0_arr = as_scalar_time_array(self.dt0, name="dt0") - tol_vbt_arr = ( - dt0_arr / 2.0 - if self.tol_vbt is None - else as_scalar_time_array(self.tol_vbt, name="tol_vbt") - ) - tol_vbt_arr = _raise_now_or_error_if( - tol_vbt_arr, - tol_vbt_arr >= dt0_arr, - "tol_vbt must be smaller than dt0 for statistically correct simulation.", - ) - return tol_vbt_arr - - -type SimulatorConfig = ODESimulatorConfig | SDESimulatorConfig +warnings.warn( + "dynestyx.inference.configs.simulator is deprecated; use " + "dynestyx.configs.simulator instead.", + DeprecationWarning, + stacklevel=2, +) diff --git a/dynestyx/inference/configs/smoother.py b/dynestyx/inference/configs/smoother.py index e92cd5128..46d283d83 100644 --- a/dynestyx/inference/configs/smoother.py +++ b/dynestyx/inference/configs/smoother.py @@ -1,460 +1,14 @@ -"""Smoother configuration dataclasses. Shared by dispatchers and integration backends.""" +"""Deprecated compatibility module for :mod:`dynestyx.configs.smoother`.""" -import abc -import dataclasses -from typing import Literal +import warnings -from dynestyx.inference.configs.filter import ( - ContinuousTimeEKFConfig, - ContinuousTimeKFConfig, - EKFConfig, - EnKFConfig, - KFConfig, - PFConfig, - UKFConfig, -) - -PFBackwardSamplingMethod = Literal["tracing", "exact", "mcmc"] -CDKFSmootherType = Literal["cd_smoother_1", "cd_smoother_2"] - - -@dataclasses.dataclass(frozen=True) -class BaseSmootherConfig(abc.ABC): - r"""Shared base class for all smoother configs. - - You do not instantiate this class directly; use one of the concrete - subclasses (e.g. `KFSmootherConfig`, `PFSmootherConfig`). - - Concrete smoother configs inherit from their corresponding filter configs, - so backend selection, filter tuning, continuous-time solver options, and - filter recording fields follow the same conventions as - `dynestyx.inference.configs.filter`. - - Config fields are immutable after construction. Use `dataclasses.replace` - to create an updated config. - - The `record_smoothed_*` fields let you save intermediate smoothing outputs - into the NumPyro trace as `numpyro.deterministic` sites, making them - accessible after inference (e.g. for plotting smoothed trajectories). - `None` defers to the backend's default for that quantity. - - Attributes: - record_smoothed_states_mean (bool | None): Save the posterior smoothing - mean \(\mathbb{E}[x_t \mid y_{1:T}]\) at each time step. - record_smoothed_states_cov (bool | None): Save the full smoothing - covariance at each time step. Can be large; prefer - `record_smoothed_states_cov_diag` for high-dimensional states. - record_smoothed_states_cov_diag (bool | None): Save only the marginal - smoothing variances at each time step. - record_smoothed_particles (bool | None): Save smoothed particles for - particle smoothers. - record_smoothed_log_weights (bool | None): Save smoothed particle log - weights for particle smoothers. - record_smoothed_states_chol_cov (bool | None): Save the Cholesky factor - of the smoothing covariance when exposed by the backend. - record_max_elems (int): Hard cap on total scalar elements saved across - all `record_*` sites. Prevents accidentally filling device memory - for long sequences or large state spaces. Defaults to `100_000`. - """ - - record_smoothed_states_mean: bool | None = None - record_smoothed_states_cov: bool | None = None - record_smoothed_states_cov_diag: bool | None = None - record_smoothed_particles: bool | None = None - record_smoothed_log_weights: bool | None = None - record_smoothed_states_chol_cov: bool | None = None - record_max_elems: int = 100_000 - - def __post_init__(self): - if type(self) is BaseSmootherConfig: - raise TypeError( - "BaseSmootherConfig is abstract and cannot be instantiated." - ) - - -@dataclasses.dataclass(frozen=True) -class KFSmootherConfig(KFConfig, BaseSmootherConfig): - r"""Rauch-Tung-Striebel Kalman Smoother (RTS) for discrete-time models. - - The exact Bayesian smoother for discrete-time linear-Gaussian state-space - models. Use this when your model was built with `LTI_discrete` or with - `LinearGaussianStateEvolution` + `LinearGaussianObservation`. - - The smoother computes \(p(x_t \mid y_{1:T})\), while `KFConfig` computes - \(p(x_t \mid y_{1:t})\). Use the inherited `record_smoothed_*` fields to - save smoothed means, covariances, or covariance diagonals in the NumPyro - trace. - - Supports missing observations via NaNs when `filter_source="cuthbert"`. Does not support missing observations (data cannot have NaNs) when `filter_source="cd_dynamax"`. - - Time-varying linear-Gaussian models (callable `(t_now, t_next)` / `(t,)` - parameters on `LinearGaussianStateEvolution` / - `LinearGaussianObservation`) are supported only with - `filter_source="cuthbert"`; `filter_source="cd_dynamax"` raises - `TypeError` for callable parameters. - - Attributes: - filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. - associative (bool | None): Whether to enable cuthbert's associative - parallel-in-time scan. This is only supported when - `filter_source="cuthbert"`. Defaults to `None`, which selects - an associative scan if `filter_source="cuthbert"`, and a - sequential scan otherwise. - - ??? note "Algorithm Reference" - After a forward Kalman filtering pass, the RTS smoother runs a backward - recursion over the filtered and one-step-ahead predicted Gaussian - states. For a linear transition matrix \(A_t\), the smoothing gain is - - $$ - G_t = P_{t|t} A_t^\top P_{t+1|t}^{-1}. - $$ - - The smoothed mean and covariance are then - - $$ - m_{t|T} = m_{t|t} + G_t (m_{t+1|T} - m_{t+1|t}), - $$ - - and - - $$ - P_{t|T} = P_{t|t} - + G_t (P_{t+1|T} - P_{t+1|t}) G_t^\top. - $$ - - References: - - - For the original smoother, see: Rauch, H. E., Tung, F., & Striebel, C. T. (1965). - Maximum likelihood estimates of linear dynamic systems. AIAA Journal, 3(8), 1445-1450. - - For a modern textbook reference, see: Särkkä, S., & Svensson, L. (2023). - Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. - [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). - """ - - -@dataclasses.dataclass(frozen=True) -class EKFSmootherConfig(EKFConfig, BaseSmootherConfig): - r"""Extended Kalman Smoother (EKS) for discrete-time models. - - The Gaussian smoother corresponding to `EKFConfig`. Use this for - differentiable nonlinear dynamics when local linearization is a reasonable - approximation to the filtering and smoothing distributions. - - This is exact (but wasteful) for linear-Gaussian models. For those models, - prefer `KFSmootherConfig`. - - Does not support missing observations (data cannot have NaNs). - - Attributes: - filter_source (FilterSource): Backend. Defaults to `"cuthbert"`. - - ??? note "Algorithm Reference" - The EKS applies the RTS backward recursion to the linear-Gaussian - approximations produced by an EKF filtering pass. The transition matrix - in the smoothing gain is the Jacobian of the transition function at the - filtered mean: - - $$ - G_t = P_{t|t} F_t^\top P_{t+1|t}^{-1}. - $$ - - Smoothed means and covariances are then computed with the same - backward recursion as `KFSmootherConfig`. - - References: - - - For a classical textbook treatment, see: Jazwinski, A. H. (1970). - Stochastic Processes and Filtering Theory. Academic Press. - - For a modern textbook reference, see: Särkkä, S., & Svensson, L. (2023). - Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. - [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). - """ - - -@dataclasses.dataclass(frozen=True) -class EnRTSSmootherConfig(EnKFConfig, BaseSmootherConfig): - r"""Ensemble Rauch-Tung-Striebel smoother (EnRTS) for discrete-time models. - - The EnRTS runs an ensemble Kalman filter forward pass followed by an - RTS-like backward recursion over the filtered and forecast ensembles. Use - this for nonlinear models with Gaussian, state-independent observation - noise when an ensemble approximation is preferable to local - linearization. - - The inherited `n_particles`, `inflation_delta`, and - `perturb_measurements` fields configure the forward EnKF. The cuthbert - backend retains the forecast ensemble required by the backward pass. - The inherited `localization` field localizes that forward EnKF only; the - backward EnRTS gain remains the standard, unlocalized empirical gain. - - Supports missing observations via NaNs. - - Attributes: - n_particles (int): Number of ensemble members. Defaults to `30`. - crn_seed (PRNGKeyArray | None): Fixed PRNG key for the ensemble. - perturb_measurements (bool | None): Whether to use stochastic - perturbed-observation EnKF updates. - inflation_delta (float | None): Ensemble inflation applied during the - forward pass. - localization (EnKFLocalizationConfig | EnKFLocalizationFunctions | None): - Optional localization for the forward EnKF pass only. - filter_source (FilterSource): Backend. Always `"cuthbert"`. - - ??? note "Algorithm Reference" - The EnRTS smooths each ensemble member with an empirical RTS gain: - - $$ - x_{t \mid T}^{(i)} - = x_{t \mid t}^{(i)} - + J_t \left( - x_{t+1 \mid T}^{(i)} - - x_{t+1 \mid t}^{(i)} - \right). - $$ - - The gain \(J_t\) is estimated from the filtered ensemble at time \(t\) - and its forecast at time \(t+1\). - - References: - - - Raanes, P. N. (2016). On the ensemble Rauch-Tung-Striebel smoother and its equivalence to the ensemble Kalman smoother. Quarterly Journal of the Royal Meteorological Society, 142(696), 1259-1264. - """ - - -@dataclasses.dataclass(frozen=True) -class UKFSmootherConfig(UKFConfig, BaseSmootherConfig): - r"""Unscented Kalman Smoother (UKS) for discrete-time models. - - A derivative-free Gaussian smoother that handles nonlinearities by - propagating deterministic sigma points rather than Jacobians. Use this when - sigma-point propagation is a better local approximation than EKF - linearization. +from dynestyx.configs.smoother import * # noqa: F403 +from dynestyx.configs.smoother import SmootherConfig as SmootherConfig +from dynestyx.configs.smoother import __all__ as __all__ - This smoother is currently supported with `filter_source="cd_dynamax"` only. - Cuthbert UKF smoothing is not implemented. - - Does not support missing observations (data cannot have NaNs). - - Attributes: - alpha (float): Spread of sigma points around the current mean. - Smaller → tighter cluster; larger → sigma points reach further. - Defaults to \(\sqrt{3}\). - beta (int): Encodes prior knowledge about the distribution shape. - `2` is optimal for Gaussians. Defaults to `2`. - kappa (int): Secondary scaling parameter. Defaults to `1`. - filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. - - ??? note "Algorithm Reference" - The UKS uses a forward UKF pass followed by an RTS-style backward pass. - Instead of using a Jacobian in the smoothing gain, it estimates the - lag-one cross-covariance \(P_{t,t+1|t}\) by propagating sigma points: - - $$ - G_t = P_{t,t+1|t} P_{t+1|t}^{-1}. - $$ - - The smoothed mean and covariance then follow the same correction form - as the Kalman and extended Kalman smoothers. - - References: - - - For the original unscented Kalman filter paper, see: Julier, S. J., & Uhlmann, J. K. (1997). - New extension of the Kalman filter to nonlinear systems. SPIE Proceedings, 3068. - - For the unscented RTS smoother, see: Särkkä, S. (2008). - Unscented Rauch-Tung-Striebel smoother. IEEE Transactions on Automatic Control, 53(3), 845-849. - - For a modern textbook reference, see: Särkkä, S., & Svensson, L. (2023). - Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. - [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). - """ - - -@dataclasses.dataclass(frozen=True) -class PFSmootherConfig(PFConfig, BaseSmootherConfig): - r"""Particle smoother for discrete-time models. - - Use this for nonlinear or non-Gaussian discrete-time models. Particle - smoothing is more flexible than Gaussian smoothing, but accuracy scales - with the number of particles and backward-sampled smoother trajectories. - - This smoother is currently supported with `filter_source="cuthbert"` only. - - Does not support missing observations (data cannot have NaNs). - - Attributes: - n_particles (int): Number of particles in the forward particle filter. - More particles give a lower-variance log-likelihood and smoothing - approximation at linear compute cost. Defaults to `1_000`. - pf_backward_sampling_method (PFBackwardSamplingMethod): Backward - simulation method. `"tracing"` is the default, `"exact"` performs - exact backward sampling where available, and `"mcmc"` uses an MCMC - backward kernel. - pf_mcmc_n_steps (int): Number of MCMC steps used when - `pf_backward_sampling_method="mcmc"`. - pf_n_smoother_particles (int | None): Number of backward-sampled - smoother particles. `None` inherits `n_particles` from `PFConfig`. - filter_source (FilterSource): Backend. Defaults to `"cuthbert"`, which - is currently the only available implementation. - - ??? note "Algorithm Reference" - Particle smoothers augment a forward particle filter with a backward - pass that reconstructs trajectories from the particle approximation to - the filtering distributions. - - In backward simulation, a sampled state \(x_{t+1}^{(j)}\) chooses an - ancestor at time \(t\) with probabilities proportional to - - $$ - w_t^{(i)} p(x_{t+1}^{(j)} \mid x_t^{(i)}). - $$ - - The `"tracing"` method follows stored particle ancestors. The `"exact"` - and `"mcmc"` methods use backward kernels that can better approximate - the full smoothing distribution at higher compute cost. - - References: - - - For backward simulation particle smoothing, see: Godsill, S. J., Doucet, A., & West, M. (2004). - Monte Carlo smoothing for nonlinear time series. Journal of the American Statistical Association, 99(465), 156-168. - - For a general SMC/particle filtering reference, see: Doucet, A., De Freitas, N., & Gordon, N. (2001). - An Introduction to Sequential Monte Carlo Methods. In Sequential Monte Carlo Methods in Practice (pp. 3-14). - New York, NY: Springer New York. - - For a modern textbook reference, see: Särkkä, S., & Svensson, L. (2023). - Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. - [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). - """ - - pf_backward_sampling_method: PFBackwardSamplingMethod = "tracing" - pf_mcmc_n_steps: int = 10 - pf_n_smoother_particles: int | None = None - - -@dataclasses.dataclass(frozen=True) -class ContinuousTimeKFSmootherConfig(ContinuousTimeKFConfig, BaseSmootherConfig): - r"""Continuous-discrete Kalman Smoother (CD-KS). - - The exact Bayesian smoother for continuous-time linear-Gaussian models with - discrete observations. Use this when your model was built with - `LTI_continuous`. - - This smoother is currently implemented through the `cd_dynamax` backend. - Inherited differential-equation solver options control the continuous-time - filtering pass, and inherited `record_smoothed_*` fields control trace - recording. - - Does not support missing observations (data cannot have NaNs). - - Attributes: - cdlgssm_smoother_type (CDKFSmootherType): CD-Dynamax smoother variant. - `"cd_smoother_1"` is the default; `"cd_smoother_2"` exposes the - backend's alternate continuous-discrete RTS implementation. - filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. - - ??? note "Algorithm Reference" - Continuous-discrete Kalman smoothing runs a continuous-time Kalman - filtering pass between observations, applies discrete Kalman updates at - observation times, and then integrates the corresponding backward - smoothing equations through the filtered trajectory. - - The result is the continuous-discrete analogue of the RTS smoother: - each state is conditioned on all observations \(y_{1:T}\), not just the - observations available up to that time. - - References: - - - For continuous-discrete smoothing equations, see: Särkkä, S. (2006). - Recursive Bayesian Inference on Stochastic Differential Equations. - - For a modern textbook reference, see Chapter 10.6 of: - Särkkä, S., & Solin, A. (2019). Applied Stochastic Differential Equations. - Cambridge University Press. [Available Online](https://users.aalto.fi/~asolin/sde-book/sde-book.pdf). - - For general Gaussian smoothing background, see: Särkkä, S., & Svensson, L. (2023). - Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. - [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). - """ - - cdlgssm_smoother_type: CDKFSmootherType = "cd_smoother_1" - - -@dataclasses.dataclass(frozen=True) -class ContinuousTimeEKFSmootherConfig(ContinuousTimeEKFConfig, BaseSmootherConfig): - r"""Continuous-discrete Extended Kalman Smoother (CD-EKS). - - Gaussian smoother for mildly nonlinear continuous-time dynamics with - discrete observations. Requires differentiable dynamics; JAX autodiff is - used to construct the local linearizations. - - This smoother is currently implemented through the `cd_dynamax` backend. - See `ContinuousTimeEKFConfig` for linearisation and solver options. - - Does not support missing observations (data cannot have NaNs). - - Attributes: - filter_source (FilterSource): Backend. Defaults to `"cd_dynamax"`. - - ??? note "Algorithm Reference" - The CD-EKS combines a continuous-discrete EKF filtering pass with a - backward smoothing pass through the locally linear Gaussian - approximations. It is the continuous-discrete analogue of - `EKFSmootherConfig`. - - The inherited `filter_state_order` and `filter_emission_order` options - control the Taylor approximation used during the continuous-time - filtering and smoothing computation. - - References: - - - For continuous-discrete smoothing equations, see: Särkkä, S. (2006). - Recursive Bayesian Inference on Stochastic Differential Equations. - - For a modern textbook reference, see Chapter 10.9 of: - Särkkä, S., & Solin, A. (2019). Applied Stochastic Differential Equations. - Cambridge University Press. [Available Online](https://users.aalto.fi/~asolin/sde-book/sde-book.pdf). - - For general Gaussian smoothing background, see: Särkkä, S., & Svensson, L. (2023). - Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. - [Available Online](https://users.aalto.fi/~ssarkka/pub/bfs_book_2023_online.pdf). - """ - - -DiscreteTimeSmootherConfigs: tuple[type, ...] = ( - KFSmootherConfig, - EKFSmootherConfig, - EnRTSSmootherConfig, - UKFSmootherConfig, - PFSmootherConfig, -) - -ContinuousTimeSmootherConfigs: tuple[type, ...] = ( - ContinuousTimeKFSmootherConfig, - ContinuousTimeEKFSmootherConfig, +warnings.warn( + "dynestyx.inference.configs.smoother is deprecated; use " + "dynestyx.configs.smoother instead.", + DeprecationWarning, + stacklevel=2, ) - - -def _config_to_smoother_record_kwargs(config: BaseSmootherConfig) -> dict: - """Build smoother record kwargs dict from config.""" - return { - "record_smoothed_states_mean": config.record_smoothed_states_mean, - "record_smoothed_states_cov": config.record_smoothed_states_cov, - "record_smoothed_states_cov_diag": config.record_smoothed_states_cov_diag, - "record_smoothed_particles": config.record_smoothed_particles, - "record_smoothed_log_weights": config.record_smoothed_log_weights, - "record_smoothed_states_chol_cov": config.record_smoothed_states_chol_cov, - "record_max_elems": config.record_max_elems, - } - - -__all__ = [ - "BaseSmootherConfig", - "CDKFSmootherType", - "ContinuousTimeEKFSmootherConfig", - "ContinuousTimeKFSmootherConfig", - "ContinuousTimeSmootherConfigs", - "DiscreteTimeSmootherConfigs", - "EKFSmootherConfig", - "EnRTSSmootherConfig", - "KFSmootherConfig", - "PFBackwardSamplingMethod", - "PFSmootherConfig", - "UKFSmootherConfig", -] - - -SmootherConfig = BaseSmootherConfig diff --git a/dynestyx/inference/enkf_localization.py b/dynestyx/inference/enkf_localization.py index ea358ff49..e4d98b958 100644 --- a/dynestyx/inference/enkf_localization.py +++ b/dynestyx/inference/enkf_localization.py @@ -13,7 +13,7 @@ ) from jaxtyping import Array -from dynestyx.inference.configs.filter import ( +from dynestyx.configs.filter import ( ConstructCholInnovationCovariance, EnKFLocalizationConfig, EnKFLocalizationFunctions, diff --git a/dynestyx/inference/filters.py b/dynestyx/inference/filters.py index dfe50fe19..ce2f23b14 100644 --- a/dynestyx/inference/filters.py +++ b/dynestyx/inference/filters.py @@ -13,18 +13,7 @@ from effectful.ops.syntax import ObjectInterpretation, implements from jaxtyping import Array, Bool, PRNGKeyArray, Real -from dynestyx.handlers import ( - HandlesSelf, - _condition_intp, - _dynestyx_stack_kind, - _DynestyxStackKind, -) -from dynestyx.inference.checkers import ( - _validate_batched_plate_alignment, - _validate_inference_supported_model_classes, - _validate_missing_observation_support, -) -from dynestyx.inference.configs.filter import ( +from dynestyx.configs.filter import ( BaseFilterConfig, ConstructCholInnovationCovariance, ContinuousTimeConfigs, @@ -48,6 +37,17 @@ TaperCovarianceFn, UKFConfig, ) +from dynestyx.handlers import ( + HandlesSelf, + _condition_intp, + _dynestyx_stack_kind, + _DynestyxStackKind, +) +from dynestyx.inference.checkers import ( + _validate_batched_plate_alignment, + _validate_inference_supported_model_classes, + _validate_missing_observation_support, +) from dynestyx.inference.enkf_localization import ( ResolvedEnKFLocalization, resolve_enkf_localization, diff --git a/dynestyx/inference/hmm_filters.py b/dynestyx/inference/hmm_filters.py index b5f161dc4..6314fb817 100644 --- a/dynestyx/inference/hmm_filters.py +++ b/dynestyx/inference/hmm_filters.py @@ -9,7 +9,7 @@ from jax.scipy.special import logsumexp from jaxtyping import Array, Bool, Float, Int, Real, Shaped -from dynestyx.inference.configs.filter import HMMConfig +from dynestyx.configs.filter import HMMConfig from dynestyx.models import DynamicalModel from dynestyx.models.core import DiscreteStateTransition from dynestyx.observation_missingness import ( diff --git a/dynestyx/inference/integrations/blackjax/mcmc.py b/dynestyx/inference/integrations/blackjax/mcmc.py index 346da7a5c..2b4ced15b 100644 --- a/dynestyx/inference/integrations/blackjax/mcmc.py +++ b/dynestyx/inference/integrations/blackjax/mcmc.py @@ -11,7 +11,7 @@ from numpyro.infer import init_to_median from numpyro.infer.util import initialize_model, potential_energy -from dynestyx.inference.configs.mcmc import ( +from dynestyx.configs.mcmc import ( AdaptiveMetropolisConfig, AdaptiveMWGConfig, BaseMCMCConfig, diff --git a/dynestyx/inference/integrations/cd_dynamax/continuous_filter.py b/dynestyx/inference/integrations/cd_dynamax/continuous_filter.py index aa281a210..83309630e 100644 --- a/dynestyx/inference/integrations/cd_dynamax/continuous_filter.py +++ b/dynestyx/inference/integrations/cd_dynamax/continuous_filter.py @@ -18,7 +18,7 @@ ) from jaxtyping import Array, PRNGKeyArray, Real -from dynestyx.inference.configs.filter import ( +from dynestyx.configs.filter import ( ContinuousTimeDPFConfig, ContinuousTimeEKFConfig, ContinuousTimeEnKFConfig, diff --git a/dynestyx/inference/integrations/cd_dynamax/continuous_smoother.py b/dynestyx/inference/integrations/cd_dynamax/continuous_smoother.py index 96d5d6994..f16e6628e 100644 --- a/dynestyx/inference/integrations/cd_dynamax/continuous_smoother.py +++ b/dynestyx/inference/integrations/cd_dynamax/continuous_smoother.py @@ -14,7 +14,7 @@ ) from jaxtyping import Array, PRNGKeyArray, Real -from dynestyx.inference.configs.smoother import ( +from dynestyx.configs.smoother import ( ContinuousTimeEKFSmootherConfig, ContinuousTimeKFSmootherConfig, ) diff --git a/dynestyx/inference/integrations/cd_dynamax/discrete_filter.py b/dynestyx/inference/integrations/cd_dynamax/discrete_filter.py index 1ebce6793..9097adfc4 100644 --- a/dynestyx/inference/integrations/cd_dynamax/discrete_filter.py +++ b/dynestyx/inference/integrations/cd_dynamax/discrete_filter.py @@ -19,7 +19,7 @@ from jax.experimental import sparse as jax_sparse from jaxtyping import Array, Real -from dynestyx.inference.configs.filter import ( +from dynestyx.configs.filter import ( BaseFilterConfig, EKFConfig, KFConfig, diff --git a/dynestyx/inference/integrations/cd_dynamax/discrete_smoother.py b/dynestyx/inference/integrations/cd_dynamax/discrete_smoother.py index 848320915..3c44ff5a9 100644 --- a/dynestyx/inference/integrations/cd_dynamax/discrete_smoother.py +++ b/dynestyx/inference/integrations/cd_dynamax/discrete_smoother.py @@ -13,12 +13,12 @@ ) from jaxtyping import Array, Real -from dynestyx.inference.configs.filter import ( +from dynestyx.configs.filter import ( EKFConfig, KFConfig, UKFConfig, ) -from dynestyx.inference.configs.smoother import ( +from dynestyx.configs.smoother import ( BaseSmootherConfig, ) from dynestyx.inference.integrations.cd_dynamax.discrete_filter import ( diff --git a/dynestyx/inference/integrations/cuthbert/discrete_filter.py b/dynestyx/inference/integrations/cuthbert/discrete_filter.py index 137813d67..c11ffff79 100644 --- a/dynestyx/inference/integrations/cuthbert/discrete_filter.py +++ b/dynestyx/inference/integrations/cuthbert/discrete_filter.py @@ -19,7 +19,7 @@ from jax.experimental import sparse as jax_sparse from jaxtyping import Array, Bool, Float, PRNGKeyArray, Real -from dynestyx.inference.configs.filter import ( +from dynestyx.configs.filter import ( BaseFilterConfig, EKFConfig, EnKFConfig, diff --git a/dynestyx/inference/integrations/cuthbert/discrete_smoother.py b/dynestyx/inference/integrations/cuthbert/discrete_smoother.py index 5c44a5e24..3dd4148e3 100644 --- a/dynestyx/inference/integrations/cuthbert/discrete_smoother.py +++ b/dynestyx/inference/integrations/cuthbert/discrete_smoother.py @@ -14,7 +14,7 @@ from cuthbertlib.smc.smoothing import exact_sampling, mcmc, tracing from jaxtyping import Array, PRNGKeyArray, Real -from dynestyx.inference.configs.smoother import ( +from dynestyx.configs.smoother import ( EKFSmootherConfig, EnRTSSmootherConfig, KFSmootherConfig, diff --git a/dynestyx/inference/latent/builder.py b/dynestyx/inference/latent/builder.py index 0d52f6970..06966dcd0 100644 --- a/dynestyx/inference/latent/builder.py +++ b/dynestyx/inference/latent/builder.py @@ -15,6 +15,7 @@ from jax.core import Tracer from jaxtyping import Array, Bool, Int, PRNGKeyArray, Real +from dynestyx.configs.simulator import ODESimulatorConfig from dynestyx.handlers import ( HandlesSelf, _condition_intp, @@ -22,7 +23,6 @@ _DynestyxStackKind, ) from dynestyx.inference.checkers import _validate_inference_supported_model_classes -from dynestyx.inference.configs.simulator import ODESimulatorConfig from dynestyx.inference.posterior_rollout import ( _final_times_for_rollout, _validate_future_only_predict_times, diff --git a/dynestyx/inference/mcmc.py b/dynestyx/inference/mcmc.py index 436b76147..87bf55589 100644 --- a/dynestyx/inference/mcmc.py +++ b/dynestyx/inference/mcmc.py @@ -4,7 +4,7 @@ import jax.numpy as jnp from numpyro.infer import HMC, MCMC, NUTS -from dynestyx.inference.configs.mcmc import ( +from dynestyx.configs.mcmc import ( AdaptiveMetropolisConfig, AdaptiveMWGConfig, BaseMCMCConfig, diff --git a/dynestyx/inference/observation_predictions.py b/dynestyx/inference/observation_predictions.py index 91d3665a4..fc0b53e3b 100644 --- a/dynestyx/inference/observation_predictions.py +++ b/dynestyx/inference/observation_predictions.py @@ -15,7 +15,7 @@ import numpyro.distributions as dist from jaxtyping import Array, Float, Real -from dynestyx.inference.configs.filter import ( +from dynestyx.configs.filter import ( BaseFilterConfig, ContinuousTimeEKFConfig, ContinuousTimeEnKFConfig, diff --git a/dynestyx/inference/scoring_configs.py b/dynestyx/inference/scoring_configs.py index 495e77fe5..5f4ea09c8 100644 --- a/dynestyx/inference/scoring_configs.py +++ b/dynestyx/inference/scoring_configs.py @@ -1,5 +1,14 @@ -"""Backward-compatible import for evaluation configuration.""" +"""Deprecated compatibility module for :mod:`dynestyx.configs.scoring`.""" -from dynestyx.evaluation.configs import ObservationScoringConfig +import warnings + +from dynestyx.configs.scoring import ObservationScoringConfig __all__ = ["ObservationScoringConfig"] + +warnings.warn( + "dynestyx.inference.scoring_configs is deprecated; use " + "dynestyx.configs.scoring instead.", + DeprecationWarning, + stacklevel=2, +) diff --git a/dynestyx/inference/smoothers.py b/dynestyx/inference/smoothers.py index 057fc007b..be6168fd7 100644 --- a/dynestyx/inference/smoothers.py +++ b/dynestyx/inference/smoothers.py @@ -11,18 +11,7 @@ from effectful.ops.syntax import ObjectInterpretation, implements from jaxtyping import Array, PRNGKeyArray, Real -from dynestyx.handlers import ( - HandlesSelf, - _condition_intp, - _dynestyx_stack_kind, - _DynestyxStackKind, -) -from dynestyx.inference.checkers import ( - _validate_batched_plate_alignment, - _validate_inference_supported_model_classes, - _validate_missing_observation_support, -) -from dynestyx.inference.configs.smoother import ( +from dynestyx.configs.smoother import ( BaseSmootherConfig, ContinuousTimeEKFSmootherConfig, ContinuousTimeKFSmootherConfig, @@ -34,6 +23,17 @@ PFSmootherConfig, UKFSmootherConfig, ) +from dynestyx.handlers import ( + HandlesSelf, + _condition_intp, + _dynestyx_stack_kind, + _DynestyxStackKind, +) +from dynestyx.inference.checkers import ( + _validate_batched_plate_alignment, + _validate_inference_supported_model_classes, + _validate_missing_observation_support, +) from dynestyx.inference.integrations.cd_dynamax.continuous_smoother import ( compute_continuous_smoother, run_continuous_smoother, @@ -266,7 +266,7 @@ def _add_log_factors( ) raise ValueError( f"Invalid smoother config: {type(config).__name__}. " - "Expected a smoother config class from dynestyx.inference.configs.smoother. " + "Expected a smoother config class from dynestyx.configs.smoother. " f"Valid types: {valid}" ) if isinstance(config, EnRTSSmootherConfig) and ( diff --git a/dynestyx/inference/utils/numpyro_sites.py b/dynestyx/inference/utils/numpyro_sites.py index 10cee4df5..e069ba566 100644 --- a/dynestyx/inference/utils/numpyro_sites.py +++ b/dynestyx/inference/utils/numpyro_sites.py @@ -5,14 +5,14 @@ import numpyro from jaxtyping import Array, Float, Real -from dynestyx.inference.configs.filter import ( +from dynestyx.configs.filter import ( BaseFilterConfig, ContinuousTimeConfigs, HMMConfig, PFConfig, _config_to_record_kwargs, ) -from dynestyx.inference.configs.smoother import ( +from dynestyx.configs.smoother import ( BaseSmootherConfig, PFSmootherConfig, _config_to_smoother_record_kwargs, diff --git a/dynestyx/simulation/auto.py b/dynestyx/simulation/auto.py index b14c99b34..da32705dc 100644 --- a/dynestyx/simulation/auto.py +++ b/dynestyx/simulation/auto.py @@ -6,8 +6,8 @@ from jaxtyping import Array, PRNGKeyArray, PyTree, Real -from dynestyx.inference.configs.filter import BaseFilterConfig -from dynestyx.inference.configs.simulator import ( +from dynestyx.configs.filter import BaseFilterConfig +from dynestyx.configs.simulator import ( ODESimulatorConfig, SDESimulatorConfig, SimulatorConfig, @@ -54,9 +54,9 @@ class Simulator(BaseSimulator): seed supplies randomness; the rollout itself is computed with pure JAX and its realized arrays are then attached to the NumPyro trace. For continuous-time models, pass an - [ODESimulatorConfig][dynestyx.inference.configs.simulator.ODESimulatorConfig] + [ODESimulatorConfig][dynestyx.configs.simulator.ODESimulatorConfig] or - [SDESimulatorConfig][dynestyx.inference.configs.simulator.SDESimulatorConfig] + [SDESimulatorConfig][dynestyx.configs.simulator.SDESimulatorConfig] as `simulator_config` to control how the differential equation is solved. Use [dsx.simulate][dynestyx.api.simulate] instead when no NumPyro trace is needed and an explicit `rng_key` is more convenient. @@ -132,7 +132,7 @@ class Simulator(BaseSimulator): Configurations and defaults --------------------------- `simulator_config` accepts a - [SimulatorConfig][dynestyx.inference.configs.simulator.SimulatorConfig] and + [SimulatorConfig][dynestyx.configs.simulator.SimulatorConfig] and forwards it to the selected continuous-time backend: - stochastic continuous-time models accept `SDESimulatorConfig`; diff --git a/dynestyx/simulation/ode.py b/dynestyx/simulation/ode.py index e3f55bac9..ff2fca3bd 100644 --- a/dynestyx/simulation/ode.py +++ b/dynestyx/simulation/ode.py @@ -4,7 +4,7 @@ import jax.random as jr from jaxtyping import Array, PRNGKeyArray, Real -from dynestyx.inference.configs.simulator import ODESimulatorConfig +from dynestyx.configs.simulator import ODESimulatorConfig from dynestyx.models import DynamicalModel from dynestyx.simulation.base import BaseSimulator from dynestyx.simulation.utils import ( @@ -44,7 +44,7 @@ class ODESimulator(BaseSimulator): `dsx.sample(name, dynamics, predict_times=...)`. The active NumPyro seed supplies randomness, and the computed arrays are then attached to the trace as deterministic sites. Pass an - [ODESimulatorConfig][dynestyx.inference.configs.simulator.ODESimulatorConfig] + [ODESimulatorConfig][dynestyx.configs.simulator.ODESimulatorConfig] to choose the Diffrax solver, step-size controller, adjoint, step size, and step limit. Use [dsx.simulate][dynestyx.api.simulate] for standalone pure-JAX generation without a NumPyro trace. @@ -105,7 +105,7 @@ class ODESimulator(BaseSimulator): Configuration and defaults -------------------------- ODEs are solved using Diffrax, and settings are controlled by - [ODESimulatorConfig][dynestyx.inference.configs.simulator.ODESimulatorConfig]. + [ODESimulatorConfig][dynestyx.configs.simulator.ODESimulatorConfig]. Its default settings are `diffrax.Tsit5()`, `diffrax.ConstantStepSize()`, `diffrax.RecursiveCheckpointAdjoint()`, `dt0=1e-3`, and `max_steps=100_000`. Pass different settings when the model diff --git a/dynestyx/simulation/sde.py b/dynestyx/simulation/sde.py index ea1ebd431..b2a4181ed 100644 --- a/dynestyx/simulation/sde.py +++ b/dynestyx/simulation/sde.py @@ -4,7 +4,7 @@ import jax.random as jr from jaxtyping import Array, PRNGKeyArray, Real -from dynestyx.inference.configs.simulator import SDESimulatorConfig +from dynestyx.configs.simulator import SDESimulatorConfig from dynestyx.models import DynamicalModel, StochasticContinuousTimeStateEvolution from dynestyx.simulation.base import BaseSimulator from dynestyx.simulation.utils import ( @@ -46,7 +46,7 @@ class SDESimulator(BaseSimulator): `dsx.sample(name, dynamics, predict_times=...)`. The active NumPyro seed supplies randomness, and the realized paths are then attached to the trace as deterministic sites. Pass an - [SDESimulatorConfig][dynestyx.inference.configs.simulator.SDESimulatorConfig] + [SDESimulatorConfig][dynestyx.configs.simulator.SDESimulatorConfig] to choose the SDE backend, solver, step-size controller, adjoint, step size, and Brownian-tree tolerance. Use [dsx.simulate][dynestyx.api.simulate] for standalone pure-JAX generation @@ -108,7 +108,7 @@ class SDESimulator(BaseSimulator): Configurations and defaults --------------------------- - [SDESimulatorConfig][dynestyx.inference.configs.simulator.SDESimulatorConfig] + [SDESimulatorConfig][dynestyx.configs.simulator.SDESimulatorConfig] selects one of two backends: - `source="em_scan"` uses a fixed-step Euler--Maruyama `jax.lax.scan`. diff --git a/mkdocs.yml b/mkdocs.yml index f27072072..d0b78a67e 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