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!

conda env create
conda activate ampform-dpd

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

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

Here, $\mathrm{\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_{\{\lambda \}}^{\nu }$ 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 }_{{}_{\mathrm{\Lambda },{\mathrm{\Lambda }}^{\prime }}}$ for the spin projections $\mathrm{\Lambda }$ of the initial state,

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

Notice the general structure:

• Summations: The outer sum is taken over the three decay chain combinations $(ij)k\in \{(23)1,(31)2,(12)3\}$. Next, we sum over the spin magnitudes $s$ of all resonances[1], the corresponding allowed helicities $\tau$, and allowed spin projections $\{{\lambda }^{\prime }\}$ 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_{\nu ,\tau -{\lambda }_k^{\prime }}^J\left({\hat{\theta }}_{k(1)}\right)={\delta }_{\nu ,\tau -{\lambda }_k^{\prime }}$.

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

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

Examples#