Field
Field<T, NDim> phi("phi", toolBox);
A real scalar field on the lattice, and the type that owns the memory. Assigning to it evaluates an expression across every site; passing it into one makes it a leaf.
field.h · ctest -R test-field
Vocabulary
Everything you can write in a TempLat expression.
TempLat expressions are built from a small set of nouns and a large set of verbs: field types that own memory, containers that bundle them under one index, and an algebra of operations that turns them into lightweight expression trees. Nothing below is evaluated until it is assigned to a field.
This page is generated from the headers in include/TempLat/. Each entry
links to the source it was read from and to the test that exercises it. To regenerate after changing the
library, run python3 tools/docgen/gen_vocabulary.py --write.
Field types
The types that own memory.
Every one of these is constructed from a name tag and a
MemoryToolBox, holds a shared reference to a MemoryBlock on the device, and is
cheap to copy — which is what lets it appear as a leaf of an expression tree. Assigning to one triggers
evaluation across the whole lattice.
ComplexField
ComplexField<T, NDim> psi("psi", toolBox);
A complex scalar field, stored as two real components.
complexfield.h · ctest -R test-complexfield
U1Field
U1Field<T, NDim> u("u", toolBox);
A single $U(1)$ link $U_i = e^{\mathrm{i} A_i}$ for fixed $i$. An alias of ComplexField, because a $U(1)$ group element is a unit-modulus complex number: the group product is complex multiplication and the inverse is conj().
u1field.h · ctest -R test-u1field
SU2Field
SU2Field<T, NDim> U("U", toolBox);
A single $SU(2)$ link $U_i$ for fixed $i$, held as four reals $c_0\dots c_3$ with $U = c_0\mathbb{1} + i\,c_a\sigma_a$ and $\sum_a c_a^2 = 1$. unitarize() restores the constraint after accumulated rounding.
su2field.h · ctest -R test-su2field
SU2LieAlgebraField
SU2LieAlgebraField<T, NDim> E("E", toolBox);
An $\mathfrak{su}(2)$ field: the same storage as the group type but with $c_0$ pinned to zero, and component access normalised to $\sigma_a/2$.
su2liealgebrafield.h · ctest -R test-su2liealgebrafield
SU2Doublet
SU2Doublet<T, NDim> phi("phi", toolBox);
An $SU(2)$ (Higgs) doublet: two complex components, stored as four reals.
su2doublet.h · ctest -R test-su2doublet
SymTracelessField
SymTracelessField<T, NDim> hij("hij", toolBox);
A real symmetric traceless $3\times3$ matrix field, stored as its five independent components. The type used for gravitational waves.
symtracelessfield.h · ctest -R test-symtracelessfield
Containers
Bundling fields under one index.
Containers give a collection of fields a single tag-indexed name — the natural shape for
gauge links $U_\mu$ and for multiplets. They nest, so a collection of vector fields is just as ordinary as a
vector of scalars. The constructors below build composite expressions rather than storage: an entry
set to ZeroType is pruned from the tree at compile time.
VectorField
VectorField<FieldType> Us("Us", toolBox);
A vector-valued field — one component per spatial dimension, indexed from 1. The natural type for a gauge link $U_\mu$.
vectorfield.h · ctest -R test-vectorfield3d
FieldCollection
FieldCollection<FieldType, N> coll("coll", toolBox);
$N$ fields of any one type under a single tag-indexed name.
fieldcollection.h · ctest -R test-fieldcollection
VectorFieldCollection
VectorFieldCollection<FieldType, N> Ws("Ws", toolBox);
$N$ vector fields under one name; the two containers nest, as for a collection of gauge fields.
vectorfieldcollection.h · ctest -R test-vectorfieldcollection
Constructors
CField
CField(re, im)
Bundles two existing real Fields into one complex field, sharing their memory rather than copying it.
Complexify
Complexify(re, im)
Builds a complex expression from a real and an imaginary expression. Lightweight: it stores nothing and owns no memory.
SU2Wrap
SU2Wrap(c0, c1, c2, c3) SU2Wrap(f)
Builds an SU(2)-valued expression from four component expressions, or from a lambda of the component tag. Nothing is stored: the result is a leaf in the expression tree.
SU2DoubletWrap
SU2DoubletWrap(a, b, c, d) SU2DoubletWrap(f)
Builds a doublet expression from four component expressions, or from a lambda of the component tag.
ConstructMatrix3x3
ConstructMatrix3x3(m11, m12, m13, m21, m22, m23, m31, m32, m33)
Builds a general $3\times3$ matrix expression, given row by row. Entries set to ZeroType are pruned from the tree at compile time.
ConstructSym
ConstructSym(s11, s12, s13, s22, s23, s33)
Builds a symmetric $3\times3$ matrix expression from its upper triangle.
ConstructHerm
ConstructHerm(h11, h12, h13, h22, h23, h33)
Builds a hermitian $3\times3$ matrix expression from its upper triangle; the lower triangle is the conjugate.
ConstructSymTraceless
ConstructSymTraceless(t11, t12, t13, t22, t23, t33)
Builds a symmetric $3\times3$ expression whose trace is subtracted on evaluation, so the result is traceless by construction.
MakeVector
MakeVector(i, beg, end, expr)
Builds a vector expression by instantiating `expr` once for each index in $[beg, end]$, with `i` bound to a compile-time tag.
auto Bs = MakeVector(i, 1, 3, magneticField(As, i));
MakeArray
MakeArray(i, beg, end, expr)
Like MakeVector, but produces a plain tuple rather than a vector expression.
MakeSU2
MakeSU2(a, expr)
Builds an SU(2) expression whose component `a` is the given expression, written once and instantiated for $a=0\dots3$.
MakeSU2Doublet
MakeSU2Doublet(a, expr)
Builds a doublet expression whose component `a` is the given expression.
Operations
The expression algebra.
Filter by the field or container types that take part in an operation. Tags come from the
C++20 requires clause that constrains each factory, so they say exactly what the compiler will
accept. Operations defined for several algebras — shift, dagger,
operator* — appear once, carrying every type they work on.
operator+
a + b
Element-wise sum. Every algebra defines its own, so the operands may be numbers, scalar or complex fields, SU(2) elements, doublets, 3x3 matrices or collections.
complexfieldadd.h · listadd.h · symtracelessadd.h · add.h · su2doubletsum.h · su2sum.h · radialprojectionresult.h · unbinnedradialprojectionresult.h
operator-
a - b -a
Element-wise difference; the unary form negates. Defined for every algebra.
complexfieldsubtract.h · listsubtract.h · listunaryminus.h · symtracelesssubtract.h · subtract.h · unaryminus.h · su2doubletsubtract.h · su2subtract.h
operator*
a * b
Product of two expressions. The meaning follows the operands: numbers and fields multiply point-wise, SU(2) elements compose as quaternions, matrices contract, collections multiply component-wise.
complexfieldmultiply.h · scalarcomplexmultiply.h · listmultiply.h · hermsymtracelessmultiply.h · matrixmatrixmultiply.h · scalarsymtracelessmultiply.h · symsymtracelessmultiply.h · multiply.h · complexfieldsu2doubletmultiply.h · scalarsu2multiplication.h · su2multiply.h · su2su2doubletmultiply.h · radialprojectionresult.h · unbinnedradialprojectionresult.h
operator/
a / b
Element-wise division.
scalarcomplexmultiply.h · listdivide.h · scalarsymtracelessmultiply.h · divide.h · complexfieldsu2doubletmultiply.h
abs
abs(r)
Absolute value, element-wise.
acos
acos(a)
Arc cosine, element-wise.
arg
arg(t) arg(r, t)
Phase of a complex field, in $(-\pi, \pi]$.
arg2
arg2(y, x)
Two-argument arc tangent $\mathrm{atan2}(y, x)$, giving a phase in $(-\pi, \pi]$.
asComplexField
asComplexField(r)
Reinterprets an expression whose eval() already returns a complex value as a complex field, so the complex algebra applies to it.
asFourier
asFourier(r)
Views a complex field as living in Fourier space, so that assignments and reductions on it are taken over momentum modes.
asinh
asinh(a)
Inverse hyperbolic sine, element-wise.
average
average(expr) average(expr, space)
Average of an expression over the whole lattice and across all MPI ranks. Defaults to configuration or Fourier space according to the operand.
B4NA
B4NA(Us, i)
Non-abelian magnetic field component $B_i$ from the clover field strength.
backDiff
backDiff(expr, mu)
Backward finite difference $\big(f(x) - f(x-\hat e_\mu)\big)/dx$ along direction `mu`.
BackwardCovariantDerivative
BackwardCovariantDerivative<dim>(Us..., scalar)
Backward gauge-covariant derivative of a scalar: the backward difference with the scalar parallel-transported by the daggered link. Takes any number of gauge vectors followed by the scalar, so a field charged under several groups is written in one call.
backwardcovariantderivative.h · ctest -R test-backwardcovariantderivative
CenteredCovariantDerivative
CenteredCovariantDerivative<dim>(Us..., scalar)
Centred gauge-covariant derivative, accurate to $O(dx^2)$. Takes the gauge vectors followed by the scalar.
centeredcovariantderivative.h · ctest -R test-centeredcovariantderivative
CenteredCovariantDerivativeO4
CenteredCovariantDerivativeO4<dim>(Us..., scalar)
Centred gauge-covariant derivative on a five-point stencil, accurate to $O(dx^4)$.
centeredcovariantderivativeo4.h · ctest -R test-centeredcovariantderivativeo4
CenteredDerivative
CenteredDerivative(t)
The ungauged centred derivative — CenteredCovariantDerivative with no links.
CenteredDerivativeO4
CenteredDerivativeO4(t)
The ungauged $O(dx^4)$ centred derivative.
commutator
commutator(r, t)
Commutator $[A,B] = AB - BA$ of two SU(2)-valued expressions.
complexfieldaverage
complexfieldaverage(instance, Configuration)
Lattice average of a complex expression, returning a complex result.
complexPhase
complexPhase(r)
Exponential map for $U(1)$: turns a real phase $\theta$ into the unit-modulus complex number $e^{i\theta}$.
conj
conj(r)
Complex conjugate, element-wise. Excluded for complex field types (HasComplexFieldGet) which have their own conj overload.
complexfieldconjugate.h · listcomplexconjugate.h · symtracelessconjugate.h · complexconjugate.h
cos
cos(a)
Cosine, element-wise.
cosh
cosh(a)
Hyperbolic cosine, element-wise.
dag
dag(r)
Short spelling of dagger.
dagger
dagger(r)
Hermitian conjugate. For SU(2) it negates the three vector components; the operator factory also simplifies as it builds, collapsing $(A^\dagger)^\dagger$ to $A$ and commuting past a shift.
derivatives
derivatives(expr, others)
Symbolic derivative of an expression with respect to each field in a collection, returned as a tuple. Provided for completeness; nothing in TempLat uses it.
DiracDelta
DiracDelta(a)
Discrete Dirac delta: the largest representable value where the operand is exactly zero, and zero elsewhere. Exists so that the derivative of heaviside has a name; it is not a distribution you can integrate.
dot
dot(r, t)
Dot product of two vector expressions, $\sum_i a_i b_i$.
electricField2
electricField2(Es) electricField2(Es, i)
Site-centred electric field: the average of the two links straddling a site in each direction. Returns a vector expression when called without an index.
exp
exp(r)
Exponential $e^x$, element-wise.
expinv
expinv(r)
Inverse of the SU(2) exponential map — the logarithm, taking a group element back to the algebra.
fieldStrength
fieldStrength(As, mu, nu)
Abelian field strength $F_{\mu\nu} = \partial_\mu A_\nu - \partial_\nu A_\mu$ from forward differences of the gauge potential.
fieldStrengthCtr
fieldStrengthCtr(As, mu, nu)
Field strength built from centred rather than forward differences.
ForLoop
ForLoop(i, beg, end, expr)
Runs `expr` once per index in a compile-time range, for side effects rather than a value.
forwDiff
forwDiff(expr, mu)
Forward finite difference $\big(f(x+\hat e_\mu) - f(x)\big)/dx$ along direction `mu`.
forwDij
forwDij<dir>(expr)
Forward two-point *sum* $\big(f(x) + f(x+\hat e_\mu)\big)/dx$ — the averaging counterpart of forwDiff, used where a gauge-covariant discretisation needs the sum rather than the difference.
Grad2
Grad2(pR)
Squared norm of the forward gradient, $(\nabla\phi)^2$ — the gradient energy term, as one fused expression.
HalfType
HalfType
Compile-time one half, so that sqrt can be written as an exact power.
halftype.h · ctest -R test-halftype
heaviside
heaviside(r)
Heaviside step function, with the convention $H(0)=1$. Its symbolic derivative is DiracDelta.
If
If(condition, ifExpr)
Compile-time branch whose untaken side is ZeroType, so it prunes out of the tree entirely.
IfElse
IfElse(condition, ifExpr, elseExpr)
Compile-time branch inside an expression: only the taken side is instantiated.
Imag
Imag(t)
Imaginary part of a complex field or complex number.
imag.h · ctest -R test-imag
LatForwardGrad
LatForwardGrad(pR)
Forward gradient, as a vector expression with one forwDiff component per dimension.
LatLapl
LatLapl(expr)
Lattice Laplacian: the standard $2d+1$-point stencil, using the operand's own $dx$. Applied component-wise to a collection.
log
log(r)
Natural logarithm, element-wise.
magneticField
magneticField(As, t) magneticField(As)
Magnetic field from the gauge potential, $B_i = \tfrac12\epsilon_{ijk}F_{jk}$. Specialised to three dimensions.
magneticField4
magneticField4(Bs) magneticField4(Bs, i)
Site-centred magnetic field: the average over the four plaquettes around a site in each direction. Specialised to three dimensions.
magneticFieldCtr
magneticFieldCtr(As, t) magneticFieldCtr(As)
Magnetic field from centred differences of the gauge potential.
max
max(instance, Configuration)
Largest value an expression takes anywhere on the lattice, reduced across all ranks.
MomentumInterpolator
MomentumInterpolator<T, NDim>
Evaluates a tabulated function of $|k|$ at every Fourier site, cubic-spline interpolated and clamped outside the table. The usual way to impose a prescribed initial power spectrum.
MomentumMultiplicity
MomentumMultiplicity<T, NDim>
How many modes share the $|k|$ of the current Fourier site — the weight a correctly normalised spectrum needs.
momentummultiplicity.h · ctest -R test-momentummultiplicity
multiplyTrace
multiplyTrace(a, b)
Trace of the product of two $3\times3$ matrix expressions, $\mathrm{tr}(AB)$, evaluated without ever forming the product.
hermsymtracelessmultiplytrace.h · matrixmatrixmultiplytrace.h · symsymtracelessmultiplytrace.h
neutDiff
neutDiff(expr, mu)
Centred finite difference $\big(f(x+\hat e_\mu) - f(x-\hat e_\mu)\big)/2dx$, accurate to $O(dx^2)$.
neutDij
neutDij<dir>(expr)
Centred two-point sum $\big(f(x+\hat e_\mu) + f(x-\hat e_\mu)\big)/2dx$, the averaging counterpart of neutDiff.
nonabelianclover
nonabelianclover(Us, mu, nu)
Clover discretisation of the non-abelian field strength: the average of the four plaquettes touching a site in the $(\mu,\nu)$ plane, which restores the symmetry a single plaquette breaks.
norm
norm(r)
Euclidean norm of a vector expression, `sqrt(norm2(v))`.
norm2
norm2(r)
Squared norm: the sum of the squares of the components. Defined for collections, complex fields and doublets.
complexfieldmultiply.h · norm.h · vectordotter.h · su2doubletdotter.h · ctest -R test-norm
Number
Number<T>
A runtime-mutable scalar that takes part in expressions: change its value and every expression holding it sees the new one, without rebuilding the tree.
number.h · ctest -R test-number
OneType
OneType
Compile-time one. Multiplying by it returns the operand unchanged.
onetype.h · ctest -R test-zerotype
plaq
plaq(Us, mu, nu)
Plaquette $P_{\mu\nu}(x) = U_\mu(x)\,U_\nu(x+\hat\mu)\,U^\dagger_\mu(x+\hat\nu)\,U^\dagger_\nu(x)$. The product is deliberately bracketed in pairs: fully expanding a chain of six or more link matrices overflows the stack.
plaquette.h · ctest -R test-plaquette
plaqBack
plaqBack(Us, mu, nu)
The plaquette traversed backwards in $\nu$, needed alongside plaq when assembling equations of motion.
plaquetteback.h · ctest -R test-plaquetteback
pow
pow<N>(x) pow(x, y)
Raises an expression to a power. $x^N$ with a compile-time exponent unrolls into repeated multiplication; the two-argument form is general. $N=0$ folds to OneType and $N=1$ to the operand itself, at compile time.
projectRadially
projectRadially(instance, spaceType, pToolBox, false) projectRadially(instance, false)
Bins an expression by radius, giving a radial profile of an $N$-dimensional lattice.
projectRadiallyFourier
projectRadiallyFourier(instance, false)
Bins an expression by $|k|$, the usual way to take a power spectrum.
RandomGaussianField
RandomGaussianField<T, NDim>
Gaussian random field generated directly in Fourier space.
RandomGaussianFieldConfig
RandomGaussianFieldConfig<T, NDim>
Gaussian random field in configuration space: an independent normal draw per site. The counter-based generator makes each site independent of every other, so results are identical whatever the decomposition. the target spectrum is flat -- for a specific P(k), assign in Fourier space instead.
RandomRayleighField
RandomRayleighField<T, NDim>
Fourier-space field with Rayleigh-distributed amplitude and uniform random phase.
RandomUniformUnitaryField
RandomUniformUnitaryField<T, NDim>
Fourier-space field of unit modulus with uniformly random phase.
Real
Real(t)
Real part of a complex field or complex number.
real.h · ctest -R test-real
safeDivide
safeDivide(numerator, denominator)
Division that yields exactly zero where the numerator does, instead of evaluating 0/0. Written for normalising spectra against a cutoff.
safeSqrt
safeSqrt(r)
Square root that clamps a negative argument to zero, for quantities that are positive up to rounding.
scalar_prod
scalar_prod(r, t)
Scalar product of two SU(2) doublets.
shift
shift(expr, mu) shift<i,j,k>(expr)
Reads an expression at a site offset by a constant lattice vector: `shift(phi, 1_c)` is $\phi(x+\hat e_1)$. Every finite-difference operator is built from it, and it is what tells TempLat which ghost cells to exchange.
auto p = (Us(mu) * shift(Us(nu), mu)) * dagger(shift(Us(mu), nu)) * dagger(Us(nu));
complexfieldshift.h · listshift.h · symtracelessfieldshift.h · shift.h · su2doubletshift.h · su2shift.h
sin
sin(a)
Sine, element-wise.
sinh
sinh(a)
Hyperbolic sine, element-wise.
SpatialCoordinate
SpatialCoordinate<NDim>
The position of the current site, as an expression. Throws if evaluated in Fourier space.
spatialcoordinate.h · ctest -R test-spatialcoordinate
sqrt
sqrt(r)
Square root, built as $x^{1/2}$ so the expression stays symbolically differentiable.
su2average
su2average(instance, Configuration)
Lattice average of an SU(2)-valued expression, aware of cached link operations.
su2dotter
su2dotter(r, t)
Lie-algebra inner product $\langle A,B\rangle = \sum_{a=1}^{3} A_a B_a$, evaluated in one fused pass rather than by building three component expressions.
su2doubletaverage
su2doubletaverage(instance, Configuration)
Lattice average of an SU(2) doublet expression.
SU2GroupWrap
SU2GroupWrap(c1, c2, c3)
Builds a genuine group element from three components, recovering $c_0$ from the unitarity constraint $c_0^2+c_1^2+c_2^2+c_3^2=1$ so that $\det U = 1$ holds by construction.
symTracelessFieldAsFourier
symTracelessFieldAsFourier(r)
Views a symmetric-traceless field in Fourier space.
tanh
tanh(a)
Hyperbolic tangent, element-wise.
toSU2
toSU2(r)
Projects an SU(2)-valued expression onto the group by rebuilding it from its three vector components.
total
total(tup) total(tup, f)
Sums every component of a tuple-like expression, optionally applying a function to each first. Reduces over the components, not over the lattice.
total.h · ctest -R test-total
Total
Total(i, beg, end, expr)
Sums `expr` over a compile-time index range — the expression-level $\sum_i$.
auto S = Total(mu, 1, NDim, Total(nu, 1, NDim, trace(plaq(Us, mu, nu))));
trace
trace(r)
Trace of an SU(2) matrix, $\mathrm{tr}\,U = 2c_0$ in the four-real-component representation.
su2trace.h · ctest -R test-su2trace
wallAverager
wallAverager(instance, Configuration)
Averages over the first $d-1$ coordinates, leaving a profile along the last one.
WaveNumber
WaveNumber<NDim>
The Fourier coordinate of the current site, as an expression. Exposes the individual components and `norm()` / `norm2()`. Throws if evaluated in configuration space.
wavenumber.h · ctest -R test-wavenumber
ZeroType
ZeroType
Compile-time zero. Multiplying by it collapses a whole expression tree to nothing, and adding it is free — this is how TempLat prunes terms before generating any code.
zerotype.h · ctest -R test-zerotype