MetaQCD.jl

Inspired by the LatticeQCD.jl package by Akio Tomiya et al.

For detailed information on how to use this package, see the docs.

Features:

• Simulations of 4D-SU(3) Yang-Mills (Pure Gauge) theory
• Simulations of full lattice QCD with arbitrary number of flavours (Staggered, Wilson-Clover)
• Metadynamics
• PT-MetaD
• Several update algorithms (HMC, Metropolis, Heatbath, Overrelaxation)
• Several symplectic integrators for HMC (Leapfrog, OMF2, OMF4)
• Gradient flow with variable integrators (Euler, RK2, RK3, RK3W7)
• Improved Gauge actions (Symanzik tree, Iwasaki, DBW2)
• Improved Topological charge definitions (clover, rectangle clover-improved)
• Wilson(-Clover) fermions
• Staggered fermions
• RHMC to simulate odd number of flavours
• Even-odd preconditioner for Wilson(-Clover)
• Even-odd preconditioner for Staggered
• Mass-splitting preconditioner / Hasenbusch trick
• Full support for CUDA and ROCm backends
• Multi-node parallelism using MPI (not working with even-odd preconditioned fermions yet)

Installation:

First make sure you have Julia version 1.9.4 installed. You can use juliaup for that or just install the release from the Julia website.

Versions above this work too, but all development and optimization is done on 1.9.4 up until now and for the foreseeable future.

Then:

1. Clone the latest release onto your machine.
2. Open Julia in the directory which you cloned the repo into, with the project specific environment. This can either be done by starting Julia with the command line argument "--project" or by activating the environment within an opened Julia instance via the package manager:

using Pkg
Pkg.activate(".")

Or you can switch to package manager mode by typing "]" and then do

pkg> activate .

3. Instantiate the project to install all the dependencies using the package manager:

Pkg.instantiate()

or

pkg> instantiate

If you want to use a GPU (still experimental), make sure you not only have CUDA.jl or AMDGPU.jl installed, but also a fairly recent version of the CUDA Toolkit or ROCm.

Quick Start:

1. Set parameters using one of the templates in template folder
2. From shell, do:

julia --threads=auto metaqcd.jl -mode=sim parameters.toml

or

2. Start Julia (with project):

julia --threads=auto --project=/path/to/dir/containing/MetaQCD.jl

3. Import MetaQCD package:

using MetaQCD

4. Begin Simulation with prepared parameter file "parameters.toml":

run_sim("parameters.toml")

To use another backend, add the -backend flag like:

julia --threads=auto metaqcd.jl -mode=sim -backend=cuda parameters.toml

Build a Bias:

1. Set parameters using the "parameters_build.toml" example in template folder
2. From shell, do:

julia --threads=auto metaqcd.jl -mode=build parameters.toml

or

2. Start Julia (with project):

julia --threads=auto --project=/path/to/dir/containing/MetaQCD.jl

3. Import MetaQCD package:

using MetaQCD

4. Begin build with prepared parameter file "parameters.toml":

build_bias("parameters.toml")

Visualization:

We include the ability to visualize your data. For that, you just have to pass the directory where your ensemble lives:

] activate MetaAnalysis/
] instantiate
using MetaAnalysis
measurements = MetaMeasurements("/path/to/ensemble")
timeseries(measurements, :my_observable)

You can also create a holder of a bias potential and plot it. MetaQCD.jl creates the bias files with an extension that gives their type (.metad or .opes), but if you changed the extension you have to provide the bias type as a symbol under the kwarg which:

bias = MetaBias(myfile)
plot(bias)