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:coldor: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; afterusing MPI, selectsMPI.COMM_WORLD. PassSerialCommunicator()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.
Gaugefields.LatticeMatricesBackend — Type
LatticeMatricesBackend()Select the portable LatticeMatrices/JACC implementation. This is the default backend of gauge_configuration.
Gaugefields.LegacyBackend — Type
LegacyBackend()Select the serial compatibility implementation used by the historical API. The historical Initialize_Gaugefields entry point keeps its existing default independently of the new API.
Gaugefields.gauge_backend — Function
Return the backend used by a gauge link or gauge configuration.
Gaugefields.gauge_lattice_size — Function
Return the global lattice size as a tuple.
Gaugefields.gauge_num_colors — Function
Return the number of colors.
Gaugefields.gauge_halo_width — Function
Return the halo width.
Gaugefields.gauge_process_grid — Function
Return the process grid as a tuple.
Gaugefields.gauge_communicator — Function
Return the serial/MPI communicator, or nothing for serial legacy storage.
Gaugefields.copy_configuration — Function
Allocate and return an independent copy of a gauge configuration.
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.
U(1) fields and the specialized Oneinstanton and Oneinstanton_SUN_embedded constructors are covered in Two and three dimensions.
Momenta and measurements
Gaugefields.gauge_momenta — Function
Allocate zero-valued conjugate momentum fields compatible with U.
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.
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.
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.
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.
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.
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.
Gaugefields.GaugeAction_module.evaluate_GaugeAction_untraced — Function
evaluate_GaugeAction_untraced(action, U)Allocate and return the untraced link-field sum represented by action. Taking tr of the result gives evaluate_GaugeAction.
Gaugefields.GaugeAction_module.evaluate_GaugeAction_untraced! — Function
evaluate_GaugeAction_untraced!(output, action, U)Overwrite output with the untraced link-field sum represented by action.
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τ.
Gaugefields.GaugeAction_module.calc_dSdUμ! — Function
calc_dSdUμ!(derivative, action, μ, U)Overwrite derivative with the matrix derivative of action in direction μ. See calc_dSdUμ for the derivative convention.
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.gradient_flow — Function
Construct the standard Wilson gradient-flow integrator.
Construct a general-action gradient-flow integrator.
Gaugefields.heatbath_updater — Function
Construct a plaquette heatbath updater.
Construct a general-action heatbath updater.
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.
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.
Gaugefields.lcnn_smearing — Function
Construct an LCNNLinkSmearing for use with Gaugefields.smear.
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.
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.
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.
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.
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.
Molecular dynamics
Gaugefields.AbstractMDIntegrator — Type
Supertype for molecular-dynamics integration schemes.
Gaugefields.MDDriver — Type
MDDriverPreallocated, 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.
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).
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...).
Gaugefields.MDActionSet — Type
MDActionSet(; name=action, ...)
MDActionSet(actions::NamedTuple)Collect independently scheduled MD action providers in a type-stable named tuple. Every member implements md_action_workspace, md_potential, and md_force!. The combined potential and force are the sums of the member contributions.
Names are also used by MDForceGroup and SextonWeingarten to select time scales.
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.
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.
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.
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.
Gaugefields.md_step_size — Function
Return the MD step size, trajectory_length / steps.
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).
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.
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.
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.
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.
Gaugefields.md_step! — Function
md_step!(integrator, U, P, step_size, driver)Apply one molecular-dynamics integration step, mutating U and P in place. Custom integrators implement this method using update_momenta! and update_gaugefields!. Subtyping AbstractMDIntegrator is optional.
MD action providers
Gaugefields.md_action_workspace — Function
md_action_workspace(action, U)Allocate reusable work fields for an MD action provider. Custom action providers implement this function together with md_potential and md_force!.
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.
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.
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.
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.
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.