Code Architecture - ALF — Algorithms for Lattice Fermions

Overview of the ALF module structure and data flow.

Source Directories¶

Directory	Contents
`Prog/`	Main QMC code: entry point, control loop, Hamiltonian interface, Green’s function, wrapping, updates
`Prog/Hamiltonians/`	Model submodules (one per Hamiltonian) and the template
`Libraries/Modules/`	Reusable Fortran modules: lattices, matrices, HDF5, RNG, Fourier, MPI shared memory
`Libraries/libqrref/`	QR decomposition library
`Analysis/`	Post-processing: `ana.F90`, `ana_hdf5.F90`, covariance analysis, converters, `Max_SAC.F90`
`testsuite/`	Unit and regression tests
`Scripts_and_Parameters_files/`	Job scripts, parameter templates, batch submission utilities
`HDF5/`	Per-compiler HDF5 build scripts
`Documentation/`	LaTeX documentation source

Module Hierarchy¶

main.F90
├── Hamiltonian_main_mod.F90    ← Hamiltonian interface (ham_base type)
│   ├── Hamiltonian_*_smod.F90  ← Model submodules (Hubbard, Kondo, tV, …)
│   ├── Operator_mod.F90        ← Op_V (interaction), Op_T (hopping)
│   ├── Fields_mod.F90          ← Auxiliary fields (nsigma)
│   ├── Observables_mod.F90     ← Obser_Vec, Obser_Latt containers
│   └── WaveFunction_mod.F90    ← Trial wave functions (projective QMC)
├── control_mod.F90             ← MC control: acceptance tracking, timing
├── cgr1_mod.F90                ← Green's function from scratch (UDV)
├── cgr2_2_mod.F90              ← Green's function update (rank-1)
├── wrapul_mod.F90              ← Wrap Green's function left (forward in τ)
├── wrapur_mod.F90              ← Wrap Green's function right (backward in τ)
├── Wrapgr_mod.F90              ← Wrap and recompute Green's function
├── UDV_WRAP_mod.F90            ← UDV stabilization during wrapping
├── Langevin_HMC_mod.F90        ← HMC and Langevin update schemes
├── Global_mod.F90              ← Global moves (space-time and single-τ)
├── QMC_runtime_var_mod.F90     ← Runtime parameters (from namelists)
└── Set_random_mod.F90          ← RNG initialization

Key Data Structures¶

Type	Module	Role
`ham_base`	`Hamiltonian_main_mod`	Abstract base for all Hamiltonians; extended by each model submodule
`Operator`	`Operator_mod`	Represents $e^{V}$ or $e^{T}$ operators with matrix, type, and metadata
`Fields`	`Fields_mod`	Auxiliary Hubbard-Stratonovich field array `f(N_op, Ltrot)`
`Obser_Vec`	`Observables_mod`	Scalar observable: stores one number per bin
`Obser_Latt`	`Observables_mod`	Lattice observable: stores correlation matrix per bin
`Lattice`	`lattices_v3_mod`	Bravais lattice: neighbor lists, distance map, reciprocal vectors
`Unit_cell`	`lattices_v3_mod`	Unit cell: orbital count, positions, coordination vectors
`WaveFunction`	`WaveFunction_mod`	Trial wave function for projective (T=0) QMC

Simulation Flow¶

A single ALF run proceeds as follows:

Initialization
- Read parameters (namelists) and seeds
- Call Ham_Set: build lattice, set up operators, initialize fields
- Call Alloc_obs: allocate observable containers
- Compute initial Green’s function from scratch (cgr1)
Monte Carlo loop (NBin bins × NSweep sweeps per bin)
- All bins are treated identically — there is no dedicated warmup phase in the simulation. Thermalization bins are discarded later at analysis time via n_skip.
- For each sweep:
  - Optionally perform tempering exchanges and global moves
  - Optionally perform Langevin/HMC updates
  - Upward sweep: traverse time slices $\tau = 0 \to L_\text{trot}-1$
    - At each slice: propose field updates (sequential / HMC / Langevin), update Green’s function via rank-1 updates (cgr2_2)
    - Every Nwrap slices: recompute Green’s function from scratch for numerical stability (cgr1 with UDV)
    - On slices in [LOBS_ST, LOBS_EN]: call Obser (equal-time measurements)
  - Downward sweep: traverse time slices $\tau = L_\text{trot} \to 1$
    - Same update and measurement logic as the upward sweep
  - At end of sweep: compute time-displaced correlations (TAU_M) if Ltau = 1
- At end of bin: average and write observables to disk (Pr_obs), save configuration (confout)
Finalization
- Write timing and acceptance statistics to info
- Remove RUNNING lock file

Build System¶

The build is driven by configure.sh + make:

source configure.sh <MACHINE> <MODE> [OPTIONS] — sets ALF_FC, ALF_FLAGS_PROG, ALF_LIB, preprocessor defines
make lib — compiles library modules (Libraries/)
make program — runs parse_ham.py to auto-generate Hamiltonian dispatch code, then compiles Prog/ → ALF.out
make ana — compiles analysis programs (Analysis/)

Dependencies within Prog/ are auto-generated by gen_deps.py.