Skip to content

iblep-disc-loops

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-loops 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-loops estimates disconnected sea-quark loops with stochastic Z2 noise. It produces single-propagator loops with all gamma insertions, the 'specs' diagram, and optionally spin-colour-traced loop components for constructing tadpole insertions in iblep-conn-lep and iblep-conn-omega.

It can also save the stochastic solves to disk for use in iblep-disc-burgershort.

Statistics can be accumulated over multiple runs of iblep-disc-loops. To support this functionality, checkpoints (the sum of all stochastic propagator loops to that point) can be saved to disk at the end of each run, and be used to resume the next run.

The 'specs' diagram is calculated for both individual flavours, and the light-strange contribution is also calculated as a combined estimator using the 'split-even' estimator. For details, see https://arxiv.org/abs/1903.10447 and https://arxiv.org/abs/2301.03995.

Inputs and outputs

Inputs

  • A gauge configuration, or the random gauge field used by the debug setup.
  • An optional gauge transformation.
  • A light-quark eigenpack for supported deflated solver setups.
  • Optional checkpoint propagator loops from a previous run when hits.start > 0.

Outputs

  • Optional stochastic propagator fields saved under paths.props.
  • Accumulated loop checkpoints under paths.ckpoint, allowing later runs to continue the hit sum.
  • Optional traced loop components under paths.loops, for use as tadpole insertions by downstream connected workflows.
  • specs and disc HDF5 files, containing 'specs' diagram results and single-propagator loops.
  • An optional XML module graph at paths.xml/<runId>.xml.

The debug configuration uses an 8^4 lattice and deterministic noise/gauge seeds, making it suitable for small numerical regression tests.

Workflow

The workflow loads or creates the gauge field, constructs the requested sea solvers, and creates position-space photon propagators. For every noise hit in the half-open range [hits.start, hits.start + hits.step), it:

  1. Creates a sparse spin-colour noise source.
  2. Solves light and strange propagators, and charm when flags.doCharm is enabled.
  3. Forms the light-strange split-even propagator.
  4. Contracts each stochastic propagator with its noise field to form an untraced loop.
  5. Updates the accumulated loop sum, loading the previous checkpoint when the run starts at a non-zero hit.
  6. Produces both single-hit and accumulated (summed) specs contractions for each hit index in the run, plus the disconnected loop contractions.
  7. Traces the loop with the configured gamma insertions to make tadpole components, then contracts each tadpole with every requested photon and flavour pairing to form Specs datasets.

For computational efficiency, the specs diagram is calculated as $$ \sum_{x,y} \left(\sum_i^N S(x, \eta_i) \eta^\dagger_i(x) \gamma_\mu \right) \left(\sum_j^N S(y, \eta_j) \eta^\dagger_j(y) \gamma_\nu \right) G_{\mu\nu}(x-y), $$ where the efficiency gain comes from taking the sum over noises on each loop before performing the contraction. This has several benefits:

  • The \(N^2\) possible contractions between the \(N\) noises in both loops are reduced to a single contraction.
  • As a result, only the sum of stochastic propagator loops needs to remain in memory.
  • This sum of loops can be saved to disk as a checkpoint to resume running from.

However, contractions involving the same noise in both loops generates unphysical bias terms, so this estimator is biased. This bias term is $$ \sum_{x,y}\sum_i^N \left( S(x, \eta_i) \eta^\dagger_i(x) \gamma_\mu \right) \left( S(y, \eta_j) \eta^\dagger_i(y) \gamma_\nu \right) G_{\mu\nu}(x-y), $$ These single contractions need to be removed from the sum of contractions in a bias-subtraction step to obtain valid results. Therefore, in addition to the summed contraction, the contraction is also performed for the propagator solved on the current hit index, thereby computing exactly the biased contributions that must be subtracted off.

The single and summed contraction types are both saved so that analysis can construct the unbiased specs diagram. Since the single contraction involves the ith noise hit in both loops, $$ \sum_{x,y} \left( S(x, \eta_i) \eta^\dagger_i(x) \gamma_\mu \right) \left( S(y, \eta_j) \eta^\dagger_i(y) \gamma_\nu \right) G_{\mu\nu}(x-y), $$ and the summed contraction is the biased estimator using hits up to i, the unbiased estimator can be reconstructed by subtracting all single contractions preceding the ith summed contraction from the summed contraction. For example, constructing the estimator on four hits requires subtracting off the single contraction for hits 0, 1, 2, and 3 from the summed contraction for hit 3.

Since the single-propagator loop results contain only a single noise, no bias-subtraction step is necessary.

From datasets to physics

The definitions of the individual Hadrons contractions are given in the Hadrons MContraction documentation, in particular the entries for Loop, DiscLoop, SplitEvenLoop, QEDTadpole, and QEDSpecs. This section specifies how those module outputs are used by this workflow and how the stored data must be processed.

For flavour \(f\) and noise hit \(i\), write

