High-level API parameters

This page lists the public convenience API introduced for Gaugefields v1. Detailed examples start in the four-dimensional tutorial.

Gauge configurations

gauge_configuration(lattice; kwargs...)
KeywordDefaultChoices or constraints
backendLatticeMatricesBackend()LatticeMatricesBackend() or LegacyBackend()
colors3Positive integer
halo1Nonnegative integer
start:cold:cold, :hot
seednothingInteger seed or nothing; explicit seeds require LM
process_gridnothingPositive integer tuple/vector of length Dim, or automatic
boundary:periodic:periodic or one phase per dimension
eltypeComplexF64LM: Float32, Float64, ComplexF32, or ComplexF64
rngPhilox4x32()Philox4x32(), PCG32(), Xoshiro256PlusPlus()
verbose0Integer output level

The supported lattice dimensionalities are 2, 3, and 4. The return value is a vector of length Dim. A 3D LegacyBackend configuration requires halo=0; the recommended LM backend uses the common default halo=1.

Metadata

These functions accept either one link or a complete configuration where applicable:

FunctionResult
gauge_backend(U)LatticeMatricesBackend() or LegacyBackend()
gauge_lattice_size(U)Global lattice-size tuple
gauge_num_colors(U)Number of colors
gauge_halo_width(U)Halo width
gauge_process_grid(U)MPI process-grid tuple
gauge_communicator(U)MPI communicator, or nothing for serial legacy storage

Conjugate momenta

gauge_momenta(U) allocates zero-valued momentum fields compatible with U.

gaussian_momenta(U; kwargs...)
KeywordDefaultChoices or constraints
sigma1.0Gaussian standard deviation
seednothingInteger or nothing; explicit seed requires LM
sweep0Nonnegative trajectory/stream counter
rngPhilox4x32()Philox4x32(), PCG32(), Xoshiro256PlusPlus()

Measurements

measure_plaquette(U; normalize=true)
measure_polyakov_loop(U; normalize=true)

With normalize=true, a cold field returns one. normalize=false selects the historical summed/unnormalized convention.

Topological charge, topological-charge density, energy density, and other physics measurements are provided by QCDMeasurements.jl; see Measurements.

Wilson loops and gauge actions

Create a coefficient-weighted action from one or more groups of closed Wilson paths:

