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: MPI process grid for LatticeMatrices.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 MPI process grid as a tuple.
Gaugefields.gauge_communicator — Function
Return the MPI communicator, or nothing for a serial legacy field.
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.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.stout_smearing — Function
stout_smearing(U; loops=:plaquette, rho=0.1)Construct a one-layer stout-smearing pipeline without exposing the internal CovNeuralnet terminology.
Gaugefields.smear — Function
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, or ILDG format.
Gaugefields.load_configuration — Function
Load a JLD2 gauge configuration and preserve its stored backend type.
Gaugefields.load_configuration! — Function
Load a gauge configuration into an existing target.
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())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!.
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.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.
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 + step_size * force(U). The mutated momenta P are the first argument and are also returned.
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.
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.
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.