Welcome to AmpForm-DPD!

This Python package is a (temporary) extension of AmpForm and provides a symbolic implementation of Dalitz-plot decomposition (10.1103/PhysRevD.101.034033) with SymPy. It has been extracted from the ComPWA/polarimetry repository, which is not yet public.

Installation

The fastest way of installing this package is through PyPI:

python3 -m pip install ampform-dpd

This installs the latest version that you can find on the stable branch. The latest version on the main branch can be installed as follows:

python3 -m pip install git+https://github.com/ComPWA/ampform@main

You can substitute stable in the above command with main or any of the tags listed under the releases. In a similar way, you can list ampform-dpd as a dependency of your application in either setup.cfg or a requirements.txt file as:

ampform-dpd @ git+https://github.com/ComPWA/ampform-dpd@main

However, we highly recommend using the more dynamic, ‘editable installation’ instead. This goes as follows:

1. Get the source code (see the Pro Git Book):

   git clone https://github.com/ComPWA/ampform-dpd.git
   cd ampform-dpd
   

2. [Recommended] Create a virtual environment (see here or the tip below).

3. Install the project in ‘editable installation’ with additional dependencies for the developer:

   python3 -m pip install -e .[dev]
   

That’s all! Have a look at the Welcome to AmpForm-DPD! page to try out the package, and see Help developing for tips on how to work with this ‘editable’ developer setup!

Tip

It’s easiest to install the project in a Conda environment. In that case, to install in editable mode, just run:

conda env create
conda activate ampform-dpd

This way of installing is also safer, because it pins all dependencies. Note you can also pin dependencies with pip, by running:

python3 -m pip install -e .[dev] -c .constraints/py3.x.txt

where you should replace the 3.x with the version of Python you want to use.

Physics

Dalitz-plot decomposition allows us to separate variables that affect the angular distribution from variables that describe the dynamics. It allows rewriting a transition amplitude \(T\) as

\[ T^{\Lambda}_{\{\lambda\}}(\alpha,\beta,\gamma; \{\sigma\}) = \sum_{\nu} {\color{RoyalBlue} D_{\Lambda,\nu}^{J}(\alpha,\beta,\gamma)} \, {\color{Orange} O^\nu_{\{\lambda\}}(\{\sigma\})}. \]

Here, \(\Lambda\) and \(\nu\) indicate the allowed spin projections of the initial state, \(\{\lambda\}\) are the allowed spin projections of the final state (e.g. \(\{\lambda\}=\lambda_1,\lambda_3,\lambda_3\) for a three-body decay). The Euler angles \(\alpha,\beta,\gamma\) are obtained by choosing a specific aligned center-of-momentum frame (“aligned CM”), see Fig. 2 in Ref [1], which gives us an “aligned” transition amplitude \(O^\nu_{\{\lambda\}}\) that only depends on dynamic variables \(\{\sigma\}\) (in the case of a three-body decay, the three Mandelstam variables \(\sigma_1,\sigma_2,\sigma_3\)).