\[ L_{f,i}(x)=\{S_f\eta_i\}(x)\eta_i^\dagger(x), \qquad \overline L_{f,N}(x)=\sum_{i=0}^{N-1}L_{f,i}(x). \]

The single dataset at database hit \(i\) is formed from \(L_{f,i}\), while the summed dataset at hit \(N-1\) is formed from \(\overline L_{f,N}\). Hit indices are zero-based, so a summed row with hit = h contains \(N=h+1\) hits, including hits restored from a checkpoint.

Single-loop output

For gamma matrix \(\Gamma\) the zero-momentum DiscLoop data are

\[ D_{f,i}^{\Gamma}(t) =\sum_{\mathbf x}\operatorname{tr}_{s,c} [\Gamma L_{f,i}(t,\mathbf x)]. \]

The corresponding summed dataset is \(\sum_{i=0}^{N-1}D_{f,i}^{\Gamma}\), not its stochastic average. An estimate of the loop is therefore

\[ \widehat D_f^{\Gamma}(t;N) =\frac{1}{N}D_{f,N}^{\Gamma,\mathrm{summed}}(t). \]

No diagonal-noise subtraction is required for this one-loop quantity.

The spliteven_ls label is not an additional quark flavour. It stores the split-even estimator

\[ L_{l-s,i}^{\mathrm{SE}}(x) =(m_s-m_l)\{S_l\eta_i\}(x)\gamma_5 \{S_s\eta_i\}(x)^\dagger\gamma_5, \]

whose expectation value is \(S_l(x,x)-S_s(x,x)\). This can be used as an optimised estimator for the disconnected contribution to a real radiative decay from the \(\{u,d,s\}\) flavours with a unitary light quark.

Specs output and bias subtraction

Let \(C_{fg,ij}^{(a)}\) denote the bare QEDSpecs contraction for loop flavour \(f\) on noise \(i\), loop flavour \(g\) on noise \(j\), and photon prescription \(a\). It includes both local vector insertions and the implemented factor \(i^2=-1\): $$ C_{fg,ij}^{(a)} =-\sum_{x,y,\mu} G_a(y-x)\, \operatorname{tr}{s,c}[L(x)\gamma_\mu]\, \operatorname{tr}{s,c}[L(y)\gamma_\mu]. $$ The HDF5 members selected by contractionType have the exact meanings $$ \begin{aligned} C_{fg,h}^{(a),\mathrm{single}}&=C_{fg,hh}^{(a)},\ C_{fg,N}^{(a),\mathrm{summed}} &=\sum_{i,j=0}^{N-1}C_{fg,ij}^{(a)}, \qquad N=h+1. \end{aligned} $$ The same-noise terms \(i=j\) are biased. The unbiased ordered-pair estimator is $$ \boxed{ \widehat C_{fg}^{(a)}(N) =\frac{ C_{fg,N}^{(a),\mathrm{summed}} -\displaystyle\sum_{i=0}^{N-1}C_{fg,i}^{(a),\mathrm{single}} }{N(N-1)}} \qquad (N\geq2). $$ In database terms, use the summed row at hit = N-1 and subtract every matching single row with hit from 0 through N-1. The flavour ordering in (flavour1, flavour2) is the ordering used in \(C_{fg}\); do not silently identify \(fg\) with \(gf\) when selecting data.

The contractions do not contain the electromagnetic coupling, quark charges, or local vector-current renormalisation factors. For physical flavours \(f\) and \(g\), the renormalised contribution is therefore $$ C_{fg,\mathrm{phys}}^{(a)} =e^2 Q_fQ_g Z_V^fZ_V^g\, \widehat C_{fg}^{(a)}. $$ The complete Specs contribution is obtained by summing this expression over the physical ordered flavour pairs required by the observable. A stored l loop is a unitary light-mass loop, not a charge-weighted \(u+d\) loop: the \(u\)- and \(d\)-charge factors must be supplied explicitly in that flavour sum. Apply the chosen AMA combination to the bare estimators at fixed flavour, photon and trajectory before the final ensemble analysis.

Checkpointing and hit ranges

When hits.start is greater than zero, the workflow loads checkpoint files ending at hits.start - 1 and continues the accumulated sums. At the end of a run it saves checkpoints ending at hits.start + hits.step - 1.

The two debug examples demonstrate this arrangement:

  • loops.debug.0.json starts at hit 0;
  • loops.debug.4.json starts at hit 4 and loads the sums from the preceding hit range.

Run

iblep-disc-loops <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 generate the application/result metadata without executing the module graph.

Input JSON

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

