madspace: 2 -> 1 processes with PDFs, one energy and one PDF per beam

[oliviermattelaer]

Summary

• 2 → 1 with PDFs in madspace (p p > z, p p > h): Diagram accepts one outgoing leg for a collision. PhaseSpaceMapping gets a 2 → 1 branch: s_hat = m², one random number (the rapidity), weight 2π |ln τ| / s. The flat mode accepts 3 masses. Leptonic 2 → 1 and massless final states raise a clear error, and so does the launcher.
• One energy and one PDF per beam in run_card.toml: [beam] ebeam1, ebeam2, pdf1, pdf2.
  • beam.e_cm (= 2√(E1E2)) and beam.pdf remain readable and settable; setting either sets both beams.
  • Cards written with e_cm / pdf are translated on read.
  • set ebeam1 … works from launch scripts, and LO→MG7 conversion keeps asymmetric beams.
• Frames: the phase space is generated in the beams' centre-of-mass frame and boosted by y₀ = ½ ln(E1/E2) into the lab frame before the cuts. Events are written in the user's frame and rapidity cuts act there. pT, masses and ΔR for massless particles are boost invariant.
  • Chili's y bound is widened by |y₀|.
  • Colour-ordered ΔR bounds are not used when y₀ ≠ 0; the cut itself still applies.
• Mirror handling for asymmetric beams (bug this change would otherwise have introduced). The Integrand used to mirror accepted lab-frame events and never swapped the PDFs. That is only valid for identical beams.
  • With PhaseSpaceMapping(mirror_beams=True) the orientation is a mirror_index condition drawn before the mapping.
  • The mirror is taken in the beams' frame, then boost, then cuts.
  • Each leg uses the PDF of the beam it comes from (_pdfs_swapped); mirror flavours weigh 2, others 1.
  • Identical beams keep the existing post-cut path unchanged.
• Second PDF grid: passed to Integrand (pdf_grid2, globals prefix beam2) and SystematicsCalculator (nominal_pdf2, also reloaded by the gridpack).
  • With different sets, PDF member variations are dropped with a warning; the scale variations use both sets.
  • <mgrwt> beam labels follow the beam direction.
• LHE <init> carries both beam energies and both LHAPDF ids.

Validation

All runs use a fixed μ = 91.188 and NNPDF4.0 LO unless stated otherwise.

check	mg7	reference
p p > z, 6.5+6.5 TeV	49225 ± 17 pb	madevent 49220 ± 27 pb
p p > e+ e-, 7+4 TeV, ptl>10, ΔR>0.4, no η cut	1817.4 ± 2.9 pb	madevent 1814 ± 1.9 pb
same, ⟨y_ee⟩ in the LHE	0.281 ± 0.016	madevent 0.249 ± 0.016 (before the mirror fix mg7 gave 0.001)
same with |η_l| < 2.5	941.2 ± 1.9 pb, max |η| in LHE = 2.500	|η_lab| < 2.5 applied offline to madevent's no-cut sample: 947.5 ± 6.5 pb
p p > z, pdf1=NNPDF40 / pdf2=NNPDF23 vs swapped	44211 ± 75 vs 44223 ± 75 pb, identical scale bands	43315 vs 45121 pb before the mirror fix

• New madspace/tests/test_beam_frame.py (9 tests) covers the 2 → 1 mapping and its inverse, boosted mappings (rambo/propagator, hadronic/leptonic), lab-frame η cuts and mirror_beams.
• madspace pytest: 1541 passed, 11 skipped. The one earlier failure was the new test file, fixed. test_flow/test_mlp need torch and were not run; lhapdf python bindings were stubbed out because they abort on this Python 3.14.
• test_banner.py RunCardMG7 tests: 17/17, including new per-beam and legacy-card tests.
• test_mg7_launch.py: 40/40. test_keyboard_interrupt_reaches_the_error_handling failed once in a full run; it also fails alone on the base commit, so it's a flaky test that predates this PR.

Notes

• madevent with ebeam1 ≠ ebeam2 is not a valid reference for η cuts. With etal = 2.5 its LHE leptons span η ∈ [−2.5, 2.5 + 2y₀], and its cross section is ~4.5% below the lab-frame value. Not touched here.
• fact_scale1/fact_scale2 follow the legs, not the beams, for mirrored events. This only matters for fixed and different per-beam factorisation scales.
• DifferentialCrossSection(input_momentum_fraction=False) still reconstructs x from energies assuming symmetric beams. The launcher never uses that mode.
• Mixed lepton–hadron beams (a PDF on one beam only) are not part of this change.

