{"id":19199832,"url":"https://github.com/rose-stl-lab/dyffusion","last_synced_at":"2026-02-27T07:04:34.089Z","repository":{"id":172077208,"uuid":"648802101","full_name":"Rose-STL-Lab/dyffusion","owner":"Rose-STL-Lab","description":"[NeurIPS 2023] A Dynamics-informed Diffusion Model for Spatiotemporal Forecasting","archived":false,"fork":false,"pushed_at":"2024-10-18T17:30:13.000Z","size":533,"stargazers_count":202,"open_issues_count":2,"forks_count":22,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-17T11:04:24.479Z","etag":null,"topics":["deep-learning","diffusion","diffusion-models","ensemble-forecasts","machine-learning","neurips","neurips-2023","probabilistic-forecasting","pytorch","pytorch-lightning","spatiotemporal-forecasting"],"latest_commit_sha":null,"homepage":"https://salvarc.github.io/blog/2023/dyffusion","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rose-STL-Lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-02T21:13:10.000Z","updated_at":"2025-05-15T08:34:23.000Z","dependencies_parsed_at":"2025-01-06T01:05:58.480Z","dependency_job_id":"f2d3e5f9-89ee-4478-94a6-c0a6e1c73fdf","html_url":"https://github.com/Rose-STL-Lab/dyffusion","commit_stats":null,"previous_names":["rose-stl-lab/dyffusion"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Rose-STL-Lab/dyffusion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rose-STL-Lab%2Fdyffusion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rose-STL-Lab%2Fdyffusion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rose-STL-Lab%2Fdyffusion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rose-STL-Lab%2Fdyffusion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rose-STL-Lab","download_url":"https://codeload.github.com/Rose-STL-Lab/dyffusion/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rose-STL-Lab%2Fdyffusion/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29887152,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T05:38:26.446Z","status":"ssl_error","status_checked_at":"2026-02-27T05:38:25.235Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","diffusion","diffusion-models","ensemble-forecasts","machine-learning","neurips","neurips-2023","probabilistic-forecasting","pytorch","pytorch-lightning","spatiotemporal-forecasting"],"created_at":"2024-11-09T12:29:08.236Z","updated_at":"2026-02-27T07:04:34.070Z","avatar_url":"https://github.com/Rose-STL-Lab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# DYffusion: A Dynamics-informed Diffusion Model for Spatiotemporal Forecasting (NeurIPS 2023)\n\n\u003ca href=\"https://pytorch.org/get-started/locally/\"\u003e\u003cimg alt=\"Python\" src=\"https://img.shields.io/badge/-Python 3.9+-blue?style=for-the-badge\u0026logo=python\u0026logoColor=white\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pytorch.org/get-started/locally/\"\u003e\u003cimg alt=\"PyTorch\" src=\"https://img.shields.io/badge/-PyTorch -ee4c2c?style=for-the-badge\u0026logo=pytorch\u0026logoColor=white\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pytorchlightning.ai/\"\u003e\u003cimg alt=\"Lightning\" src=\"https://img.shields.io/badge/-Lightning-792ee5?style=for-the-badge\u0026logo=pytorchlightning\u0026logoColor=white\"\u003e\u003c/a\u003e\n\u003ca href=\"https://hydra.cc/\"\u003e\u003cimg alt=\"Config: hydra\" src=\"https://img.shields.io/badge/config-hydra-89b8cd?style=for-the-badge\u0026labelColor=gray\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Rose-STL-Lab/dyffusion/blob/main/LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/huggingface/datasets.svg?color=blue\"\u003e\u003c/a\u003e\n\n\u003ch3\u003e ✨Official implementation of our \u003ca href=\"https://arxiv.org/abs/2306.01984\"\u003eDYffusion\u003c/a\u003e paper✨ \u003c/h3\u003e\n \n![DYffusion Diagram](https://media.giphy.com/media/v1.Y2lkPTc5MGI3NjExOXpvdHB5bGY1aWltbTdoYTdxNW03bmdxaG9tMDN6dGY1ZTZ2OWU5ZCZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/h7yQszDENzsSiIUOpJ/giphy.gif)\n\n*DYffusion forecasts a sequence of* $h$ *snapshots* $\\mathbf{x}_1, \\mathbf{x}_2, \\dots, \\mathbf{x}_h$\n*given the initial conditions* $\\mathbf{x}_0$ *similarly to how standard diffusion models are used to sample from a distribution.*\n\n\u003c!-- \u003cimg src=\"docs/img/DYffusion-diagram.png\"\u003e --\u003e\n\u003c/div\u003e\nIf you use this code, please consider citing our work. Copy the bibtex from the bottom of this Readme or cite as:\n\n\u003e [DYffusion: A Dynamics-informed Diffusion Model for Spatiotemporal Forecasting](https://arxiv.org/abs/2306.01984),\\\nSalva Rühling Cachay, Bo Zhao, Hailey Joren, and Rose Yu,\\\n*Advances in Neural Information Processing Systems (NeurIPS)*, 2023\n\n## | Environment Setup\n\nWe recommend installing ``dyffusion`` in a virtual environment from PyPi or Conda. \nFor more details about installing [PyTorch](https://pytorch.org/get-started/locally/), please refer to their official documentation.\nFor some compute setups you may want to install pytorch first for proper GPU support.\n\n    python3 -m pip install \".[train]\"\n\n## | Downloading Data\n\n**Navier-Stokes and spring mesh:**\nFollow the instructions given by the [original dataset paper](https://github.com/karlotness/nn-benchmark).\nOr, simply run our scripts to download the data. For Navier-Stokes: ``bash scripts/download_navier_stokes.sh``.\nFor spring mesh: ``bash scripts/download_spring_mesh.sh``.\n\nBy default, the data are downloaded to ``$HOME/data/physical-nn-benchmark``, \nyou can override this by setting the ``DATA_DIR`` in the [scripts/download_physical_systems_data.sh](scripts/download_physical_systems_data.sh) script.\n\n**Sea surface temperatures:**\nPre-processed SST data can be downloaded from Zenodo: https://zenodo.org/record/7259555\n\n**IMPORTANT:** By default, our code expects the data to be in the ``$HOME/data/physical-nn-benchmark`` and ``$HOME/data/oisstv2`` directories.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003e Using a different data directory \u003c/b\u003e\u003c/summary\u003e\n\nIf you want to use a different directory, you need to change the \n`datamodule.data_dir` command line argument (e.g. `python run.py datamodule.data_dir=/path/to/data`), or \npermanently edit the ``data_dir`` variable in the [src/configs/datamodule/_base_data_config.yaml](src/configs/datamodule/_base_data_config.yaml) file.\n\u003c/details\u003e\n\n## | Running experiments\n\nPlease see the [src/README.md](src/README.md) file for detailed instructions on how to run experiments, navigate the code and running with different configurations.\n\n### Train DYffusion\n\n**First stage:** Train the *interpolator* network. E.g. with \n\n```\npython run.py experiment=spring_mesh_interpolation\n```\n\n**Second stage:** Train the *forecaster* network. E.g. with \n\n```\npython run.py experiment=spring_mesh_dyffusion diffusion.interpolator_run_id=\u003cWANDB_RUN_ID\u003e\n```\nNote that we currently rely on Weights \u0026 Biases for logging and checkpointing, \nso please note the wandb run id of the interpolator training run, so that you can use it to train the forecaster network as above.\nYou can find the run's ID, for example, in the URL of the run's page on wandb.ai.\nE.g. in ``https://wandb.ai/\u003centity\u003e/\u003cproject\u003e/runs/i73blbh0`` the run ID is ``i73blbh0``.\n\n#### Training DYffusion on your own data\nWe advise to create your own datamodule by following the example ones in [datamodules/](src/datamodules) and creating a\ncorresponding yaml config file in [configs/datamodule/](src/configs/datamodule).\n\u003cbr\u003e\n*First stage:* It is worth spending some time/compute in optimizing the interpolator network (in terms of CRPS) before training the forecaster network.\nTo do so, it is important to sweep over the dropout rate(s). \nBut any other hyperparameter like the learning rate that leads to better CRPS will likely transfer to the overall performance of DYffusion as well.\n\u003cbr\u003e\n*Second stage:*\nThe full set of possible configuration for training DYffusion/the forecaster net is defined and briefly explained in [src/configs/diffusion/dyffusion.yaml](src/configs/diffusion/dyffusion.yaml).\nIt can be useful to try out different values for ``forward_conditioning``, \ncheck whether setting ``additional_interpolation_steps\u003e0`` (i.e. ``k\u003e0``) helps to improve the performance,\nand enable ``refine_intermediate_predictions=True`` (you may do so after finishing training).\n\n### Wandb integration\n\nWe use [Weights \u0026 Biases](https://wandb.ai/) for logging and checkpointing.\nPlease set your wandb username/entity in the [src/configs/logger/wandb.yaml](src/configs/logger/wandb.yaml) file.\nAlternatively, you can set the `logger.wandb.entity` command line argument (e.g. `python run.py logger.wandb.entity=my_username`).\n\n### Reproducing results\nYou can use any of the yaml configs in the [src/configs/experiment](src/configs/experiment) directory to (re-)run experiments.\nEach experiment file name defines a particular dataset and method/model combination following the pattern ``\u003cdataset\u003e_\u003cmethod\u003e.yaml``.\nFor example, you can train the ``Dropout`` baseline on the spring mesh dataset with:\n\n    python run.py experiment=spring_mesh_time_conditioned\n\nPlease note that to train DYffusion you need to start with the interpolation stage first, before running the ``\u003cdataset\u003e_dyffusion`` experiment,\nas described above.\n\n#### Testing a trained model\nTo test a trained model you, take note of its wandb run ID and then run:\n\n    python run.py mode=test logger.wandb.id=\u003crun_id\u003e\n\nAlternatively, reload the model from a local checkpoint file with:\n\n    python run.py mode=test logger.wandb.id=\u003crun_id\u003e ckpt_path=\u003cpath/to/local/checkpoint.ckpt\u003e\n\nIt is important to set the `mode=test` flag, so that the model is tested appropriately (e.g. predict 50 samples per initial condition).\nIf you're using multiple wandb projects, you may also need to set the `logger.wandb.project` flag.\n\n### Debugging\nBy default, we use all training trajectories for training our models.\nTo debug the physical systems experiments, feel free to use fewer training trajectories by setting:\n``python run.py datamodule.num_trajectories=1``. To accelerate training for the SST experiments, you may run with fewer\nregional boxes (the default is 11 boxes) with ``python run.py 'datamodule.boxes=[88]'``.\nGenerally, you can also try mixed precision training with ``python run.py trainer.precision=16``.\n\n## | Citation\n\n    @inproceedings{cachay2023dyffusion,\n      title={{DYffusion:} A Dynamics-informed Diffusion Model for Spatiotemporal Forecasting},\n      author={R{\\\"u}hling Cachay, Salva and Zhao, Bo and Joren, Hailey and Yu, Rose},\n      booktitle={Advances in Neural Information Processing Systems (NeurIPS)}, \n      url={https://openreview.net/forum?id=WRGldGm5Hz},\n      year={2023}\n    }","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frose-stl-lab%2Fdyffusion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frose-stl-lab%2Fdyffusion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frose-stl-lab%2Fdyffusion/lists"}