Public v1 API index

This page collects the docstrings for the recommended Gaugefields v1 entry points. Detailed parameter tables are in High-level API parameters.

Configurations and metadata

Gaugefields.gauge_configuration — Function
gauge_configuration(lattice; kwargs...)

Create one gauge link field for every direction of lattice. The return value is the existing Vector representation and therefore has length length(lattice).

The new API defaults to LatticeMatricesBackend, while the historical Initialize_Gaugefields default is unchanged. Use backend=LegacyBackend() to request the serial compatibility implementation explicitly.

Keywords

  • colors=3: number of colors.
  • halo=1: halo width.
  • start=:cold: either :cold or :hot.
  • seed=nothing: reproducible global-site seed for a LatticeMatrices hot start.
  • process_grid=nothing: process grid for LatticeMatrices.
  • comm=nothing: serial without MPI.jl; after using MPI, selects MPI.COMM_WORLD. Pass SerialCommunicator() to force serial execution.
  • boundary=:periodic: boundary phases or :periodic.
  • eltype=ComplexF64: element type.
  • rng=Philox4x32(): site-local RNG algorithm for LatticeMatrices.
  • verbose=0: verbosity level.
source
Gaugefields.copy_configuration! — Function
copy_configuration!(destination, source)

Copy a complete gauge configuration into preallocated compatible storage. Backend-specific copy methods are used so device synchronization and halo state are handled consistently. The destination is returned.

source

U(1) fields and the specialized Oneinstanton and Oneinstanton_SUN_embedded constructors are covered in Two and three dimensions.

Momenta and measurements

Gaugefields.gaussian_momenta — Function
gaussian_momenta(U; sigma=1, seed=nothing, sweep=0, rng=Philox4x32())

Allocate conjugate momenta compatible with U and fill them from a Gaussian distribution. Explicit seeds and site-local RNG algorithms require the LatticeMatrices backend.

source
Gaugefields.gaussian_momenta! — Function
gaussian_momenta!(momenta; sigma=1, seed=nothing, sweep=0,
                  rng=Philox4x32())

Fill preallocated conjugate momenta in place. Explicit seeds and site-local RNG algorithms require LatticeMatrices-backed momenta. The momentum array is returned.

source
Gaugefields.measure_plaquette — Function
measure_plaquette(U; normalize=true)

Calculate the plaquette. The default is normalized so that a cold configuration returns one. Set normalize=false for the historical summed value returned by calculate_Plaquette.

source
Gaugefields.measure_polyakov_loop — Function
measure_polyakov_loop(U; normalize=true)

Calculate the Polyakov loop in the final lattice direction. The default divides the color trace by the number of colors.

source

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

Wilson-loop actions

Gaugefields.GaugeAction_module.GaugeAction — Type
GaugeAction(U; hascovnet=false)

Construct an initially empty Wilson-loop action compatible with the gauge configuration U. Add a term with push!(action, coefficient, closedloops), where closedloops is a vector of Wilsonline{Dim} objects. Include the Hermitian-conjugate paths when the loop set is not already closed under conjugation and the action must be real.

The same action object can be evaluated with evaluate_GaugeAction, differentiated with calc_dSdUμ!, and passed to heatbath_updater or md_driver.

source
Gaugefields.GaugeAction_module.evaluate_GaugeAction — Function
evaluate_GaugeAction(action, U)

Return the traced, lattice-summed Wilson-loop expression stored in action. For the built-in MD action provider, the corresponding potential energy is -real(evaluate_GaugeAction(action, U)) / U[1].NC.

source
Gaugefields.GaugeAction_module.calc_dSdUμ — Function
calc_dSdUμ(action, μ, U)

Allocate and return the matrix derivative of action with respect to links in direction μ. This is the raw action derivative used to construct staples; the MD driver performs the additional link multiplication, normalization, and traceless anti-Hermitian projection required for dp/dτ.

source