{
  "setup": "debug",
  "runId": "ibdisc",
  "AMAstage": "inexact",
  "dryRun": false,
  "traj": { "start": 0, "step": 20, "end": 20 },
  "paths": {
    "results": "data/results",
    "props": "data/props",
    "loops": "data/loops",
    "ckpoint": "ckpoint",
    "resultDb": "data/result.db",
    "xml": "log/loops.0",
    "gauge": "",
    "gaugeTransform": "",
    "eigenpack": "",
    "statDb": "db/ibdisc-loops-debug.0",
    "appDb": "db/ibdisc-loops-debug.0"
  },
  "charm": {
    "mc": 0.663,
    "residual": 1.0e-8
  },
  "qed": ["L", "r"],
  "hits": { "start": 0, "step": 4 },
  "flags": {
    "saveProps": true,
    "doCharm": true,
    "saveTadpoleLoops": true,
    "saveTadpoleLoopHits": [1, 2, 4, 8, 16, 32, 64, 128, 256, 512],
    "saveTadpoleLoopGammas": ["GammaX", "GammaY", "GammaZ", "GammaT"]
  }
}
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.
dryRun boolean Yes Build run XML without execution when true.
traj.start, traj.end, traj.step unsigned integer Yes Inclusive trajectory range and increment passed to Hadrons.
paths.results path Yes Root directory for Specs and disconnected result groups.
paths.props path Yes Directory for per-hit stochastic propagators.
paths.loops path Yes Directory for saved traced loop components.
paths.ckpoint path Yes Directory for accumulated loop checkpoints.
paths.appDb, paths.statDb, paths.resultDb path Yes Hadrons application, statistics, and result-database paths.
paths.xml path Optional Directory for the saved Hadrons module graph.
paths.gauge path Setup-dependent NERSC gauge input for non-debug setups.
paths.gaugeTransform path Optional Gauge transformation used by gauge-fixed configurations. Necessary for light solves to correctly use deflation.
paths.eigenpack path Setup-dependent Light-quark eigenpack used by supported deflated solvers.
charm.mc, charm.residual number Yes Charm mass and residual; the mass is used when doCharm is enabled.
qed string array Yes Photon discretisation: L (for QED_L), r (for QED_r), or both.
hits.start, hits.step unsigned integer Yes First hit and number of hits in this run.
flags.saveProps boolean Yes If true, saves stochastic propagators to disk. Necessary for subsequently running iblep-disc-burgershort.
flags.doCharm boolean Yes Include charm solves and charm loops.
flags.saveTadpoleLoops boolean Yes Save traced gamma-component loops for tadpole insertions in iblep-conn-lep and iblep-conn-omega.
flags.saveTadpoleLoopHits unsigned-integer array Conditional Hit counts at which the summed loops are saved for tadpole insertions.
flags.saveTadpoleLoopGammas string array Conditional Must contain GammaX, GammaY, GammaZ, and GammaT when tadpole saving is enabled. Supports any Gamma matrix insertion in Grid.

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

Files and result groups

For trajectory T, AMA stage A, and first hit H, the main result stems are:

<paths.results>/<T>/<A>/specs.hit<H>
<paths.results>/<T>/<A>/disc.hit<H>

Accumulated checkpoint names use the final processed hit E:

<paths.ckpoint>/<T>/<A>/ckpoint_l.<E>
<paths.ckpoint>/<T>/<A>/ckpoint_s.<E>
<paths.ckpoint>/<T>/<A>/ckpoint_c.<E>          # when doCharm is true
<paths.ckpoint>/<T>/<A>/ckpoint_spliteven_ls.<E>

Saved traced loop names (for tadpoles) follow:

<paths.loops>/<T>/<A>/loop_<flavour>_<gamma>.<hit>

The specs group contains contractions for every requested flavour pair, photon discretisation, hit, and single/summed contraction type. The disc group contains the position-summed loop contractions for each flavour and gamma selection.

Result database

This workflow directly creates two result tables:

  • specs_data, mapping specs datasets to their photon, flavour pair, hit, and result file;
  • disc_data, mapping disconnected-loop datasets to their flavour, gamma selection, hit, and result file.

The result-group metadata mechanism additionally records hit ranges in specs_files and disc_files.

specs_data

Column Type Meaning
flavour1 text, not null Flavour used in the tadpole loop.
flavour2 text, not null Flavour used in the paired loop.
photon text, not null Photon prescription.
AMAStage text, not null AMA stage from the input.
contractionType text, not null single or summed.
hit unsigned integer, not null Noise-hit index.
filename text, not null Trajectory-specific HDF5 result filename.
dataset text, not null Specs dataset/module name in that file.

Primary key: (flavour1, flavour2, photon, AMAStage, contractionType, hit, dataset).

disc_data

Column Type Meaning
flavour text, not null Sea flavour.
AMAStage text, not null AMA stage from the input.
contractionType text, not null single or summed.
hit unsigned integer, not null Noise-hit index.
gammas text, not null Gamma selection, such as all or the four tadpole components.
filename text, not null Trajectory-specific HDF5 result filename.
dataset text, not null Disconnected-loop dataset/module name in that file.

Primary key: (flavour, AMAStage, contractionType, hit, gammas, dataset).

specs_files and disc_files

Hadrons result metadata records the hit range associated with each exported group:

Column Type Meaning
hitStart unsigned integer, not null First hit in the exported group.
hitEnd unsigned integer, not null One past the final hit in the exported group.