Skip to main content

CausalDynamics: A large-scale benchmark for structural discovery of dynamical causal models

NeurIPS 2025

arXiv Homepage Huggingface Dataset License Badge Tests

A comprehensive benchmark framework designed to rigorously evaluate state-of-the-art causal discovery algorithms for dynamical systems.

Key Features

Overview of CausalDynamics

1️⃣ Large-Scale Benchmark. Systematically evaluate state-of-the-art causal discovery algorithms on thousands of graph challenges with increasing difficulty.

2️⃣ Customizable Data Generation. Scalable, user-friendly generation of increasingly complex coupled ordinary and stochastic systems of differential equations

3️⃣ Diverse Challenges. From simple chaotic systems to modular causal coupling of dynamical systems, including optional noise, confounding, time lags, and even climate model dynamics.

Abstract: Causal discovery for dynamical systems poses a major challenge in fields where active interventions are infeasible. Most methods used to investigate these systems and their associated benchmarks are tailored to deterministic, low-dimensional and weakly nonlinear time-series data. To address these limitations, we present CausalDynamics, a large-scale benchmark and extensible data generation framework to advance the structural discovery of dynamical causal models. Our benchmark consists of true causal graphs derived from thousands of coupled ordinary and stochastic differential equations as well as two idealized climate models. We perform a comprehensive evaluation of state-of-the-art causal discovery algorithms for graph reconstruction on systems with noisy, confounded, and lagged dynamics. CausalDynamics consists of a plug-and-play, build-your-own coupling workflow that enables the construction of a hierarchy of physical systems. We anticipate that our framework will facilitate the development of robust causal discovery algorithms that are broadly applicable across domains while addressing their unique challenges.

Datasets

You can generate your own dataset (see getting started), but you can also download our preprocessed ones directly from HuggingFace:

wget https://huggingface.co/datasets/kausable/CausalDynamics/resolve/main/process_causaldynamics.py
python process_causaldynamics.py

Installation

Using pip

CausalDynamics is available on PyPi, so you can use pip to install causaldynamics, which currently requires Python version 3.10.

pip install causaldynamics

If you use conda, please use the following commands:

conda create --name venv python=3.10
conda activate venv
pip install causaldynamics

Using pdm

Clone the repository and install it using pdm:

git clone https://github.com/kausable/CausalDynamics.git
cd CausalDynamics
pdm install

You can test whether the installation succeded by creating some coupled causal model data:

$(pdm venv activate)
python src/causaldynamics/creator.py --config config.yaml

You find the output at output/<timestamp> as default location.

Getting Started

Benchmarking

Citation

If you find any of the code and dataset useful, feel free to acknowledge our work through:

@article{herdeanu2025causaldynamics,
  title={CausalDynamics: A large-scale benchmark for structural discovery of dynamical causal models},
  author={Herdeanu, Benjamin and Nathaniel, Juan and Roesch, Carla and Buch, Jatan and Ramien, Gregor and Haux, Johannes and Gentine, Pierre},
  journal={arXiv preprint arXiv:2505.16620},
  year={2025}
}

Metadata

Release files for causaldynamics 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for causaldynamics 1.0.0
File Interpreter ABI Platform Actions
causaldynamics-1.0.0-py3-none-any.whl Python 3 none any Details for causaldynamics-1.0.0-py3-none-any.whl

Release files / causaldynamics-1.0.0-py3-none-any.whl

Download URL causaldynamics-1.0.0-py3-none-any.whl
Size 101.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8f0d607267119e318f0baf4a1deb0bebf13c4769f441c88379f847e51384e56d
BLAKE2b-256 checksum
How to use checksums
098d0c983bdcdf3ecec13cf354b8b1658850de7b55164e81cb81154537a36a37
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.10.16

Security for causaldynamics 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page