make_loops_fromname is re-exported from Wilsonloop.jl. Direct construction of Wilsonline paths and low-level evaluate_gaugelinks! usage are documented in Wilson loops and gauge actions.

Updates, flow, smearing, and I/O

Gaugefields.AbstractGaugefixing_module.gaugefixing! — Function
gaugefixing!(U, g_transform, LA_overrelax, LA_iteration,
             SD_overrelax, SD_iteration, tol, config_n, temp_master;
             D_fix=4, min_iterations=500)

Gauge-fix U with Los Alamos and steepest-descent updates. Each stage runs for at least min(min_iterations, requested_iterations) iterations before its tolerance test may stop it. Set min_iterations=0 to test convergence after the first iteration.

On return, g_transform contains the most recent checkerboard transformation; it is not the accumulated transformation from the input configuration.

source
Gaugefields.stout_smearing — Function
stout_smearing(U; loops=:plaquette, rho=0.1)

Construct a one-layer stout-smearing pipeline without exposing the internal CovNeuralnet terminology. This compatibility API supports arbitrary loop sets. For the native plaquette-only implementation with an analytic pullback, use StoutSmearing (or its EXPSmearing alias) with smear.

source
Gaugefields.smear — Function
smear(U, smearing::LCNNLinkSmearing;
      record=false, calcdSdU=false, temps=nothing)

Apply Plaq -> LCNN feature layers -> LExp through the ordinary Gaugefields link-smearing API. The default return value is a vector of updated gauge links. With record=true, return (configuration, history, derivative), where history is a reusable LCNNLinkSmearingCache. If calcdSdU=true, derivative is a callable vector–Jacobian product accepting an output-link cotangent; otherwise it is nothing.

Passing history back as temps reuses all lattice-sized storage and overwrites the earlier returned configuration owned by that workspace.

source
smear(U, smearing; record=false)

Apply a smearing pipeline. Return only the smeared configuration by default. With record=true, return a named tuple containing configuration, history, and derivative.

source
Gaugefields.save_configuration — Function

Save a gauge configuration in JLD2, Bridge, ILDG, NERSC, or MILC format. Portable JLD2 output gathers physical links to rank 0 and stores backend-independent host arrays; all ranks owning a distributed configuration must participate.

source
Gaugefields.load_configuration — Function

Load a portable JLD2, NERSC, or MILC gauge configuration. The destination is allocated on the current JACC backend and communicator; process_grid and comm may differ from those used when the file was written.

source
Gaugefields.load_configuration! — Function

Load a gauge configuration into an existing target. For format=:milc, reunitarize=true projects the single-precision links onto SU(3) as MILC does after reading in double precision; MILC I/O is experimental and reports the setting in a warning.

source

Molecular dynamics

Gaugefields.MDDriver — Type
MDDriver

Preallocated, deterministic molecular-dynamics driver. Construct one with md_driver, then reuse it with md_trajectory!.

The driver does not generate momenta, draw random numbers, or perform an accept/reject decision.

source
Gaugefields.md_driver — Function
md_driver(U, action; steps, trajectory_length=1.0, integrator=QPQ(),
          momentum_denominator=1.0)

Construct a reusable molecular-dynamics driver for U and action.

steps is required. trajectory_length may be negative, which is useful for reversibility checks, but must be finite and nonzero. integrator may be PQP(), QPQ(), or any custom object implementing md_step!. momentum_denominator selects the momentum/MD-time normalization: the kinetic energy is p*p/(2*momentum_denominator), and momentum kicks are multiplied by momentum_denominator. The default 1 preserves the historical Gaugefields/LTK convention; 2 is the Grid/Bridge++ convention and requires Gaussian momentum coefficients with standard deviation sqrt(2).

source
md_driver(U, action::GaugeAction, B::Bfield; kwargs...)

Construct an MD driver using B in both the potential and the U force. Equivalent to md_driver(U, BfieldGaugeAction(action, B); kwargs...).

