Extending the v1 API
Gaugefields v1 has two intentional application extension points: MD action providers define the potential and force, and integrators define the ordering of the elementary gauge and momentum updates. A new storage backend is not required for ordinary applications; LatticeMatrices/JACC supplies the portable CPU, GPU, MPI, and multi-GPU field implementation.
Custom MD action provider
Define a type that owns the immutable action parameters:
struct MyAction{T}
coupling::T
endThen implement the three provider methods:
Gaugefields.md_action_workspace(action::MyAction, U) = MyWorkspace(U)
function Gaugefields.md_potential(action::MyAction, U, workspace)
# Return the complete real potential V(U).
return potential
end
function Gaugefields.md_force!(force, action::MyAction, U, workspace)
# Overwrite every force[mu] with dP[mu]/dtau.
# Each result must be traceless and anti-Hermitian.
return nothing
endmd_action_workspace is called once by md_driver. Allocate reusable gauge fields and other large buffers there. md_potential and md_force! must use the same sign and normalization convention so that Hamiltonian diagnostics and the MD evolution agree.
Use the provider like a built-in GaugeAction:
action = MyAction(coupling)
driver = md_driver(U, action; steps=20)
P = gaussian_momenta(U; seed=1234, sweep=0)
result = md_trajectory!(U, P, driver)Enzyme-defined force
For a differentiable four-dimensional LM potential, loading Enzyme activates enzyme_md_action:
using Enzyme
function potential(U1, U2, U3, U4, coupling, temps)
# U1,...,U4 and temps are underlying LatticeMatrices objects.
# Reuse temps and return the complete real V(U).
end
action = enzyme_md_action(potential, coupling; num_temps=3)
driver = md_driver(U, action; steps=20)The current Enzyme provider requires 4D LatticeMatrices fields with halo >= 1. Use mul_shifted!, mul_shifted_adjoint!, and mul_adjoint! inside the potential. CUDA multi-GPU use additionally requires CUDA-aware MPI. The complete plaquette example is in Automatic differentiation with Enzyme.
Custom integrator function
An integrator function implements one MD step. The mutated object is always the first argument of each elementary update:
function my_qpq!(U, P, delta_tau, driver)
update_gaugefields!(U, P, 0.5 * delta_tau, driver)
update_momenta!(P, U, delta_tau, driver)
update_gaugefields!(U, P, 0.5 * delta_tau, driver)
return nothing
end
driver = md_driver(U, action; steps=20, integrator=my_qpq!)Parameterized integrator
Define an ordinary Julia type and extend Gaugefields.md_step!:
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
endSubtyping a Gaugefields type is optional. The method must apply exactly one step and multiply all coefficients by delta_tau. HMC integrators should normally be symmetric and tested for reversibility.
Storage implementations
The old guide for defining AbstractGaugefields subtypes described the pre-v1 wing, direct-shift, accelerator, and MPI storage families. Those types remain readable for compatibility, but new portable work should extend LatticeMatrices rather than add another accelerator-specific Gaugefields storage tree. The historical implementation contract is retained in Legacy API.