mg7 merged-flavor: single-merged-leg flavored couplings + guard (MSSM)

[oliviermattelaer]

Summary

Handles merged-flavor (PDG=81) coupling topologies in the mg7/madmatrix C++
output that previously crashed with a cryptic unpack error (k1, k2 = [i for i in key if i!=0]) — surfaced by MSSM generate p p > go go under the default
mg7 output. Pre-existing on the feat-madmatrix branch; unrelated to the goodhel
work this PR is based on.

This is incremental: single-merged-leg independent couplings are now fully
supported and validated; the remaining gap (event-by-event "dependent"
flavored couplings, e.g. SUSY-QCD gluino-squark-quark) is cleanly guarded
with an actionable error, not a crash. output madevent/standalone support
the full set and are unaffected.

What's here (4 commits)

1. Guard (_assert_flv_couplings_supported): raises a clear InvalidCmd
   for the not-yet-supported cases instead of crashing / emitting uncompilable
   code. Scoped to the process's used couplings.
2. Tests + CI: split the MSSM p p > go go check into an mg7 job
   (test_mssm_gogo_mg7_unsupported → acceptancetest_mg7.yml) and a madevent
   job (test_madevent_mssm_gogo → acceptancetest_madevent.yml).
3. Design doc (docs/mg7_merged_flavor_mssm_design.md): full diagnosis +
   how the Fortran side does it (the template we mirror).
4. Single-merged-leg support (independent couplings):
   • serialization mirrors Fortran flavor_couplings.f (unmerged partner gets
     flavor index 1);
   • consumer fix in get_coupling_def — select the coupling by the merged
     fermion leg (cudacpp arg order can put the unmerged fermion first, unlike
     Fortran).

Validation

• p p > n1 n1 QCD=0 (t-channel squark, EW/independent): standalone_mg7 now
  reproduces the Fortran standalone per-flavor |M|² for all flavors (before
  the consumer fix only flavor 0 matched). New test
  test_standalone_mg7_mssm_single_leg.
• Two-leg path unchanged: test_standalone_mg7_vs_cpp still passes.
• p p > go go still fails cleanly with the guard (dependent couplings).

CPU/SSE4 builds + check_sa.exe validated locally; CUDA path untouched here.

Remaining (separate / next)

Dependent (event-by-event) flavored couplings — the per-event idcoup +
CD_ACCESS FLV view, the analogue of Fortran's VAL%P => GC(J). This is what
unblocks full p p > go go. Tracked in the design doc.

🤖 Generated with Claude Code

[Qubitol]

Claude report on the implementation of Step 3 of the design document docs/mg7_merged_flavor_mssm_design.md

mg7 merged-flavor — Step 3: dependent (running-αs) flavored couplings

Branch claude/mg7-flv-single-leg, commit d20a583036.

What was implemented

Dependent (event-by-event, running-αs) flavored couplings for the mg7/madmatrix
standalone_mg7 backend — the MSSM SUSY-QCD squark-quark-gluino case
(p p > go go, couplings GC_106/GC_110 ∝ g_s). This completes Step 3 of
docs/mg7_merged_flavor_mssm_design.md.

Mechanism (per-event AoSoA; flavor index constant across a SIMD lane)

A running-αs coupling cannot be addressed by the fixed FLV_COUPLING value[]
pointers set once in setIndependentCouplings. Instead:

• The FFSxM vertex routines are templated on the coupling access type, so
  dependent flavored calls are instantiated with CD_ACCESS (per-event SIMD)
  and independent ones keep CI_ACCESS (broadcast). The consumer body
  (get_coupling_def) is unchanged except the per-flavor stride 2 →
  C_ACCESS::flv_stride.
• Per event page, calculate_jamps gathers the running coupling values into
  an aligned AoSoA buffer dpf_value and wraps it in
  FLV_COUPLING_ARRAY<nDPF,nMF,CD_ACCESS::flv_stride> flvCOUPs_dep.
• Direct analogue of Fortran's FLV_xx%VAL(k)%P => GC_yyy(J). The independent
  path stays numerically identical. By construction all SIMD lanes share the
  same flavor index but read their own per-event running value.

Files changed

• MemoryAccessCouplings.h / MemoryAccessCouplingsFixed.h — add
  C_ACCESS::flv_stride (nx2*neppC for CD_ACCESS, nx2 for CI_ACCESS).
• cpp_hel_amps_h.inc — FLV_COUPLING_ARRAY gains a 3rd template param
  FSTRIDE (default nx2, so the independent path is byte-for-byte unchanged).
• model_handling.py —
  • consumer get_coupling_def strides by C_ACCESS::flv_stride;
  • format_coupling splits FLV routing into flvCOUPs / flvCOUPs_dep
    (dependent calls keep CD_ACCESS);
  • get_process_function_definitions emits nDPF + constant
    cDPF_partner1/2/idcoup (idcoup symbolic via
    Parameters_dependentCouplings::idcoup_<GC>);
  • the per-event AoSoA gather + flvCOUPs_dep view in calculate_jamps;
  • set_flv_couplings now serializes only independent flavored couplings.
• export_cpp.py — same set_flv_couplings change; guard now only rejects
  vertices with >2 merged legs.
• process_function_definitions.inc — nDPF constant + cdpfdecl block.
• Tests/CI — test_mssm_gogo_mg7_unsupported → test_standalone_mg7_mssm_gogo
  (positive per-flavor consistency check), with the two CI workflow refs updated.
• docs/mg7_merged_flavor_mssm_design.md — Status/Step 3 marked done with the
  as-implemented design.

Validation (CPU/SIMD cppavx2)

p p > go go standalone_mg7 vs Fortran standalone, √s = 3000 GeV:

	mg7	Fortran
QQx d d~ / s s~	1.1166755580	1.1166755121
QQx u u~ / c c~	1.1177869029	1.1177868883
gg	6.2551194240	6.2551192425

All agree to ~1e-7 (the mg7 mixed-precision-float floor).

Green regression tests: test_standalone_mg7_mssm_gogo,
test_standalone_mg7_mssm_single_leg, test_standalone_mg7_vs_cpp,
test_standalone_cpp_fd_output_consistency.

Caveat

GPU was not validated (no GPU in the dev environment). The gather/routing is
written to be CPU+GPU uniform, but a CUDA build+run cross-check is advisable
before relying on the CUDA path.

Gotcha (for the test)

The two check drivers disagree on the energy-argument semantics below the
gluino-pair threshold (the Fortran check auto-bumps to ~1215 GeV/beam), so the
test uses √s = 3000 GeV where both evaluate the same phase-space point. Without
that, a naive comparison looks ~18% off purely from mismatched momenta.

[oliviermattelaer]

@Qubitol I think that we can merge this after your final change.
Maybe we can consider remove the file in the docs directory