These aligned transition amplitudes are then combined into an observable differential cross section (intensity distribution), using a spin density matrix \(\rho_{_{\Lambda,\Lambda'}}\) for the spin projections \(\Lambda\) of the initial state,

\[ \mathrm{d}\sigma/\mathrm{d}\Phi_3 = N \sum_{\Lambda,\Lambda'} \rho_{_{\Lambda,\Lambda'}} \sum_{\nu,\nu'} {\color{RoyalBlue} D^{J^*}_{\Lambda,\nu}\left(\alpha,\beta,\gamma\right) D^{J}_{\Lambda',\nu'}\left(\alpha,\beta,\gamma\right) } \sum_{\{\lambda\}} {\color{Orange} O^\nu_{\{\lambda\}}\left(\{\sigma\}\right) O^{\nu'*}_{\{\lambda\}}\left(\{\sigma\}\right) }. \]

Given the right alignment, the aligned transition amplitude can be written as

(1)\[\begin{split}\begin{eqnarray*} {\color{Orange}O^\nu_{\{\lambda\}}\left(\{\sigma\}\right)} &=& \sum_{(ij)k} \sum^{(ij)\to i,j}_s \sum_\tau \sum_{\{\lambda'\}} \; {\color{Orange}X_s\!\left(\sigma_k\right)} \\ {\color{LightGray}\text{production:}} && \quad \times\; \eta_J\, d^J_{\nu,\tau-\lambda'_k}\!\left(\hat\theta_{k(1)}\right)\, H^{0\to(ij),k}_{\tau,\lambda_k'}\,(-1)^{j_k-\lambda_k'} \\ {\color{LightGray}\text{decay:}} && \quad \times\; \eta_s\, d^s_{\tau,\lambda'_i-\lambda_j'}\!\left(\theta_{ij}\right)\, H^{(ij)\to i,j}_{\lambda'_i,\lambda'_j}\,(-1)^{j_j-\lambda_j'} \\ {\color{LightGray}\text{rotations:}} && \quad \times\; d^{j_1}_{\lambda'_1,\lambda_1}\!\left(\zeta^1_{k(0)}\right)\, d^{j_2}_{\lambda'_2,\lambda_2}\!\left(\zeta^2_{k(0)}\right)\, d^{j_3}_{\lambda'_3,\lambda_3}\!\left(\zeta^3_{k(0)}\right). \end{eqnarray*}\end{split}\]

Notice the general structure:

• Summations: The outer sum is taken over the three decay chain combinations \((ij)k \in \left\{(23)1, (31)2, (12)3\right\}\). Next, we sum over the spin magnitudes \(s\) of all resonances[1], the corresponding allowed helicities \(\tau\), and allowed spin projections \(\{\lambda'\}\) of the final state.

• Dynamics: The function \(X_s\) only depends on a single Mandelstam variable and carries all the dynamical information about the decay chain. Typically, these are your \(K\)-matrix or Breit-Wigner lineshape functions.

• Isobars: There is a Wigner \(d\)-function and a helicity coupling \(H\) for each isobar in the three-body decay chain: the \(0\to(ij),k\) production node and the \((ij)\to i,j\) decay node. The argument of these Wigner \(d\)-functions are the polar angles. The factors \(\eta_J=\sqrt{2S+1}\) and \(\eta_s=\sqrt{2s+1}\) are normalization factors. The phase \((-1)^{j-\lambda}\) is added to both helicity couplings to convert to the Jacob-Wick particle-2 convention.[2] The convention treats the first and the second particle unequally, however, it enables the simple relation of the helicity couplings to the \(LS\) couplings explained below.

• Wigner rotations: The last three Wigner \(d\)-functions represent Wigner rotations that appear when rotating the boosted frames of the production and decay isobar amplitudes back to the space-fixed CM frame.

If \(k=1\), we have \(\hat\theta_{k(1)}=0\), so the Wigner \(d\) function for the production isobar reduces to a Kronecker delta, \(d^J_{\nu,\tau-\lambda'_k}\!\left(\hat\theta_{k(1)}\right) = \delta_{\nu,\tau-\lambda'_k}\).

Equation (1) is written in terms of helicity couplings, but can be rewritten in terms of \(LS\) couplings, using

\[\begin{split}\begin{eqnarray*} H^{0\to(ij),k}_{\tau,\lambda'_k} & = & \sum_{LS} H^{0\to(ij),k}_{LS} \sqrt{\frac{2L+1}{2J+1}} C^{S,\tau-\lambda'_k}_{s,\tau,j_k,-\lambda'_k} C^{J,\tau-\lambda'_k}_{L,0,S,\tau-\lambda'_k} \\ H^{(ij)\to i,j}_{\lambda'_i,\lambda'_j} & = & \sum_{l's'} H^{0\to(ij),k}_{l's'} \sqrt{\frac{2l'+1}{2s+1}} C^{s',\lambda'_i-\lambda'_j}_{j_i,\lambda'_i,j_j,-\lambda'_j} C^{s,\lambda'_i-\lambda'_j}_{l',0,s',\lambda'_i-\lambda'_j}\,. \end{eqnarray*}\end{split}\]

The dynamics function is dependent on the \(LS\) values and we write \(X_s^{LS;l's'}\) instead of \(X_s\).

Examples

• Λ_c⁺ → p π⁺ K⁻
• J/ψ → K⁰ Σ⁺ p̅
• Ξ_b⁻ → p K⁻ K⁻
• Model serialization

• Comparison with AmpForm
  • D⁰ → K⁰ K⁺ K⁻
  • J/ψ → π⁰ π⁺ π⁻
  • J/ψ → φ(1020) π⁺ π⁻

---

[1]

Alternatively, one can sum over all resonances themselves, so that one has a dynamic function \(X_\mathcal{R}(\sigma_k)\) for each resonance \(\mathcal{R}\) in subsystem \(k\).

[2]

See also [2], Section 2.1.