MadSpin: six fixes for the frame-projected polarised density

[oliviermattelaer]

Targets #65's branch, so it lands with the polarisation feature it completes.

These six fixes are what make a polarised NLO production decayable at all. Before them, p p > z{0} z{0} [QCD] + MadSpin ran at ~450 s per event and was killed at event 40 of 4000. After, the same 20000 production events decay in 15.6 s — a factor ~1.3e5 — and the sample closes on the physics: f00 = 0.9995 +- 0.0228 for a pure-longitudinal production, against 1.

They also fill in the "polarised ME + MadSpin" column of the three-route comparison in #65's own study, which had to be left empty. Every entry now agrees with the other two routes within 1.3 sigma.

The six

1. Silent wrong physics. _production_polarization parsed the process line with MadSpin's tree-level mg5cmd, which refuses a perturbation-order bracket. MadSpin only warned, so the density was left unrestricted and every NLO polarised production got unpolarised decay angles — with the right cross section and no crash. The bracket is irrelevant to the polarisation, so it is stripped before parsing.
2. _frame_boost called get_momenta without merged_map, raising ValueError under flavour grouping.
3. get_density called get_pdg — which matches particles by exact momentum equality — on the boosted momenta, so nothing was found. The pdgs are now read off the lab momenta, before the boost.
4. get_density's cached branch recomputed the tag with a bare get_tag_and_order(), losing the 1->N antiparticle fallback that get_pdir owns. It now caches the tag get_pdir resolved.
5. The load-bearing one. The offshell mass-stage weight divided a me_frame-boosted Tr(rho_off) by a lab-frame |M_prod|^2. A helicity-restricted matrix element is not Lorentz invariant, so the two are different projections; for an unpolarised production the trace is invariant and they agree, which is why only polarised runs were affected. Reverting this one alone puts the mass-stage bound back to 7.9e6 while leaving both angular bounds bit-identical — that is the whole difference between 450 s/event and 15.6 s/20000.
6. The same frame fix on the joint path.

_onshell_production_norm returns calculate_matrix_element unchanged when there is no frame boost, so unpolarised runs are bit-for-bit identical.

Safety of fix 6 on the joint path

That call site is also on the unpolarised polarisation-weight path, so it had to be shown safe rather than assumed. Over 5414 production events the denominator was bit-identical across every joint trial of the same event — it is a per-production-event constant, and a constant cancels out of an accept/reject, so the accepted decay distribution is unchanged in law, not merely in measurement. End to end, redecaying 150000 events moves every published fraction by <= 0.5 sigma and leaves the nine-row ms_pol closure intact.

The test commit

The fixes were written against PR #103's head; #65's head has nine commits on top, three of which added stubs the fixes outgrow. All three are the double falling behind the real class, so the stubs move, not the production code:

• _FrameStub gains _revert_merged — MadSpinInterface carries it as a class attribute, and the stub does not inherit from it. Guarding the production side with getattr would have hidden a real attribute behind a test-only default.
• _MomentaEvent.get_momenta gains merged_map=None, matching lhe_parser.Event.get_momenta, which has always had it.
• _offshell_fixture gains _onshell_production_norm, delegating to the calculate_matrix_element it already fakes — exactly what the real helper does with no frame boost, which is the only case a boost-free stub can represent. Borrowing the real helper would have dragged _frame_boost and get_density into the stub's hand-kept borrow list.

502 unit tests OK — the same count and result as the base without the fixes, so nothing was skipped to get there.

For the reviewer

Upstream 3.8.0 carries an independent version of fix 5 (mg5amcnlo#407) and of a related joint symmetry factor (#408, #409). When MadGraph7 merges 3.8.0 (#117) these need reconciling rather than both being applied — and MadGraph7's get_density signature carries flavour-grouping arguments 3.8.0 has no equivalent of, so it will not be a clean either/or. Flagging it here because the commit history is the only place that context survives.

Known limit: p p > z z j [QCD] still aborts, on a separate pre-existing flavour-ordering bug that reproduces identically on the unpolarised process. #114 fixes that one; it is unrelated to these six.

🤖 Generated with Claude Code

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

Improves correctness and runtime of MadSpin when decaying polarised NLO productions by making production-density parsing and normalization frame-consistent (and fixing flavour-grouping interactions).

Changes:

• Strip perturbation-order brackets from NLO process lines before MadSpin’s tree-level parser reads polarisation braces.
• Fix flavour-grouping / merged-pdg handling in _frame_boost() and get_density() (merged map propagation + cached tag).
• Ensure get_density() uses lab-frame momenta for exact-momentum PDG matching, and align mass-stage/joint-path normalization with the numerator frame.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
MadSpin/interface_madspin.py	Core fixes for process parsing, flavour-grouping momentum retrieval, density tagging, and frame-consistent normalization.
tests/unit_tests/madspin/test_madspin.py	Updates stubs/fixtures to match new production behavior API expectations (merged map + normalization helper).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.