{"id":13476839,"url":"https://github.com/saforem2/l2hmc-qcd","last_synced_at":"2025-08-21T23:32:30.322Z","repository":{"id":38706254,"uuid":"176870361","full_name":"saforem2/l2hmc-qcd","owner":"saforem2","description":"Application of the L2HMC algorithm to simulations in lattice QCD.","archived":false,"fork":false,"pushed_at":"2024-02-02T21:33:22.000Z","size":916150,"stargazers_count":67,"open_issues_count":0,"forks_count":9,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-12-15T03:49:47.133Z","etag":null,"topics":["deep-learning","deepspeed","gauge-theory","hamiltonian-monte-carlo","hmc","horovod","hydra","lattice","lattice-qcd","machine-learning","mcmc","monte-carlo","pytorch","tensorflow"],"latest_commit_sha":null,"homepage":"https://saforem2.github.io/l2hmc-qcd/","language":"Jupyter Notebook","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/saforem2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-21T04:32:54.000Z","updated_at":"2024-12-14T09:14:41.000Z","dependencies_parsed_at":"2023-02-14T18:16:09.341Z","dependency_job_id":"dacba503-e3e2-454f-9406-f10d3c651eef","html_url":"https://github.com/saforem2/l2hmc-qcd","commit_stats":{"total_commits":6139,"total_committers":6,"mean_commits":"1023.1666666666666","dds":0.003257859586251799,"last_synced_commit":"1b951ef75d9876e818ee2e38d443ece1af94350d"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saforem2%2Fl2hmc-qcd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saforem2%2Fl2hmc-qcd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saforem2%2Fl2hmc-qcd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saforem2%2Fl2hmc-qcd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saforem2","download_url":"https://codeload.github.com/saforem2/l2hmc-qcd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230542287,"owners_count":18242332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","deepspeed","gauge-theory","hamiltonian-monte-carlo","hmc","horovod","hydra","lattice","lattice-qcd","machine-learning","mcmc","monte-carlo","pytorch","tensorflow"],"created_at":"2024-07-31T16:01:35.179Z","updated_at":"2024-12-20T06:05:52.006Z","avatar_url":"https://github.com/saforem2.png","language":"Jupyter Notebook","funding_links":[],"categories":["Jupyter Notebook"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n![l2hmc-qcd](./assets/logo-small.svg)\n\n\u003ca href=\"https://hits.seeyoufarm.com\"\u003e\u003cimg alt=\"hits\" src=\"https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2Fsaforem2%2Fl2hmc-qcd\u0026count_bg=%2300CCFF\u0026title_bg=%23555555\u0026icon=\u0026icon_color=%23111111\u0026title=👋\u0026edge_flat=false\"\u003e\u003c/a\u003e    \n\u003ca href=\"https://github.com/saforem2/l2hmc-qcd/\"\u003e\u003cimg alt=\"l2hmc-qcd\" src=\"https://img.shields.io/badge/-l2hmc--qcd-252525?style=flat\u0026logo=github\u0026labelColor=gray\"\u003e\u003c/a\u003e \u003ca href=\"https://www.codefactor.io/repository/github/saforem2/l2hmc-qcd\"\u003e\u003cimg alt=\"codefactor\" src=\"https://www.codefactor.io/repository/github/saforem2/l2hmc-qcd/badge\"\u003e\u003c/a\u003e\n\u003cbr\u003e\n\u003ca href=\"https://arxiv.org/abs/2112.01582\"\u003e\u003cimg alt=\"arxiv\" src=\"http://img.shields.io/badge/arXiv-2112.01582-B31B1B.svg\"\u003e\u003c/a\u003e \u003ca href=\"https://arxiv.org/abs/2105.03418\"\u003e\u003cimg alt=\"arxiv\" src=\"http://img.shields.io/badge/arXiv-2105.03418-B31B1B.svg\"\u003e\u003c/a\u003e \n\u003cbr\u003e\n\u003ca href=\"https://hydra.cc\"\u003e\u003cimg alt=\"hydra\" src=\"https://img.shields.io/badge/Config-Hydra-89b8cd\"\u003e\u003c/a\u003e \u003ca href=\"https://pytorch.org/get-started/locally/\"\u003e\u003cimg alt=\"pyTorch\" src=\"https://img.shields.io/badge/PyTorch-ee4c2c?logo=pytorch\u0026logoColor=white\"\u003e\u003c/a\u003e \u003ca href=\"https://www.tensorflow.org\"\u003e\u003cimg alt=\"tensorflow\" src=\"https://img.shields.io/badge/TensorFlow-%23FF6F00.svg?\u0026logo=TensorFlow\u0026logoColor=white\"\u003e\u003c/a\u003e \n\u003cbr\u003e\n[\u003cimg src=\"https://raw.githubusercontent.com/wandb/assets/main/wandb-github-badge-28.svg\" alt=\"Weights \u0026 Biases monitoring\" height=20\u003e](https://wandb.ai/l2hmc-qcd/l2hmc-qcd)\n\n\u003c/div\u003e\n\n\u003cdetails open\u003e\u003csummary\u003e\u003cb\u003eContents\u003c/b\u003e\u003c/summary\u003e\n\n- [Overview](#overview)\n  * [Papers 📚, Slides 📊, etc.](https://github.com/saforem2/l2hmc-qcd/#training--experimenting)\n  * [Background](#background)\n- [Installation](#installation)\n- [Training](#training)\n  - [Configuration Management](#configuration-management)\n  - [Running @ ALCF](#running-at-ALCF) \n- [Details](#details)\n  * [Organization](#organization)\n    + [Dynamics / Network](#dynamics---network)\n      - [Network Architecture](#network-architecture)\n    + [Lattice](#lattice)\n\n\u003c/details\u003e\n\n# Overview\n\n## Papers 📚, Slides 📊 etc.\n- [📊 Slides (07/31/2023 @ Lattice 2023)](https://saforem2.github.io/lattice23/#/title-slide)\n- [📕 Notebooks / Reports](./reports/):\n  - [📙 2D U(1) Model (w/ `fp16` or `fp32` for training)](./reports/l2hmc-2DU1.md)\n  - [📒 4D SU(3) Model (w/ `complex128` + `fp64` for training)](./src/l2hmc/notebooks/l2hmc-2dU1.ipynb)\n    - [alt link (if github won't load)](https://nbviewer.org/github/saforem2/l2hmc-qcd/blob/dev/src/l2hmc/notebooks/pytorch-SU3d4.ipynb)\n\n- 📝 Papers:\n    - [LeapfrogLayers: A Trainable Framework for Effective Topological Sampling](https://arxiv.org/abs/2112.01582), 2022  \n    - [Accelerated Sampling Techniques for Lattice Gauge Theory](https://saforem2.github.io/l2hmc-dwq25/#/) @ [BNL \u0026 RBRC: DWQ @ 25](https://indico.bnl.gov/event/13576/) (12/2021)\n    - [Training Topological Samplers for Lattice Gauge Theory](https://bit.ly/l2hmc-ect2021) from the [*ML for HEP, on and off the Lattice*](https://indico.ectstar.eu/event/77/) @ $\\mathrm{ECT}^{*}$ Trento (09/2021) (+ 📊 [slides](https://www.bit.ly/l2hmc-ect2021))\n    - [Deep Learning Hamiltonian Monte Carlo](https://arxiv.org/abs/2105.03418) @ [Deep Learning for Simulation (SimDL) Workshop](https://simdl.github.io/overview/) **ICLR 2021**\n        - 📚 : [arXiv:2105.03418](https://arxiv.org/abs/2105.03418)  \n        - 📊 : [poster](https://www.bit.ly/l2hmc_poster)\n\n\n## Background\nThe L2HMC algorithm aims to improve upon\n[HMC](https://en.wikipedia.org/wiki/Hamiltonian_Monte_Carlo) by optimizing a\ncarefully chosen loss function which is designed to minimize autocorrelations\nwithin the Markov Chain, thereby improving the efficiency of the sampler.\n\nA detailed description of the original L2HMC algorithm can be found in the paper:\n\n[*Generalizing Hamiltonian Monte Carlo with Neural Network*](https://arxiv.org/abs/1711.09268)\n\nwith implementation available at\n[brain-research/l2hmc/](https://github.com/brain-research/l2hmc) by [Daniel\nLevy](http://ai.stanford.edu/~danilevy), [Matt D.\nHoffman](http://matthewdhoffman.com/) and [Jascha\nSohl-Dickstein](sohldickstein.com).\n\nBroadly, given an *analytically* described target distribution, π(x), L2HMC provides a *statistically exact* sampler that:\n\n- Quickly converges to the target distribution (fast ***burn-in***).\n- Quickly produces uncorrelated samples (fast ***mixing***).\n- Is able to efficiently mix between energy levels.\n- Is capable of traversing low-density zones to mix between modes (often difficult for generic HMC).\n\n# Installation\n\n\u003e **Warning**\u003cbr\u003e\n\u003e It is recommended to install _inside_ an existing virtual environment\u003cbr\u003e\n\u003e (ideally one with `tensorflow, pytorch [horovod,deepspeed]` already installed)\n\n\u003cdetails open\u003e\u003csummary\u003e\u003cb\u003eFrom source (RECOMMENDED)\u003c/b\u003e\u003c/summary\u003e\n\n```Shell\ngit clone https://github.com/saforem2/l2hmc-qcd\ncd l2hmc-qcd\n# for development addons:\n# python3 -m pip install -e \".[dev]\"\npython3 -m pip install -e .\n```\n\n\u003cdetails closed\u003e\n\u003csummary\u003e\n\u003cb\u003e\nFrom \u003ca href=\"https://pypi.org/project/l2hmc/\"\u003e\n\u003ccode\u003el2hmc\u003c/code\u003e on PyPI\u003c/a\u003e\n\u003c/b\u003e\n\u003c/summary\u003e\n\u003cp\u003e\n\n```Shell\npython3 -m pip install l2hmc\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\nTest install:\n\n```Shell\npython3 -c 'import l2hmc ; print(l2hmc.__file__)'\n/path/to/l2hmc-qcd/src/l2hmc/__init__.py\n```\n\n# Training\n\n## Configuration Management\n\nThis project uses [`hydra`](https://hydra.cc) for configuration management and\nsupports distributed training for both PyTorch and TensorFlow.\n\nIn particular, we support the following combinations of `framework` + `backend` for distributed training:\n\n- TensorFlow (+ Horovod for distributed training)\n- PyTorch +\n    - DDP\n    - Horovod\n    - DeepSpeed\n\nThe main entry point is [`src/l2hmc/main.py`](./src/l2hmc/main.py),\nwhich contains  the logic for running an end-to-end `Experiment`.\n\nAn [`Experiment`](./src/l2hmc/experiment/) consists of the following sub-tasks:\n\n1. Training\n2. Evaluation\n3. HMC (for comparison and to measure model improvement)\n\n**All** configuration options can be dynamically overridden via the CLI at runtime, \nand we can specify our desired `framework` and `backend` combination via:\n\n```Shell\npython3 main.py mode=debug framework=pytorch backend=deepspeed precision=fp16\n```\n\nto run a (non-distributed) Experiment with `pytorch + deepspeed` with `fp16` precision.\n\nThe [`l2hmc/conf/config.yaml`](./src/l2hmc/conf/config.yaml) contains a brief\nexplanation of each of the various parameter options, and values can be\noverriden either by modifying the `config.yaml` file, or directly through the\ncommand line, e.g.\n\n```Shell\ncd src/l2hmc\n./train.sh mode=debug framework=pytorch \u003e train.log 2\u003e\u00261 \u0026\ntail -f train.log $(tail -1 logs/latest)\n```\n\nAdditional information about various configuration options can be found in:\n\n- [`src/l2hmc/configs.py`](./src/l2hmc/configs.py):\n  Contains implementations of the (concrete python objects) that are adjustable for our experiment.\n- [`src/l2hmc/conf/config.yaml`](./src/l2hmc/conf/config.yaml):\n  Starting point with default configuration options for a generic `Experiment`.\n\n\nfor more information on how this works I encourage you to read [Hydra's\nDocumentation Page](https://hydra.cc).\n\n\n## Running at ALCF\n\nFor running with distributed training on ALCF systems, we provide a complete\n[`src/l2hmc/train.sh`](./src/l2hmc/train.sh) \nscript which should run without issues on either Polaris or ThetaGPU @ ALCF.\n\n\n# Details\n\n**Goal:** Use L2HMC to **efficiently** generate _gauge configurations_ for\ncalculating observables in lattice QCD.\n\nA detailed description of the (ongoing) work to apply this algorithm to\nsimulations in lattice QCD (specifically, a 2D U(1) lattice gauge theory model)\ncan be found in [arXiv:2105.03418](https://arxiv.org/abs/2105.03418).\n\n\u003cdiv align=\"center\"\u003e\n \u003cimg src=\"assets/l2hmc_poster.jpeg\" alt=\"l2hmc-qcd poster\" width=\"90%\" /\u003e\n\u003c/div\u003e\n\n## Organization\n\n### Dynamics / Network\n\nFor a given target distribution, π(x), the `Dynamics` object\n([`src/l2hmc/dynamics/`](src/l2hmc/dynamics)) implements methods for generating\nproposal configurations (x' ~ π) using the generalized leapfrog update.\n\n\nThis generalized leapfrog update takes as input a buffer of lattice\nconfigurations `x` and generates a proposal configuration `x' = Dynamics(x)` by\nevolving generalized L2HMC dynamics.\n\n\n#### Network Architecture\n\nAn illustration of the `leapfrog layer` updating `(x, v) --\u003e (x', v')` can be seen below.\n\n\u003cdiv align=\"center\"\u003e\n \u003cimg src=\"assets/lflayer.png\" alt=\"leapfrog layer\" width=800/\u003e\n\u003c/div\u003e\n\n\n## Contact\n\n***Code author:*** Sam Foreman\n\n***Pull requests and issues should be directed to:*** [saforem2](http://github.com/saforem2)\n\n## Citation\n\nIf you use this code or found this work interesting, please cite our work along with the original paper:\n\n```bibtex\n@misc{foreman2021deep,\n      title={Deep Learning Hamiltonian Monte Carlo}, \n      author={Sam Foreman and Xiao-Yong Jin and James C. Osborn},\n      year={2021},\n      eprint={2105.03418},\n      archivePrefix={arXiv},\n      primaryClass={hep-lat}\n}\n```\n\n```bibtex\n@article{levy2017generalizing,\n  title={Generalizing Hamiltonian Monte Carlo with Neural Networks},\n  author={Levy, Daniel and Hoffman, Matthew D. and Sohl-Dickstein, Jascha},\n  journal={arXiv preprint arXiv:1711.09268},\n  year={2017}\n}\n```\n\n## Acknowledgement\n\n\n\u003e **Note**\u003cbr\u003e\n\u003e This research used resources of the Argonne Leadership Computing Facility, which is a DOE Office of Science User Facility supported under contract DE_AC02-06CH11357.\u003cbr\u003e\n\u003e This work describes objective technical results and analysis.\u003cbr\u003e\n\u003e Any subjective views or opinions that might be expressed in the work do not necessarily represent the views of the U.S. DOE or the United States Government.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaforem2%2Fl2hmc-qcd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaforem2%2Fl2hmc-qcd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaforem2%2Fl2hmc-qcd/lists"}