Conventions
Which build this describes
The reference build is qlua/2026.10d, configured with AFF, HDF5, GSL, CBLAS/LAPACK, ARPACK, the Clover, Twisted and Möbius domain-wall Level III libraries, QOPQDP's Wilson multigrid, the extras contraction package, and colors 2, 3 and N. QUDA and Grid are not in it; what they would add is in Optional back ends and marked as such.
Nothing here is promised of a build older than 2026.10d. Two sets of changes are recent enough to name:
New in 2026.10d. The sequential color types gained set_zero and zero_like; the sequential ColorMatrix gained det, log, sqrt and inverse; qcd.quarkContract12 through 34 began accepting sequential propagators; and qcd.dot began accepting two complex numbers. Before that release the sequential types were a strictly smaller algebra than their lattice twins.
After the 2026.10d tag. Five further changes are in the sources this manual was written against but not in the 2026.10d binary:
| What | Before |
|---|
set and set_zero return the receiver | set returned its argument, set_zero returned nothing on the color types | qcd.DiracPropagatorN(nc, m) builds a propagator | it returned m itself | L:DiracPropagatorN(nc, M) works | it raised "bad DiracPropagator constructor" | qcd.qdpcc.write_prop and qcd.ddpairs.write take volfmt as optional | omitting it raised "string expected, got userdata" | type() names twisted, scatter, gather, latmat, contraction-state and file objects | it answered "userdata" for those six |
A script that must run against an older build can test for a method before using it, but it has to do so without calling it: an unknown method name raises rather than returning nil, and on a parallel job that raise takes the whole job down. The idiom is to ask the metatable, collectively, once:
if not pcall(function() return qcd.ColorVectorN(3).set_zero end) then
error("this script needs qlua/2026.10d or later")
end
Ranks and sites
Two words are used throughout in one sense each, and they are easy to confuse because both are positions.
A rank is a process: one of the parallel jobs the launcher started, at its own place in the network of processes. os.node() and qcd.node() give the calling rank's number, qcd.network() says how many there are and how they are wired, and L:network() gives the shape of the process grid the lattice was laid out on. Every rank runs the whole script.
A site is a point of the lattice: a position in the physical volume, named by a coordinate list such as {3, 0, 1, 12} with one entry per axis, each counted from 0. A lattice field holds one value per site. L:volume() is how many sites there are, and L:pcoord(mu) is the field whose value at each site is that site's own coordinate along axis mu.
The sites are divided among the ranks — that is what makes the job parallel — but which rank owns which site is the layout's business, not a script's. A field operation covers the whole lattice however the sites fall.
This manual never calls the number of a lattice's dimensions its "rank", although QDP does: #L is the number of dimensions, and rank is kept for processes.
Notation
An argument's name says its type. A capital letter is a lattice field, the matching small letter the single-site value of the same kind.
| Lattice field | Single-site value |
|---|
| integer | I | a plain Lua number | | real | R | a plain Lua number | | complex | C | z | | color vector | V | v | | color matrix | M | m | | Dirac fermion | D | d | | Dirac propagator | P | p |
Where a method takes a second value of the same type as its receiver, the second is the same letter with a 2: I:and(I2), R:min(R2), C:project(C2, ms). F stands for a field whose type does not matter to the statement being made, and F2 for a second one of the same type.
The other recurring names:
| Name | What it is |
|---|
L | a lattice | U | a gauge field: a list of #L lattice ColorMatrix fields, indexed from 1 | S, s | a lattice random state, a sequential one | sub | a subset | ms | a multiset | g | a gamma | f | a file | r, w | a reader, a writer | CL, TW, DW, mg | a Clover, Twisted, MDWF or Wilson-multigrid solver object | df | a deflator | mu, nu | an axis, counted from 0 | nc | a number of colors | t_axis | the axis that is time, counted from 0 |
In a call shape, [x] marks an optional argument and --> introduces what the call returns. Several names after --> mean several return values, in order. Indices into color and spin spaces are written as a table — V[{c=1}], M[{a=0,b=2}], P[{c=1,d=3}] — and every one of them counts from 0.
|
