Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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: about 1 month 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 (almost 6 years ago)
Default Branch: main
Last Pushed: 2024-02-02T21:33:22.000Z (12 months ago)
Last Synced: 2024-12-15T03:49:47.133Z (about 1 month 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

        


![l2hmc-qcd](./assets/logo-small.svg)

    

 




  




   




[](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.