Normalizing Flows for Lattice Quantum Field Theory

PyTorch implementations of normalizing-flow samplers for several Euclidean lattice field theories in 1+1 dimensions. The repository is organized as a collection of focused research scripts rather than a general-purpose simulation package.

Implemented Models

Theory	Degrees of freedom	Main script	Reference checks
Scalar phi-four	Real scalar field	phi4/phi4_1_1D.py	Exact free theory or Metropolis benchmark
Pure compact U(1)	Periodic link angles	U_1_gauge_theory/U1_2D.py	Metropolis, Wilson loops, topology, gauge-orbit diagnostics
Schwinger model	U(1) links with staggered fermion determinant	U_1_gauge_theory/schwinger.py	Determinant, topology, Wilson loops, meson correlator
Pure SU(2) Yang-Mills	Quaternion-valued links	SU_2_gauge_theory/SU_2_2D.py	Metropolis, Wilson loops, Haar/unit-norm and inverse checks
SU(2)-Higgs	SU(2) links and a fundamental scalar	SU_2_gauge_theory/higgs_2D.py	Joint gauge/scalar Metropolis and invertibility checks

All current training configurations use a two-dimensional Euclidean lattice: one spatial and one Euclidean-time direction.

Repository Layout

.
├── phi4/                 # Scalar theory training and observables
├── U_1_gauge_theory/     # Pure U(1), Schwinger model, and correlators
├── SU_2_gauge_theory/    # Pure SU(2), SU(2)-Higgs, and focused tests
├── scripts/               # Repository maintenance and download helpers
├── artifacts/            # Generated checkpoints, plots, and evaluations (created when you train models)
└── requirements.txt

Generated outputs are kept out of the source directories. Existing local checkpoints and plots are preserved under artifacts/{phi4,u1,su2}.

Setup

Python 3.10 or newer is recommended.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

PyTorch installation varies by platform. If the command above does not install the desired CUDA build, follow the platform-specific instructions at pytorch.org, then install the remaining requirements.

The scripts prefer Apple Metal (mps) when available and otherwise generally use CPU. The phi-four training and mass scripts currently set device = "mps" directly; change that setting to "cpu" or "cuda" on other platforms.

Usage

Run scripts from their theory directory because the analysis scripts use local module imports.

Scalar phi-four

cd phi4
python phi4_1_1D.py
python benchmark_free_theory.py
python calculate_mass.py

The benchmark supports CLI options such as --checkpoint, --m2, --lam, --num-batches, and --device. Video generation requires FFmpeg.

Pure U(1)

cd U_1_gauge_theory
python U1_2D.py

Schwinger model

cd U_1_gauge_theory
python schwinger.py --mass 1.0
python schwinger.py --mass 0.8 --ft 1.0
python meson_correlator.py

--ft initializes a run from a checkpoint at another fermion mass. --topo-features enables the experimental frozen topological-proxy conditioner feature.

Pure SU(2)

cd SU_2_gauge_theory
python SU_2_2D.py

SU(2)-Higgs

cd SU_2_gauge_theory
python higgs_2D.py

The SU(2) trainers perform forward/inverse reconstruction and log-Jacobian cancellation checks before saving their final checkpoints.

Benchmark Highlights

Representative saved-checkpoint results on 8 x 8 lattices are summarized below. Flow samples are compared with finite-run Metropolis references unless noted otherwise, so these values should be treated as reproducibility snapshots rather than exact or architecture-wide guarantees.

Model	Representative result
Interacting phi-four (m2=1, lambda=1)	Across three seeds, field-histogram TV distance was 0.0093 +/- 0.0007, connected-correlator MAE was 0.0017 +/- 0.0001, and the mean-action gap was about -0.059.
Pure U(1) (beta=2)	Plaquette-histogram TV distance was 0.0135; mean plaquette was 0.6912 versus 0.6973; gauge-orbit mean absolute log q change was 3.6e-5.
Schwinger model (beta=2)	Across masses 1.0 to 0.2, plaquette-histogram TV remained approximately 0.0107-0.0138. The fermion log det D mean gap increased from 0.0103 at m=1.0 to 0.1257 at m=0.2, showing that the low-mass regime remains harder.
Pure SU(2) Yang-Mills (beta=2)	Plaquette-histogram TV distance was 0.0137; mean plaquette trace was 0.4295 versus 0.4337; the 2 x 2 Wilson-loop absolute gap was 0.0085.
SU(2)-Higgs	Plaquette-histogram TV distance was 0.0238, Higgs `

The benchmarks also check topology, Wilson loops, group constraints, inverse reconstruction, and forward/inverse log-Jacobian cancellation where applicable.

Using pretrained models

Download all published checkpoints from Hugging Face:

python scripts/download_pretrained.py

The script creates artifacts/ when necessary and preserves the repository's phi4/, u1/, and su2/ checkpoint layout. Existing up-to-date downloads are reused. A branch, tag, or commit can be selected with --revision; use --force-download to refresh every checkpoint.

python scripts/download_pretrained.py --revision main --force-download

Reproducibility Notes

• Training hyperparameters currently live near the top of each script's main() function.
• Checkpoints, plots, benchmark videos, and JSON evaluations are written to artifacts/ and are not version-controlled.
• The code is research-oriented and several default runs are computationally expensive.
• Metropolis comparisons are finite-run references, not exact solutions unless explicitly stated by the phi-four free-theory benchmark.
• For best performance when training a model for Schwinger, I suggest a mass curriculum. I started with mass 1.0 and reduced in in increments of 0.2 until the mass was 0.2, with each model being fine-tuned from the last.