https://github.com/saforem2/l2hmc-qcd
Application of the L2HMC algorithm to simulations in lattice QCD.
https://github.com/saforem2/l2hmc-qcd
deep-learning deepspeed gauge-theory hamiltonian-monte-carlo hmc horovod hydra lattice lattice-qcd machine-learning mcmc monte-carlo pytorch tensorflow
Last synced: 7 months ago
JSON representation
Application of the L2HMC algorithm to simulations in lattice QCD.
- Host: GitHub
- URL: https://github.com/saforem2/l2hmc-qcd
- Owner: saforem2
- License: apache-2.0
- Created: 2019-03-21T04:32:54.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2024-02-02T21:33:22.000Z (about 2 years ago)
- Last Synced: 2024-12-15T03:49:47.133Z (over 1 year ago)
- Topics: deep-learning, deepspeed, gauge-theory, hamiltonian-monte-carlo, hmc, horovod, hydra, lattice, lattice-qcd, machine-learning, mcmc, monte-carlo, pytorch, tensorflow
- Language: Jupyter Notebook
- Homepage: https://saforem2.github.io/l2hmc-qcd/
- Size: 874 MB
- Stars: 67
- Watchers: 5
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
- my-awesome-starred - saforem2/l2hmc-qcd - Application of the L2HMC algorithm to simulations in lattice QCD. (Jupyter Notebook)
README
[
](https://wandb.ai/l2hmc-qcd/l2hmc-qcd)
Contents
- [Overview](#overview)
* [Papers 📚, Slides 📊, etc.](https://github.com/saforem2/l2hmc-qcd/#training--experimenting)
* [Background](#background)
- [Installation](#installation)
- [Training](#training)
- [Configuration Management](#configuration-management)
- [Running @ ALCF](#running-at-ALCF)
- [Details](#details)
* [Organization](#organization)
+ [Dynamics / Network](#dynamics---network)
- [Network Architecture](#network-architecture)
+ [Lattice](#lattice)
# Overview
## Papers 📚, Slides 📊 etc.
- [📊 Slides (07/31/2023 @ Lattice 2023)](https://saforem2.github.io/lattice23/#/title-slide)
- [📕 Notebooks / Reports](./reports/):
- [📙 2D U(1) Model (w/ `fp16` or `fp32` for training)](./reports/l2hmc-2DU1.md)
- [📒 4D SU(3) Model (w/ `complex128` + `fp64` for training)](./src/l2hmc/notebooks/l2hmc-2dU1.ipynb)
- [alt link (if github won't load)](https://nbviewer.org/github/saforem2/l2hmc-qcd/blob/dev/src/l2hmc/notebooks/pytorch-SU3d4.ipynb)
- 📝 Papers:
- [LeapfrogLayers: A Trainable Framework for Effective Topological Sampling](https://arxiv.org/abs/2112.01582), 2022
- [Accelerated Sampling Techniques for Lattice Gauge Theory](https://saforem2.github.io/l2hmc-dwq25/#/) @ [BNL & RBRC: DWQ @ 25](https://indico.bnl.gov/event/13576/) (12/2021)
- [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))
- [Deep Learning Hamiltonian Monte Carlo](https://arxiv.org/abs/2105.03418) @ [Deep Learning for Simulation (SimDL) Workshop](https://simdl.github.io/overview/) **ICLR 2021**
- 📚 : [arXiv:2105.03418](https://arxiv.org/abs/2105.03418)
- 📊 : [poster](https://www.bit.ly/l2hmc_poster)
## Background
The L2HMC algorithm aims to improve upon
[HMC](https://en.wikipedia.org/wiki/Hamiltonian_Monte_Carlo) by optimizing a
carefully chosen loss function which is designed to minimize autocorrelations
within the Markov Chain, thereby improving the efficiency of the sampler.
A detailed description of the original L2HMC algorithm can be found in the paper:
[*Generalizing Hamiltonian Monte Carlo with Neural Network*](https://arxiv.org/abs/1711.09268)
with implementation available at
[brain-research/l2hmc/](https://github.com/brain-research/l2hmc) by [Daniel
Levy](http://ai.stanford.edu/~danilevy), [Matt D.
Hoffman](http://matthewdhoffman.com/) and [Jascha
Sohl-Dickstein](sohldickstein.com).
Broadly, given an *analytically* described target distribution, π(x), L2HMC provides a *statistically exact* sampler that:
- Quickly converges to the target distribution (fast ***burn-in***).
- Quickly produces uncorrelated samples (fast ***mixing***).
- Is able to efficiently mix between energy levels.
- Is capable of traversing low-density zones to mix between modes (often difficult for generic HMC).
# Installation
> **Warning**
> It is recommended to install _inside_ an existing virtual environment
> (ideally one with `tensorflow, pytorch [horovod,deepspeed]` already installed)
From source (RECOMMENDED)
```Shell
git clone https://github.com/saforem2/l2hmc-qcd
cd l2hmc-qcd
# for development addons:
# python3 -m pip install -e ".[dev]"
python3 -m pip install -e .
```
From
l2hmc on PyPI
```Shell
python3 -m pip install l2hmc
```
Test install:
```Shell
python3 -c 'import l2hmc ; print(l2hmc.__file__)'
/path/to/l2hmc-qcd/src/l2hmc/__init__.py
```
# Training
## Configuration Management
This project uses [`hydra`](https://hydra.cc) for configuration management and
supports distributed training for both PyTorch and TensorFlow.
In particular, we support the following combinations of `framework` + `backend` for distributed training:
- TensorFlow (+ Horovod for distributed training)
- PyTorch +
- DDP
- Horovod
- DeepSpeed
The main entry point is [`src/l2hmc/main.py`](./src/l2hmc/main.py),
which contains the logic for running an end-to-end `Experiment`.
An [`Experiment`](./src/l2hmc/experiment/) consists of the following sub-tasks:
1. Training
2. Evaluation
3. HMC (for comparison and to measure model improvement)
**All** configuration options can be dynamically overridden via the CLI at runtime,
and we can specify our desired `framework` and `backend` combination via:
```Shell
python3 main.py mode=debug framework=pytorch backend=deepspeed precision=fp16
```
to run a (non-distributed) Experiment with `pytorch + deepspeed` with `fp16` precision.
The [`l2hmc/conf/config.yaml`](./src/l2hmc/conf/config.yaml) contains a brief
explanation of each of the various parameter options, and values can be
overriden either by modifying the `config.yaml` file, or directly through the
command line, e.g.
```Shell
cd src/l2hmc
./train.sh mode=debug framework=pytorch > train.log 2>&1 &
tail -f train.log $(tail -1 logs/latest)
```
Additional information about various configuration options can be found in:
- [`src/l2hmc/configs.py`](./src/l2hmc/configs.py):
Contains implementations of the (concrete python objects) that are adjustable for our experiment.
- [`src/l2hmc/conf/config.yaml`](./src/l2hmc/conf/config.yaml):
Starting point with default configuration options for a generic `Experiment`.
for more information on how this works I encourage you to read [Hydra's
Documentation Page](https://hydra.cc).
## Running at ALCF
For running with distributed training on ALCF systems, we provide a complete
[`src/l2hmc/train.sh`](./src/l2hmc/train.sh)
script which should run without issues on either Polaris or ThetaGPU @ ALCF.
# Details
**Goal:** Use L2HMC to **efficiently** generate _gauge configurations_ for
calculating observables in lattice QCD.
A detailed description of the (ongoing) work to apply this algorithm to
simulations in lattice QCD (specifically, a 2D U(1) lattice gauge theory model)
can be found in [arXiv:2105.03418](https://arxiv.org/abs/2105.03418).
## Organization
### Dynamics / Network
For a given target distribution, π(x), the `Dynamics` object
([`src/l2hmc/dynamics/`](src/l2hmc/dynamics)) implements methods for generating
proposal configurations (x' ~ π) using the generalized leapfrog update.
This generalized leapfrog update takes as input a buffer of lattice
configurations `x` and generates a proposal configuration `x' = Dynamics(x)` by
evolving generalized L2HMC dynamics.
#### Network Architecture
An illustration of the `leapfrog layer` updating `(x, v) --> (x', v')` can be seen below.
## Contact
***Code author:*** Sam Foreman
***Pull requests and issues should be directed to:*** [saforem2](http://github.com/saforem2)
## Citation
If you use this code or found this work interesting, please cite our work along with the original paper:
```bibtex
@misc{foreman2021deep,
title={Deep Learning Hamiltonian Monte Carlo},
author={Sam Foreman and Xiao-Yong Jin and James C. Osborn},
year={2021},
eprint={2105.03418},
archivePrefix={arXiv},
primaryClass={hep-lat}
}
```
```bibtex
@article{levy2017generalizing,
title={Generalizing Hamiltonian Monte Carlo with Neural Networks},
author={Levy, Daniel and Hoffman, Matthew D. and Sohl-Dickstein, Jascha},
journal={arXiv preprint arXiv:1711.09268},
year={2017}
}
```
## Acknowledgement
> **Note**
> 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.
> This work describes objective technical results and analysis.
> 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.