AmpliCol matrix elements in mg7 ([amplicol] processes)

[theoheimel]

AmpliCol as a second matrix-element backend of the mg7 output: generate p p > j j j [amplicol], alone or mixed with madmatrix processes in one output. Based on #285. It needs pyamplicol with mg5amcnlo/pyamplicol#6.

How it works

• Output: each [amplicol] process definition goes to SubProcesses/A<n>_<name>/. pyamplicol generates a leading-colour artifact (lc), a full-colour one (full), and the sources of a UMAMI library returning their ratio (reweight). No MG diagrams are generated.
• Subprocesses: every UMAMI channel (one colour-ordered phase-space pattern) becomes a madspace subprocess. It has the LC matrix element at a fixed channel and a colour-ordered phase-space mapping.
• Colour accuracy: a weighting step with the ratio library re- or unweights the events to full colour, using the ratio-returning weighting steps of madspace: multi-step re- and unweighting (surrogates, color reweighting) #285.
• Run card: a new [amplicol] section with color_accuracy (full, lc), mode (reweight, unweight) and the first-pass settings.

madspace

• MatrixElement with a fixed channel index (no channel input).
• Integrands sample the discrete choices of the phase-space mapping uniformly, with weight 2^n.
• LHE completion of subprocesses without diagrams.

Launcher (launch.py)

• Module split: launch.py is split into modules (common, observables, subprocess_madmatrix, madgraph_process, options, model_widths, postprocess, driver, cli); launch.py re-exports their names. The e+e- j reference cross section is reproduced exactly.
• Weighting steps per subprocess, and hooks for other matrix-element backends.
• AmplicolSubprocess:
  • flavour-grouped legs and their MG multiparticle labels;
  • beams that pyamplicol keeps in one order only are integrated as mirrored, as madmatrix does;
  • the libraries of all channels of a process are loaded once.

Interface and output

• [amplicol] syntax: process definitions are kept without diagrams. Decay chains, explicit orders, s-channel and particle restrictions, polarisations, non 2->n processes and outputs other than mg7 are refused.
• Coupling orders: MG's default WEIGHTED order becomes pyamplicol coupling-order limits.
• Separate worker: pyamplicol runs in a worker process (madgraph/iolibs/amplicol_worker.py). Symbolica holds a per-user lock until its process exits, so MadGraph sessions no longer block each other; a worker waits while another one runs.
• Amplicol-only outputs get no madmatrix files.
• Refused for [amplicol]: cuts that are not flavour blind, GPUs, gridpacks, dummy matrix elements, and matrix-element re-evaluation in the systematics.

Tests

• tests/unit_tests/interface/test_amplicol_syntax.py: syntax, export (flavour groups, multiparticles, coupling orders, mirrored beams).
• tests/acceptance_tests/test_mg7_amplicol.py: cross sections against madmatrix within errors for
  • g g > g g g (reweight and unweight; LC = 9/8 x full);
  • g g > t t~ g;
  • p p > j j j;
  • a mixed [amplicol] + madmatrix output.

All pass with mg5amcnlo/pyamplicol#6.

Known limitations

• Phase space for two-particle sides: the colour-ordered mapping undersamples colour orders where a side between the beams has exactly two particles, e.g. 0 2 3 1 4 5 in g g > g g g g, so it shows large weights there. Unlike Fortran AmpliCol, such a side is built with a 2->2 peel instead of a 2->3 step against the opposite beam, and composite masses are sampled flat instead of with s^-0.5. Not addressed here, see madspace: colour-ordered mapping undersamples two-particle sides (vs Fortran AmpliCol) #292.
• Generation time: pyamplicol takes a few minutes for p p > j j j at output, dominated by Python parts of pyamplicol.
• Concurrent generation: two [amplicol] generations cannot run at the same time while Symbolica takes its restricted thread at import.