source
Gaugefields.MDForceGroup — Type
MDForceGroup(names...)

Select named members of an MDActionSet for a momentum update. The names are stored in the group type so the selected action providers remain type-stable in the integration loop.

source
Gaugefields.QPQ — Type
QPQ()

Second-order symmetric Q(1/2) P(1) Q(1/2) integrator. This is the ordering used by the historical Gaugefields HMC examples and is the default of md_driver.

source
Gaugefields.PQP — Type
PQP()

Second-order symmetric P(1/2) Q(1) P(1/2) integrator. Here P updates the momenta and Q updates the gauge links.

source
Gaugefields.SextonWeingarten — Type
SextonWeingarten(; slow, fast, n_fast, ordering=QPQ())

Second-order Sexton–Weingarten integrator for two force time scales. slow and fast are action names, tuples of action names, or MDForceGroup objects selecting members of an MDActionSet. n_fast is a positive runtime integer and is deliberately not a type parameter.

With the default QPQ() ordering, a half-duration evolution of the fast Hamiltonian is applied on each side of one full slow-force update. Each half is divided into n_fast QPQ substeps. With PQP() ordering, half slow-force updates surround one full fast evolution divided into n_fast QPQ substeps.

source
Gaugefields.md_hamiltonian — Function
md_hamiltonian(U, p, driver)

Calculate the Hamiltonian used by the MD driver. The potential comes from the driver's action provider and the kinetic term is p*p/(2*driver.momentum_denominator).

source
Gaugefields.md_trajectory! — Function
md_trajectory!(U, p, driver; diagnostics=true)

Evolve U and p in place through one deterministic MD trajectory. No momentum refresh or accept/reject step is performed.

With diagnostics=true, return a named tuple containing initial_hamiltonian, final_hamiltonian, and delta_hamiltonian. Set it to false to skip the two Hamiltonian evaluations and return nothing.

source
Gaugefields.update_momenta! — Function
update_momenta!(P, U, step_size, driver)

Update only the conjugate momenta as P ← P + momentum_denominator * step_size * force(U). The mutated momenta P are the first argument and are also returned.

source
update_momenta!(P, U, step_size, driver, group::MDForceGroup)

Update the momenta with only the named members selected from the driver's MDActionSet. This is the elementary kick used by SextonWeingarten and custom multiple-time-scale integrators.

source
Gaugefields.update_gaugefields! — Function
update_gaugefields!(U, P, step_size, driver)

Update only the gauge fields as Uμ ← exp(step_size * Pμ) Uμ. The mutated gauge configuration U is the first argument and is also returned.

source

MD action providers

Gaugefields.md_potential — Function
md_potential(action, U, workspace)

Return the potential energy represented by an MD action provider. The result must use the same normalization and sign convention as its md_force! method.

source
Gaugefields.md_force! — Function
md_force!(force, action, U, workspace)

Write the traceless anti-Hermitian molecular-dynamics force dp/dτ to force. Custom action providers own the conversion from their derivative representation to this common force convention.

source
md_force!(force, actions, U, workspace, group::MDForceGroup)

Write the sum of only the selected action forces to force. This is the force-selection operation used by multiple-time-scale integrators.

source
Gaugefields.enzyme_md_action — Function
enzyme_md_action(potential, arguments...; num_temps=0)

Construct an Enzyme-backed MD action provider. This method becomes available after loading Enzyme through the Gaugefields Enzyme extension. potential receives the four underlying LatticeMatrices link matrices separately, followed by arguments and, when num_temps > 0, the LM work-field collection.

source

Automatic differentiation

Enzyme_derivative! writes the matrix gradient of a real scalar function. nodiff, diff, realtrace, Wiltinger_derivative!, and Wiltinger_numerical_derivative are also exported for differentiation workflows. Their argument conventions and the distinction between a raw gradient and an MD force are explained in Automatic differentiation with Enzyme.

The pre-v1 exported surface remains available for compatibility but is listed separately in Legacy API.