FEAT: derive C-parity sign for charge-conjugate decay chains

[Zeyna777]

Closes #204.

Generalises the C-parity sign convention derived in ComPWA/jpsi-nstar#573 from $J/\psi \to p\bar p\eta$ to an arbitrary three-body decay, as a new ampform_dpd.cparity module.

What

If charge conjugation maps the final state of a decay onto itself, the strong interaction relates each decay chain to the chain of its charge-conjugate resonance. The two chains are then one model component with a single set of couplings and a fixed relative sign,

$$\mathcal{H}[\bar R, \dots] = s , \mathcal{H}[R, \dots] , , \qquad s = \pm 1 , .$$

jpsi-nstar computes $s$ as C_parent * C_meson * (-1)**L — correct for that channel, but it hard-codes both the fact that there is exactly one self-conjugate final-state particle and the fact that the decay vertex is the one that gets re-ordered. Here $s$ is assembled from the three factors of the general derivation instead:

$$s = \underbrace{C_0}_\text{initial state} ; \underbrace{\prod_a C_a}_\text{self-conjugate finals} ; \underbrace{\prod_v \eta_v}_\text{re-ordered vertices}$$

For three-body DPD this can be evaluated in closed form. Charge conjugation is an involution, so the permutation it induces on the final state is either the identity or a single transposition; the production vertex $0 \to R,k$ is written as (resonance, spectator) in both chains and never mismatches; and the cyclic pair ordering $(23)1,(31)2,(12)3$ is orientation-preserving, so the decay vertex $R \to i,j$ is re-ordered exactly when charge conjugation acts non-trivially on $i$ or $j$. Its exchange phase depends on the basis,

$$\eta^\text{LS} = (-1)^{l+s_i+s_j-S} , , \qquad \eta^\text{helicity} = (-1)^{J_R-s_i-s_j} , ,$$

which is why a sign derived in one basis must never be applied to the couplings of the other.

C-parities and antiparticles are read from a QRules ParticleCollection (load_particles() by default), so nothing about the decay has to be supplied by hand.

API (src/ampform_dpd/cparity.py)

function	purpose
get_conjugate_state_map / is_c_symmetric	the gate: the permutation of the final-state IDs, or False if C maps the decay to a different process
get_conjugate_coupling_sign	$s$, per chain and per basis
get_exchange_phase	$\eta_v$ on its own
get_conjugate_chain_pairs	the chains that are tied to each other, particle first
get_c_forbidden_chains	the selection rule for chains that C maps onto themselves
relate_conjugate_couplings	the coupling substitutions, sign on the production coupling
symmetrize_conjugate_couplings	applies them to an AmplitudeModel and drops the dependent parameters

The tie handles LS couplings, helicity couplings, mixed bases and the single-coefficient form of formulate(). In the helicity basis the two indices of the decay node are swapped as well, since charge conjugation delivers the decay products in the order in which the partner chain lists them the other way round.

Validation

Reproduces the reference table of jpsi-nstar#573, including the disagreement between the two bases:

$R$	$J^P$	$s_\text{LS}$	$s_\text{hel}$
$N(1535)$	$\tfrac12^-$	$-1$	$-1$
$N(1650)$	$\tfrac12^-$	$-1$	$-1$
$N(1710)$	$\tfrac12^+$	$+1$	$-1$

and passes two independent cross-checks that involve neither of those states:

• isospin. For the $\rho^\pm$ pair of $J/\psi \to \pi^0\pi^-\pi^+$ the module gives $s=+1$, which is what the equal $\rho^+\pi^-$ and $\rho^-\pi^+$ coefficients of the $I=0$ combination require.
• QRules. For the same decay the selection rule forbids the $f_2(1270)$ chain and allows the $\rho^0$; re-generating the reaction with allowed_interaction_types="strong" makes QRules drop exactly the $f_2(1270)$.

On top of the unit tests, TestMirrorSymmetry checks the tie against the amplitudes themselves: charge conjugation relabels the final state without touching a momentum, so a tied model's intensity has to be invariant under the induced permutation of the Mandelstam variables. Untied couplings give an asymmetry of ~1e-01, the tie brings it to ~1e-16.

That check is degenerate in $s$ for a model that consists of a conjugate pair alone — both signs are eigenstates of the tie and an overall $s$ drops out of the modulus — but not once the model also contains a chain that charge conjugation maps onto itself, since that chain interferes with the pair. $J/\psi \to 3\pi$ with $\rho^\pm$ and $\rho^0$ is the smallest example and is worked out in the notebook.

Docs

docs/cparity.ipynb walks through the derivation on the real implementation: the gate, the sign factor by factor in both bases, the selection rule with its two cross-checks, the coupling substitutions, and Dalitz plots showing that the sign leaves both bands untouched and only moves the interference where they cross, that tying restores mirror symmetry, and — in the $J/\psi \to 3\pi$ section — when mirror symmetry is and is not able to tell the two signs apart.

Known limitation

Fixing the sign of a conjugate pair turned out to be a good probe of the pair-ordering conventions inside the builder, and it found one: in the $LS$ basis the Clebsch-Gordan factors of subsystem 2 are built in a different pair ordering than the isobar Wigner-$d$ function of the same node (#202). The derived sign is stated in the ordering of the DPD paper, so an $LS$ model whose conjugate pair involves subsystem 2 is tied with the wrong relative sign between waves of different $l$, off by exactly $\eta^\text{LS}$.

That is a property of DalitzPlotDecompositionBuilder, not of this module, so it is fixed separately in #207. Helicity couplings are unaffected and are the safe choice until that lands.

Merge-order note: the xfail in TestMirrorSymmetry is strict=True, so it starts failing the moment #207 makes it pass. Whichever of the two PRs is merged second needs test_tying_restores_mirror_symmetry_for_different_waves stripped of its @pytest.mark.xfail decorator — the test body itself already asserts the correct behaviour and needs no other change.

Notes

• No existing behaviour is touched; cparity is a new module and the only changes elsewhere are two test fixtures, three api_target_substitutions, five spell-check entries and the docs toctree.
• docs/cparity.ipynb is added to the [[tool.ty.overrides]] list that already covers the other documentation notebooks.

🤖 Generated with Claude Code

[redeboer]

47a94e9: it would be good to check in a separate branch/PR whether #202 is really a bug. We can then also test this downstream in the polarimetry repo, because that does floating-point comparisons to a published model.