iblep-disc-burgershort

graph LR
  %%%%%%%%%%%%%%%%%%%%%%%
  %% Highlight definition
  %%%%%%%%%%%%%%%%%%%%%%%
  classDef highlight fill:#083008,stroke:#20B030,stroke-width:4px
  %%%%%%%%%%%%%%%%%%%%%%%
  %% Graph
  %%%%%%%%%%%%%%%%%%%%%%%
  iblep-disc-loops -->|Propagators| iblep-disc-burgershort;
  iblep-disc-loops -.->|Tadpoles| iblep-conn-lep;
  iblep-disc-loops -.->|Tadpoles| iblep-conn-omega;
  iblep-disc-burgerlong;
  iblep-conn-emfieldft;
  iblep-real-fixgauge -->|Gauge field| iblep-real-props;
  iblep-real-props -->|Propagators| iblep-real-threept;


class iblep-disc-burgershort highlight
  %%%%%%%%%%%%%%%%%%%%%%%
  %% Interaction
  %%%%%%%%%%%%%%%%%%%%%%%
  click iblep-disc-loops "../../../workflows/disc/iblep-disc-loops/";
  click iblep-disc-burgershort "../../../workflows/disc/iblep-disc-burgershort/";
  click iblep-disc-burgerlong "../../../workflows/disc/iblep-disc-burgerlong/";
  click iblep-conn-lep "../../../workflows/conn/iblep-conn-lep/";
  click iblep-conn-omega "../../../workflows/conn/iblep-conn-omega/";
  click iblep-conn-emfieldft "../../../workflows/conn/iblep-conn-emfieldft/";
  click iblep-real-fixgauge "../../../workflows/real/iblep-real-fixgauge/";
  click iblep-real-props "../../../workflows/real/iblep-real-props/";
  click iblep-real-threept "../../../workflows/real/iblep-real-threept/";

iblep-disc-burgershort computes short-distance Burger contractions from stochastic propagators produced by iblep-disc-loops. This diagram is a single number, formed by taking the coordinate sum over both vertex insertions in the diagram.

The workflow computes a volume-average for each contribution with a separation $r$ between the vector insertions, where $r$ is within (and on) a 4D sphere of radius $R$. This is a high-statistics estimator of the dominant short-distance contribution to the burger diagram. For a description of this strategy, see https://arxiv.org/abs/2301.03995.

In the continuum, the burger diagram is radially symmetric in $r$. On the lattice, this breaks down to (at most) a 4D octahedral symmetry. Typically a sufficient distinction will be made between the spatial and temporal directions that only a 3D spatial octahedral symmetry and Z2 time symmetry is available. The remaining symmetry is broken to an approximate symmetry by the use of stochastic noise for the propagators. This workflow therefore allows you to accelerate the contraction at a slight cost in statistics by specifying a 'symmetry' scheme for the contraction, which will cause $r$s that are redundant (in the absence of noise) under the selected scheme to be dropped from the contraction. Since the contraction costs is linear in the number of $r$, this can produce highly significant speedups (see Workflow).

The $r$ loop is deliberately the outer loop and the hit loop the inner loop. This keeps the number of live propagator-sized fields bounded by the number of $r$ assigned to a job, rather than by the total number of stochastic hits.

Inputs and outputs

Inputs

Per-hit stochastic propagators from iblep-disc-loops, stored under paths.props.
The same lattice geometry, setup, flavour, and AMA-stage conventions used when those propagators were generated.
A set of radial shells with one of the supported symmetry reductions: none, parity, orthant, oct3d, or oct4d.
One or both supported photon discretisations: L (QED_L) and r (QED_r).

Outputs

Files: A burgershort result group containing one dataset for each selected $r$ and hit.
Database: burgershort_symmetries rows describing the generated symmetry-reduced $r$ and their multiplicity factors.
Database: burgershort_data rows mapping each $r$/hit contraction to its result file and dataset.
XML: Hadrons result metadata describing the exported flavour and hit range.
An optional XML module graph at paths.xml/<runId>.xml.

Workflow

The workflow performs the contraction in sequential "shells" of radius $|r|^2$ up to (and including) the specified limit $R$. The workflow generates the $r$s using the selected symmetry class for each shell, and performs the contraction only for the subrange of $r$ beginning at sites.siteStart with length sites.siteStep.

Note