action = GaugeAction(U)
loops = make_loops_fromname("plaquette"; Dim=length(U))
append!(loops, loops')
push!(action, coefficient, loops)
FunctionResult
evaluate_gaugelinks!(output, loops, U, temps)Ordered path product, summed for a loop collection
evaluate_GaugeAction(action, U)Coefficient-weighted traced lattice sum
evaluate_GaugeAction_untraced(action, U)Allocated matrix-valued action sum
evaluate_GaugeAction_untraced!(output, action, U)In-place matrix-valued action sum
calc_dSdUμ(action, μ, U)Allocated raw matrix derivative in direction μ
calc_dSdUμ!(output, action, μ, U)In-place raw matrix derivative

See Wilson loops and gauge actions for explicit Wilsonline paths, coefficient conventions, and reuse in heatbath, gradient flow, and MD.

Heatbath and overrelaxation

For a plaquette action:

heatbath_updater(U; beta, kwargs...)
heatbath_updater(U, beta; kwargs...)
ParameterDefaultMeaning
betarequiredPlaquette coupling
ITERATION_MAX10^5Positive rejection-loop limit
seed0LM site-stream seed
sweep0Initial heatbath sweep counter
overrelaxation_sweepsweepInitial independent overrelaxation counter
rng_algorithmPhilox4x32()Philox4x32(), PCG32(), Xoshiro256PlusPlus()

Apply the updater with heatbath!(U, updater) or overrelaxation!(U, updater). The corresponding counter advances after a successful call.

For a general GaugeAction:

heatbath_updater(U, action; kwargs...)

This accepts the same random-stream parameters and also:

KeywordDefaultChoices or constraints
coloring:auto:auto, :sequential, or a valid tuple of HeatbathColoring values
max_colors256Positive search limit used by :auto

coloring=:auto derives a safe periodic coloring from the action staples. :sequential is an exact but deliberately slow fallback.

Gradient flow

gradient_flow(U; steps=1, step_size=0.01)
gradient_flow(U, loops, coefficients; steps=1, step_size=0.01)

steps and step_size must be positive. The second form constructs a general-action flow from explicit loops and coefficients. Apply the resulting integrator with flow!(U, flow).

Stout smearing

stout_smearing(U; loops=:plaquette, rho=0.1)

loops may be one symbol/string or a collection. rho may be one scalar or one coefficient per loop.

smear(U, smearing; record=false, calcdSdU=false, temps=nothing)

The default return value is the smeared configuration. record=true returns a named tuple containing configuration, history, and derivative.

Configuration I/O

save_configuration(filename, U; format=:jld2, kwargs...)
load_configuration(filename; format=:jld2)
load_configuration!(U, filename; format=:jld2)

save_configuration and load_configuration! accept :jld2, :bridge, and :ildg. Allocating load_configuration currently accepts only :jld2; Bridge and ILDG input require a preallocated destination.

Molecular dynamics

Construct a pure-gauge MD driver once and reuse its preallocated work fields:

driver = md_driver(
    U,
    action;
    steps=20,
    trajectory_length=1.0,
    integrator=QPQ(),
)

result = md_trajectory!(U, p, driver)
ParameterDefaultChoices or constraints
UrequiredGauge configuration used to allocate the driver
actionrequiredA GaugeAction or an object implementing the MD action-provider interface
stepsrequiredPositive integer number of MD steps
trajectory_length1.0Finite, nonzero number; a negative value is useful for reversibility tests
integratorQPQ()QPQ(), PQP(), a step function, or an object implementing md_step!

QPQ() applies Q(1/2) P(1) Q(1/2) in each step and matches the ordering in the historical Gaugefields HMC examples. PQP() applies P(1/2) Q(1) P(1/2). Here Q updates the gauge links and P updates the momenta. md_step_size(driver) returns trajectory_length / steps.

md_trajectory! mutates both U and p. With its default diagnostics=true, it returns initial_hamiltonian, final_hamiltonian, and delta_hamiltonian. Pass diagnostics=false to omit those two global Hamiltonian evaluations and return nothing. md_hamiltonian(U, p, driver) is also available directly.

Analytic and Enzyme forces

A GaugeAction uses Gaugefields' analytic force. To differentiate a custom scalar potential with Enzyme, load Enzyme and wrap the function:

using Enzyme

# The potential must return the complete, real potential energy V(U).
# If num_temps is nonzero, Gaugefields appends `temps` to this argument list.
function my_potential(U1, U2, U3, U4, coupling, temps)
    # Fill/reuse temps and calculate V(U1, U2, U3, U4).
    return value
end

action = enzyme_md_action(my_potential, coupling; num_temps=3)
driver = md_driver(U, action; steps=20)

The four links are passed as separate arguments so that Enzyme can differentiate them. Extra positional arguments given to enzyme_md_action are treated as constants. When num_temps > 0, the final argument received by the potential is a collection of that many reusable gauge fields; Gaugefields clears it before each evaluation and allocates the matching shadow workspace. The function must return a real scalar with the desired sign and normalization already included. The same function supplies both the Hamiltonian value and the automatically differentiated force, preventing an action/force mismatch.

The initial Enzyme MD implementation supports four-dimensional LatticeMatrices configurations with halo >= 1, including CUDA and MPI. A regular GaugeAction remains the portable choice for Legacy fields and for two- or three-dimensional configurations. CUDA multi-GPU execution requires a CUDA-aware MPI installation, with matching mpiexec and libmpi selections.

For direct access to the matrix gradient, constant-argument annotations, and primal/adjoint work fields, see Automatic differentiation with Enzyme.

Other packages can implement an action provider by defining all three methods:

Gaugefields.md_action_workspace(action::MyAction, U) = MyWorkspace(U)
Gaugefields.md_potential(action::MyAction, U, workspace) = potential_value
function Gaugefields.md_force!(force, action::MyAction, U, workspace)
    # Write dp/dtau, as traceless anti-Hermitian fields, into `force`.
    return nothing
end

md_action_workspace is called once by md_driver; the other two methods must reuse it rather than allocate large work fields on every stage.

Custom integrators

The two elementary MD operations make the mutated field explicit as their first argument:

  • update_momenta!(P, U, delta_tau, driver) changes P and leaves U unchanged.
  • update_gaugefields!(U, P, delta_tau, driver) changes U and leaves P unchanged.

Both functions return the field named by their first argument. The ! and the argument order therefore show exactly which object is updated.

For a one-off integrator, write an ordinary Julia function for one MD step. md_trajectory! calls it steps times with delta_tau = trajectory_length / steps:

function five_update_pqp!(U, P, delta_tau, driver)
    update_momenta!(P, U, 0.25 * delta_tau, driver)
    update_gaugefields!(U, P, 0.5 * delta_tau, driver)
    update_momenta!(P, U, 0.5 * delta_tau, driver)
    update_gaugefields!(U, P, 0.5 * delta_tau, driver)
    update_momenta!(P, U, 0.25 * delta_tau, driver)
    return nothing
end

driver = md_driver(U, action; steps=20, integrator=five_update_pqp!)

For a reusable named integrator, define a type in the application or package that owns it, then extend Gaugefields.md_step!. Subtyping AbstractMDIntegrator is optional. For example, an Omelyan-style PQP update is:

struct OmelyanPQP{T}
    lambda::T
end

function Gaugefields.md_step!(
    integrator::OmelyanPQP,
    U,
    P,
    delta_tau,
    driver,
)
    lambda = integrator.lambda
    update_momenta!(P, U, lambda * delta_tau, driver)
    update_gaugefields!(U, P, 0.5 * delta_tau, driver)
    update_momenta!(P, U, (1 - 2lambda) * delta_tau, driver)
    update_gaugefields!(U, P, 0.5 * delta_tau, driver)
    update_momenta!(P, U, lambda * delta_tau, driver)
    return nothing
end

driver = md_driver(
    U,
    action;
    steps=20,
    integrator=OmelyanPQP(0.1931833275037836),
)

The custom method must implement exactly one step. It is responsible for multiplying every coefficient by delta_tau; negative coefficients are allowed. For standard HMC, the sequence should normally be symmetric so that changing the sign of trajectory_length reverses the evolution. The original integrator function or object is retained as driver.integrator.

This extension point changes only the ordering and coefficients. It is independent of the force source, so the same custom integrator works with a GaugeAction, enzyme_md_action, or another action provider. Integrators that need additional stage kinds, nested time scales, or multiple independently scheduled actions require a separate higher-level driver.

HMC responsibility boundary

Gaugefields deliberately provides deterministic MD evolution rather than an HMC updater. It does not refresh momenta, draw a Metropolis random number, accept or reject a proposal, restore a rejected configuration, or own a trajectory counter. Those policy and random-state operations belong in an application or a higher-level HMC package.

An HMC layer built on md_driver therefore owns the following parameters:

HMC parameterOwner or choice
Gauge actionPassed to md_driver
MD integratorQPQ(), PQP(), a step function, or a custom md_step! method
Trajectory length and step countPassed to md_driver
Momentum widthsigma=1.0 by default in gaussian_momenta
Momentum random streamseed, trajectory sweep, and rng passed to gaussian_momenta
Metropolis random streamSupplied and synchronized by the HMC layer
Acceptance, rollback, and trajectory counterMaintained by the HMC layer

See Randomness and reproducibility for the complete state that a reproducible HMC chain must save.