Reconsider amplitude builder design to improve implementation of spin alignment

[redeboer]

### Requirements
- [ ] https://github.com/ComPWA/ampform/issues/281

To-do [WIP]

• [ ] Move scalar_initial_state_mass and stable_final_state_ids config to HelicityAdapter (that should untangle this mess)

Problem description

The latest (unreleased) implementation of Dalitz-plot decomposition (https://github.com/ComPWA/ampform/pull/307) makes use of the existing HelicityAmplitudeBuilder. This is problematic, because the choice of spin alignment method influences the way the 'unaligned' amplitudes are formulated. In particular, in the case of DPD, there should be no 'isobar Wigner-D'.

Here's an attempt to summarize the processes that go on when calling HelicityAmplitudeBuilder.formulate():

• [Core] Loop over QRules' StateTransition objects to formulate (unaligned) helicity amplitudes for each decay chain. This also takes care of particle symmetrisation, through perform_external_edge_identical_particle_combinatorics().
• The helicity formalism assumes a decay proceeds through a chain of isobar decays, so that the 'unaligned' amplitude for, for example, a three-body decay $0 \to R (\to 12) 3$ can be formulated as a product of two couplings for the two isobars: with $\mathcal{H}$ some scalar, complex coupling strength for each isobar, $D$ a Wigner-D function over helicity angles $\left(\phi^i_j, \theta^i_j\right)$ (polar angles of $j$ in the rest frame of $i$), $s_i$ the spin magnitude of particle $i$, $\lambdai$ its helicity[^1], and $\mathcal{D}$ a dynamics lineshape that depends on kinematic variables $\tau$ (usually Mandelstam variable, widths, masses of decay products and angular momentum of the decaying pair).[^2]<!-- \begin{eqnarray} \mathcal{A}^R &=& \mathcal{H}{0 \to R,3}\; D^{s0}{\lambda_0, \lambda_R - \lambda_3}\left(-\phi^0_R,\theta^0R\right)\; \mathcal{D}{0 \to R,3}\left(\tau\right) \ & \times & \mathcal{H}_{R \to 1,2}\; D^{sR}{\lambda_R, \lambda_1 - \lambda_2}\left(-\phi^R_1,\theta^R1\right)\; \mathcal{D}{R \to 1,2}\left(\tau\right) \end{eqnarray} -->
• Keep track of lineshape choices $\mathcal{D}\left(\tau\right)$ for each isobar node. This is outsourced to DynamicsSelector.
• Generate suggested parameter values for each parameter sympy.Symbol in the resulting expression. The amplitude builder only generates suggested parameter values for the helicity couplings $\mathcal{H}$ (simply set to 1+0j). ResonanceDynamicsBuilders suggest values for the remaining parameters, like pole position or meson radius.
• Formulate conversion from four-momentum to kinematic variables. This currently done through the HelicityAdapter and computes only invariant masses and helicity angles $\phi, \theta$.
• Generate coefficient/coupling names for each StateTransition through a NameGenerator. For some state transitions, the coupling name is the same, for parity conservation concerns (the intelligence there comes from QRules, though). See HelicityAmplitudeNameGenerator for the implementation used by the HelicityAmplitudeBuilder.
• Align spin (see [^1]). This is currently to be done through an external class that the HelicityAmplitudeBuilder is unaware of. This class also has the responsibility to compute any additional kinematic variables, like $\zeta^i_{j(k)}$ for Dalitz-plot decomposition.

Example

All in all, as of 148c8c9, this results in the following amplitudes, using NoAlignment and DalitzPlotDecomposition[^3]:

import ampform
import qrules
from ampform.helicity.align import NoAlignment

reaction = qrules.generate_transitions(
    initial_state=("J/psi(1S)", [-1, +1]),
    final_state=["K0", "Sigma+", "p~"],
    allowed_intermediate_particles=["Sigma(1660)", "N(1650)"],
    allowed_interaction_types=["strong"],
    formalism="helicity",
)

builder = ampform.get_builder(reaction)
builder.config.spin_alignment = NoAlignment()
builder.config.use_helicity_couplings = True
non_aligned_model = builder.formulate()
non_aligned_model.intensity

non_aligned_model.amplitudes

For DPD, the reaction needs to be relabeled:[^4]

from ampform.helicity.align.dpd import DalitzPlotDecomposition, relabel_edge_ids

reaction_123 = relabel_edge_ids(reaction)
builder_123 = ampform.get_builder(reaction_123)
builder_123.config.spin_alignment = DalitzPlotDecomposition(reference_subsystem=1)
builder_123.config.use_helicity_couplings = True
dpd_model = builder_123.formulate()
dpd_model.intensity

dpd_model.amplitudes

Note that the choice for DPD does not affect the individual amplitudes. This is incorrect, if I understand @mmikhasenko correctly. In combination with #309, this points in the direction of a fundamental design problem, namely the assumption that the choice of 'spin alignment method' does not affect the form of the 'unaligned' amplitudes.

Related issues

• 210

• 257

• 281

• 284

• 309

[^1]: This causes the need for 'spin alignment'. [^2]: The CanonicalAmplitudeBuilder forms an extension of the HelicityAmplitudeBuilder class that (only) inserts Clebsch-Gordan coefficients (formulate_clebsch_gordan_coefficients()). Amplitude $\mathcal{A}^R$ then becomes a sum over all allowed $LS$-couplings for $0 \to R (\to 12) 3$ with two CG coefficients for each node (four in the case of a three-body decay). [^3]: Yes, there is a minor bug in the second set of summations, see https://github.com/ComPWA/ampform/issues/309. [^4]: The relabeled reactions look as follows:

| Standard labeling | DPD labeling |
|---|---|
| ![reaction](https://user-images.githubusercontent.com/29308176/182376650-00d3c713-b2d2-4491-9d92-a605e5ecfa4f.svg) | ![reaction123](https://user-images.githubusercontent.com/29308176/182376653-9e681178-4f78-4a7e-99ee-78f22955856e.svg) |

[redeboer]

Tagging @spflueger here as well, who knows more about the implementation for symmetrization [code] and "parity prefactor" [code] (see also #284).

[redeboer]

Conclusion after discussion with @spflueger: write a new builder for DPD and don't let this work through dependency injection (spin_alignment member). A core method seems to be _formulate_partial_decay(), which is overwritten by CanonicalAmplitudeBuilder. If this could somehow be made into a function or separate interface, we can also get of this risky inheritance-in-order-to-share-functionality.