Each $r$ (or 'site') in the specified range implies storage of a propagator-sized field in memory. You must therefore be careful not to specify too many sites for the contraction, which will cause a host out-of-memory error. Since only a subset of the total $r$ are computed, you must run the workflow multiple times at different ranges until you exhaust the list of $r$ for your selected range of shells.

This is a trade-off between memory and I/O time. The more $r$ you can fit into a job, the fewer times you must run the workflow, and therefore the fewer times you must stream the large propagator fields from disk.

For every selected site and every hit from 0 through hits - 1, it:

Loads the corresponding stochastic propagator from paths.props.
Reconstructs the noise field. debug uses deterministic seeded noise; unit-test loads a saved noise field.
Performs the contraction for the selected $r$ for every requested photon discretisation.
Supplies the previous hit's two summed propagator outputs to the next hit, allowing the contraction to accumulate the stochastic estimator.

Warning

Since the noises are reconstructed to save disk space and I/O bandwidth, you MUST run the iblep-disc-burgershort workflow with the SAME runId as the iblep-disc-loops workflow that generated the loops.

The site generators are constructed for a four-dimensional lattice. The available symmetry choices are:

Name	Meaning
`none`	Keep every site in the requested radial shell.
`parity`	Cull sites related by parity symmetry, $ r \to -r$
`orthant`	Cull sites related by orthant symmetry.
`oct3d`	Cull sites related by 3D spatial octahedral symmetry and Z2 time symmetry.
`oct4d`	Cull sites related by 4D space-time octahedral symmetry .

Tip

You can select a different symmetry scheme for each "shell" of radius $|r|^2$. This allows you to, for example, use a less aggressive symmetry-reduction for extremely small radii (where the reduction drops fewer sites) and more aggressive at larger radii (where there are very large numbers of redundant sites).

A summary of $r$ counts under different symmetry schemes is given in the table below.

Method	Radius: 0	1	2	3	4	5	6	7	8
Full	1	9	89	425	1281	3121	6577	11833	20185
Parity	1	5	45	213	641	1561	3289	5917	10093
Orthant	1	5	20	70	165	357	688	1154	1867
$H_3 \times Z_2$	1	3	10	25	52	102	183	291	451
$H_4$	1	2	6	12	23	41	70	106	159

Tip

The parity symmetry scheme is an exact symmetry, even for stochastic propagators. This makes it a free factor 2 speedup in the contraction for zero loss in statistics.

The burger diagram uses the same biased-estimator optimisation as iblep-disc-loops. Therefore, you must perform the same bias-subtraction process as described on that page.

From datasets to physics

The exact contraction performed for one displacement is defined by QEDBurgerShortPoint in the Hadrons documentation. Neither bias subtraction nor hit normalisation has been applied.

For hit $i$, displacement $r$, flavour $f$, and photon prescription $a$, let $b_{f,i}^{(a)}(r)$ be the burgerSingle member. With $\phi_{f,i}=S_f\eta_i$, it is

\[ b_{f,i}^{(a)}(r) =-G_{\mu\mu,a}(r)\sum_{x,\mu}\operatorname{tr}_{s,c}\!\left[ \gamma_\mu \phi_{f,i}(x+r)\eta_i^\dagger(x) \gamma_\mu \phi_{f,i}(x)\eta_i^\dagger(x+r) \right]. \]

The minus sign is the implemented $i^2=-1$ from the two electromagnetic insertions. The burgerSummed member in the dataset for hit $N-1$ instead contains every ordered noise pair:

\[ F_{f,N}^{(a)}(r) =\sum_{i,j=0}^{N-1}b_{f,ij}^{(a)}(r). \]

Consequently, for each stored representative site, the unbiased estimator is

\[ \boxed{ \widehat B_{f,\mathrm{short}}^{(a)}(r;N) =\frac{ \texttt{burgerSummed}_{N-1}(r) -\displaystyle\sum_{i=0}^{N-1}\texttt{burgerSingle}_{i}(r) }{N(N-1)}} \qquad (N\geq2). \]

Here the suffix on the dataset name is a zero-based hit index, whereas the burgershort_data.hits column is the one-based count $N$. All terms in this equation must have the same trajectory, flavour, AMA stage, photon prescription, and displacement.