🤖 Generated with Claude Code

[oliviermattelaer]

Pushed b44c4a78f: the mirrored orientation is the one the cuts and the ME see

Follow-up to the mirror_beams machinery this PR adds. The post-cut mirror that identical beams still use (_mirror_before_cuts == false) rotates the event by pi about x after everything upstream has looked at it, and two consumers were reading the wrong side of that rotation.

The matrix element

Integrand::build_common_part fed the cross section momenta_acc, the momenta as generated, while the event was written mirrored. It now takes the mirrored set when there is one. Same one-line change as "madspace: evaluate the matrix element on the momenta the event is written with" on claude/madspace-mirror-me-momenta, carried onto the post-cut path that only exists on this branch — so expect a trivial conflict there when that lands, resolved by keeping either copy.

On the mirror_beams path nothing changes, and I checked that rather than assumed it: to_lab applies the mirror inside the mapping, before the boost into the lab frame and before the cuts, so momenta_acc is already the written orientation and momenta_mirror_acc is never produced.

The cuts — the actual point

Nothing stated that the cuts have to be blind to the mirror, and nothing enforced it. It happened to hold because pt, eta_abs, delta_r, mass and sqrt_s all are.

• Observable::mirror_invariant() classifies every observable under py, pz -> -py, -pz, with no default: so a new observable has to declare which side it falls on. It also checks the ordering observable — sorting by a quantity that flips picks a different particle out of the event. An observable that matched no particle is the constant 0, so it counts as invariant (Cuts::build_function_impl already skips those).
• Cuts::non_mirror_invariant_cuts() names the offenders, and Integrand refuses the post-cut mirror when there are any, next to the asymmetric-beams check this PR already added.
• launch.py turns mirror_beams on for a subprocess whose cuts are not mirror invariant — the same switch asymmetric beams already trigger — and logs why, so mg7 never hits the refusal.

Option (a) from the two on the table, and the identical-beam fast path stays bit-for-bit for every cut set mg7 ships. Same distinction Template/LO/SubProcesses/cuts.f draws with PMIR under EBEAM(1).NE.EBEAM(2).

This is not latent

The run-card [cuts] table takes any observable name, and the template comment even advertises eta. p p > e+ e-, 2000 events, lepton-eta.min = 0.0:

	cross section	events written outside the cut
post-cut mirror (before)	276.3 +- 2.1 pb	1017 / 2000 (50.9%)
orientation first (after)	233.9 +- 2.1 pb	0

and the second is the right one: lepton-eta.max = 0.0, which a pp collider's symmetry forces to be equal, gives 232.9 +- 2.2 pb — 0.3 sigma from the new number, 14 sigma from the old. The old value is 18% high because it integrates one beam orientation twice, and a single ordering of a valence-sea pair is forward-skewed.

Nothing on the invariant-cut path moves

Default cuts keep the post-cut mirror (no switch logged), and g _quark > e+ e- _quark gives 59.0349 +- 0.0490 pb against the 59.0235 +- 0.0287 reference — 0.2 sigma, 0.019% relative.

Tests

22 new tests in madspace/tests/test_beam_frame.py:

• the per-observable classification, including the ordering observable and the absent-particle case;
• a mapping-level test that with mirror_beams the cuts act on the momenta that come out, for both orientations — and that a signed eta cut makes the two orientations disagree (627/2000 events flip verdict) while eta_abs cannot, which is exactly why the fast path is sound for the cuts mg7 ships;
• the Integrand precondition (refused post-cut, allowed with mirror_beams, allowed for unmirrored flavors);
• graph-level tests that the matrix element consumes the mirror_momenta output on the post-cut path and momenta_acc on the mirror_beams path.

I reverted each fix and rebuilt: exactly those two intended tests go red, nothing else. Full madspace suite 1569 passed / 11 skipped / 4 failed, the four being No module named 'scipy' in test_double_t.py, identical before the change.

One gap

No UpdateNotes.txt entry here. main restructured that file (new 0.3.0 section, which is where the ME fix's own entry sits), so adding one on this branch would manufacture a conflict in exactly that spot. The cut half needs a line next to it when the two meet.

🤖 Generated with Claude Code

[theoheimel]

I propose we rebase the last two commits onto #245 and close this branch because the other one has a big merge conflict now.