The complete short-distance piece is $$ B_{f,\mathrm{short}}^{(a)}(R;N) =\sum_{r}m(r)\, \widehat B_{f,\mathrm{short}}^{(a)}(r;N), $$ where $m(r)$ is the combinatoric factor pre-calculated per-displacement in the burgershort_symmetries table, using the symmetry selected for its shell. When performing this sum, you should select the set of displacements corresponding to a particular symmetry scheme from the burgershort_symmetries table, and use this to identify which elements of the dataset to sum (with the corresponding combinatoric factor).

The output does not contain $e^2$, the quark charge, or local-current renormalisation. Since both vector insertions lie on the same flavour line, the physical short-distance term is

\[ B_{f,\mathrm{short,phys}}^{(a)}(R) =e^2 Q_f^2\left(Z_V^f\right)^2 B_{f,\mathrm{short}}^{(a)}(R). \]

Apply the AMA combination before multiplying by these common physical factors. To obtain the full Burger diagram, combine this result with the Burger-long estimator at the identical $R^2$, photon prescription, flavour and AMA stage, as described on the iblep-disc-burgerlong page.

Run

iblep-disc-burgershort <parameter-file.json> [Grid options]

The executable uses Hadrons' naive scheduler. traj.start, traj.end, and traj.step are passed directly to the Hadrons trajectory counter.

Set dryRun to true to construct the module graph and generate result metadata without executing the contractions.

Input JSON

The following is an example input JSON copied from iblep/parameters/iblep-disc/debug/burgershort.debug.json:

{
  "setup": "debug",
  "runId": "ibdisc",
  "AMAstage": "inexact",
  "flavour": "l",
  "dryRun": false,
  "traj": { "start": 0, "step": 20, "end": 20 },
  "hits": 8,
  "paths": {
    "results": "data/results",
    "props": "data/props",
    "resultDb": "data/result.db",
    "xml": "log/loops.0",
    "gauge": "",
    "gaugeTransform": "",
    "eigenpack": "",
    "statDb": "db/ibdisc-burgershort-debug.0",
    "appDb": "db/ibdisc-burgershort-debug.0"
  },
  "sites": {
    "shells": [
      { "symmetry": "parity", "rSqMin": 0, "rSqMax": 2 },
      { "symmetry": "orthant", "rSqMin": 2, "rSqMax": 4 }
    ],
    "siteStart": 0,
    "siteStep": 100
  },
  "qed": ["L", "r"]
}

Field	Type	Required	Meaning and constraints
`setup`	string	Yes	Solver and gauge setup. This example uses `debug`; production setups use a RBC/UKQCD gauge ensemble name.
`AMAstage`	string	Yes	AMA solver stage supported by `setup`: `inexact` or `exact`.
`runId`	string	Yes	Hadrons run identifier and XML filename component.
`flavour`	string	Yes	Flavour of the input propagator: `l`, `s`, or `c`.
`dryRun`	boolean	Yes	Build XML without execution when `true`.
`traj.start`, `traj.end`, `traj.step`	unsigned integer	Yes	Inclusive trajectory range and increment passed to Hadrons.
`hits`	unsigned integer	Yes	Number of stochastic propagator hits to process.
`paths.results`	path	Yes	Root directory for burger-short result groups.
`paths.props`	path	Yes	Root directory containing per-hit propagators from `iblep-disc-loops`.
`paths.resultDb`	path	Yes	Result-database path.
`paths.appDb`, `paths.statDb`	path	Yes	Hadrons application and statistics database paths.
`paths.xml`	path	Optional	Directory for the saved Hadrons module graph.
`paths.gauge`, `paths.gaugeTransform`, `paths.eigenpack`	path	Setup-dependent	Retained for shared disconnected parameter conventions; this workflow loads propagators rather than constructing sea solvers.
`sites.shells`	object array	Yes	Consecutive radial-shell ranges and symmetry generators.
`sites.shells[].symmetry`	string	Yes	One of `none`, `parity`, `orthant`, `oct3d`, or `oct4d`.
`sites.shells[].rSqMin`, `rSqMax`	unsigned integer	Yes	Half-open radial-shell range. Each shell must start at the previous shell's `rSqMax`, or the programme will exit with an error.
`sites.siteStart`, `sites.siteStep`	unsigned integer	Yes	Subrange of generated sites to contract over in this job.
`qed`	string array	Yes	Photon discretisation: `L`, `r`, or both.

The available setups are:

Key	Meaning
`debug`	A debug configuration .
`unit-test`	A debug configuration.
`RBCUKQCD-C0ZMobiusLCD`	RBC/UKQCD C0 ensemble with ZMobius light quarks with Local Coherence deflation.
`RBCUKQCD-C0MADWFLCD`	RBC/UKQCD C0 ensemble with Mobius light quarks with Local Coherence deflation via MADWF solves.
`RBCUKQCD-C0LLCD`	RBC/UKQCD C0L ensemble with light quarks with Local Coherence deflation.
`RBCUKQCD-M0LCD`	RBC/UKQCD M0 ensemble with light quarks with Local Coherence deflation.
`RBCUKQCD-C1MIRL`	RBC/UKQCD C1M ensemble with online deflation of light quarks.
`RBCUKQCD-C1M16IRL`	RBC/UKQCD C1M16 ensemble with online deflation of light quarks.
`RBCUKQCD-C1M20IRL`	RBC/UKQCD C1M20 ensemble with online deflation of light quarks.
`RBCUKQCD-C1M32IRL`	RBC/UKQCD C1M32 ensemble with online deflation of light quarks.
`JLQCD-fUd3Sa`	JLQCD fUd3Sa ensemble with a fine lattice spacing.
`JLQCD-fUd3Sa`	JLQCD mUd3Sa ensemble with a medium lattice spacing.
`JLQCD-fUd3Sa`	JLQCD mUd3Sb ensemble with a medium lattice spacing.
`JLQCD-fUd3Sa`	JLQCD cUd2Sa ensemble with a coarse lattice spacing.
`JLQCD-fUd3Sa`	JLQCD cUd2SaL ensemble with a coarse lattice spacing.
`JLQCD-fUd3Sa`	JLQCD cUd3Sa ensemble with a coarse lattice spacing.
`JLQCD-fUd3Sa`	JLQCD cUd3Sb ensemble with a coarse lattice spacing.

Output and data format

Propagator inputs

For trajectory T and AMA stage A, each input propagator is loaded from the standard disconnected subdirectory:

<paths.props>/<T>/<A>/prop_<flavour>_<hit>

The iblep-disc-loops workflow is responsible for creating these files. The hit index is zero-based in the module names and filenames.

HDF5 result group

The exported result stem is:

<paths.results>/<T>/<A>/burgershort_<flavour>_site<siteStart>

The trajectory-specific result file contains datasets named:

burgershort_site_<x>_<y>_<z>_<t>_hit_<hit>

Each dataset contains one record per requested photon propagator. Its important members are burgerSingle, the current hit's same-noise contraction, and burgerSummed, the contraction of the cumulative propagator sums through the current hit. These are the two quantities appearing in the bias-subtraction equation above; neither is independently a physical Burger result.

Result database

The result database is distinct from Hadrons' application and statistics databases. This workflow directly creates:

burgershort_symmetries, the displacements catalogue used to record symmetry factors;
burgershort_data, the dataset catalogue for the exported contractions.

Hadrons result metadata additionally records the exported hit range in burgershort_files.

`burgershort_symmetries`

Column	Type	Meaning
`symmetry`	text, not null	Site-generator symmetry name.
`rSq`	unsigned integer, not null	Radial shell index.
`site`	text, not null	Coordinate encoded as a space-separated string.
`factor`	unsigned integer, not null	Symmetry multiplicity factor.

Primary key: (symmetry, rSq, site).

`burgershort_data`

Column	Type	Meaning
`site`	text, not null	$r$ encoded as a space-separated string.
`flavour`	text, not null	Flavour of the input propagator.
`AMAstage`	text, not null	AMA-stage label from the input.
`hits`	unsigned integer, not null	One-based hit count recorded for the dataset.
`file`	text, not null	Trajectory-specific HDF5 result filename.
`dataset`	text, not null	Burger-short dataset name in that file.

Primary key: (site, flavour, AMAstage, hits).

`burgershort_files`

Hadrons result metadata records the exported hit range:

Column	Type	Meaning
`flavour`	text, not null	Flavour used for the export.
`hitStart`	unsigned integer, not null	First exported hit, currently `0`.
`hitEnd`	unsigned integer, not null	One past the final exported hit.

Column	Type	Meaning
`site`	text, not null	\(r\) encoded as a space-separated string.
`flavour`	text, not null	Flavour of the input propagator.
`AMAstage`	text, not null	AMA-stage label from the input.
`hits`	unsigned integer, not null	One-based hit count recorded for the dataset.
`file`	text, not null	Trajectory-specific HDF5 result filename.
`dataset`	text, not null	Burger-short dataset name in that file.