Welcome to AmpForm!

Welcome to AmpForm!#

10.5281/zenodo.5526648 Supported Python versions Google Colab Binder

AmpForm automatically formulates amplitude models for arbitrary particle transitions in order to do a partial-waves analysis. All allowed transitions between some initial and final state are generated with the qrules package. You can then use ampform to formulate these state transitions into an amplitude model with some formalism, like the helicity formalism.

Flexible partial-wave decomposition

Scan which resonances are allowed for a given particle decay, then formulate the amplitude model automatically with the spin formalism of your choice.

Formulate amplitude model
Narrow the gap between code and theory

AmpForm amplitude models are formulated symbolically with SymPy, so that you can easily inspect the mathematical expressions and modify then algebraically.

https://compwa.github.io/symbolics
Adjust and modify the model to your needs

Customize dynamics lineshapes in the amplitude builder, for instance if you needsome additional background terms, without having to tweak the entire framework.

Custom dynamics
Convert to several computational back-ends

The amplitude models are converted to computational back-ends like JAX, TensorFlow, and NumPy. The TensorWaves package facilitates this and also provides tools to generate toy Monte Carlo data samples.

https://tensorwaves.rtfd.io
Use your favorite Python packages

All this functionality is offered in an open and transparent style, so that you can navigate AmpForm’s output and feed it to whatever other Python packages come in handy for you. For instance, check out inspect the model interactively to see how to inspect your model with an interactive widget.

ampform

The following pages provide more advanced examples of how to use AmpForm. You can run each of them as Jupyter notebooks with the launch button in the top-right corner.

Dynamics parametrizations#

AmpForm offers a number of functions for parametrizing dynamics lineshapes. The functions are expressed with sympy, so that they can easily be visualized, simplified, or modified:

import sympy as sp

from ampform.dynamics import relativistic_breit_wigner

m, m0, w0 = sp.symbols("m m0 Gamma0")
relativistic_breit_wigner(s=m**2, mass0=m0, gamma0=w0)
\[\displaystyle \frac{\Gamma_{0} m_{0}}{- i \Gamma_{0} m_{0} - m^{2} + m_{0}^{2}}\]
from ampform.dynamics import relativistic_breit_wigner_with_ff

m1, m2, L = sp.symbols("m1 m2 L")
relativistic_breit_wigner_with_ff(
    s=m**2,
    mass0=m0,
    gamma0=w0,
    m_a=m1,
    m_b=m2,
    angular_momentum=L,
    meson_radius=1,
)
\[\displaystyle \frac{\Gamma_{0} m_{0} \mathcal{F}_{L}\left(m^{2}, m_{1}, m_{2}\right)}{- m^{2} + m_{0}^{2} - i m_{0} \Gamma_{0}\left(m^{2}\right)}\]
from ampform.dynamics.kmatrix import NonRelativisticKMatrix

n_poles = sp.Symbol("n_R", integer=True, positive=True)
NonRelativisticKMatrix.formulate(
    n_poles=n_poles,
    n_channels=1,
)[0, 0]
\[\displaystyle \frac{i \sum_{R=1}^{n_{R}} \frac{\Gamma_{R, 0} \gamma_{R, 0}^{2} m_{R}}{- s + m_{R}^{2}}}{\sum_{R=1}^{n_{R}} \frac{\Gamma_{R, 0} \gamma_{R, 0}^{2} m_{R}}{- s + m_{R}^{2}} + i}\]
matrix = NonRelativisticKMatrix.formulate(n_poles=1, n_channels=2)
matrix[0, 0].doit().simplify()
\[\displaystyle - \frac{\Gamma_{1, 0} \gamma_{1, 0}^{2} m_{1}}{s + i \Gamma_{1, 0} \gamma_{1, 0}^{2} m_{1} + i \Gamma_{1, 1} \gamma_{1, 1}^{2} m_{1} - m_{1}^{2}}\]

More dynamics functions can be found in the dynamics library, as well as on the Dynamics page!

Formulate amplitude models#

Together with QRules, AmpForm can automatically formulate amplitude models for generic, multi-body decays. These models can then be used as templates for faster computational back-ends with TensorWaves. Here’s an example:

import qrules

reaction = qrules.generate_transitions(
    initial_state=("psi(4160)", [-1, +1]),
    final_state=["D-", "D0", "pi+"],
    allowed_intermediate_particles=["D*(2007)0"],
    formalism="helicity",
)

import ampform
from ampform.dynamics.builder import create_relativistic_breit_wigner

builder = ampform.get_builder(reaction)
for particle in reaction.get_intermediate_particles():
    builder.dynamics.assign(particle.name, create_relativistic_breit_wigner)
model = builder.formulate()
model.intensity
\[\displaystyle \sum_{m_{A}\in\left\{1,-1\right\}} \sum_{m_{0}=0} \sum_{m_{1}=0} \sum_{m_{2}=0}{\left|{A^{02}_{m_{A}, m_{0}, m_{1}, m_{2}}}\right|^{2}}\]

Hide code cell source

 
from ampform.io import aslatex

(symbol, expr), *_ = model.amplitudes.items()
Math(aslatex({symbol: expr}, terms_per_line=1))
\[\begin{split}\displaystyle \begin{aligned} A^{02}_{-1, 0, 0, 0} \;&=\; \frac{C_{\psi(4160) \to D^{*}(2007)^{0}_{+1} D^{0}_{0}; D^{*}(2007)^{0} \to D^{-}_{0} \pi^{+}_{0}} \Gamma_{D^{*}(2007)^{0}} m_{D^{*}(2007)^{0}} D^{1}_{-1,1}\left(- \phi_{02},\theta_{02},0\right) D^{1}_{1,0}\left(- \phi^{02}_{0},\theta^{02}_{0},0\right)}{- i \Gamma_{D^{*}(2007)^{0}} m_{D^{*}(2007)^{0}} - m_{02}^{2} + \left(m_{D^{*}(2007)^{0}}\right)^{2}} \\ \;&+\; \frac{C_{\psi(4160) \to D^{*}(2007)^{0}_{-1} D^{0}_{0}; D^{*}(2007)^{0} \to D^{-}_{0} \pi^{+}_{0}} \Gamma_{D^{*}(2007)^{0}} m_{D^{*}(2007)^{0}} D^{1}_{-1,-1}\left(- \phi_{02},\theta_{02},0\right) D^{1}_{-1,0}\left(- \phi^{02}_{0},\theta^{02}_{0},0\right)}{- i \Gamma_{D^{*}(2007)^{0}} m_{D^{*}(2007)^{0}} - m_{02}^{2} + \left(m_{D^{*}(2007)^{0}}\right)^{2}} \\ \;&+\; \frac{C_{\psi(4160) \to D^{*}(2007)^{0}_{0} D^{0}_{0}; D^{*}(2007)^{0} \to D^{-}_{0} \pi^{+}_{0}} \Gamma_{D^{*}(2007)^{0}} m_{D^{*}(2007)^{0}} D^{1}_{-1,0}\left(- \phi_{02},\theta_{02},0\right) D^{1}_{0,0}\left(- \phi^{02}_{0},\theta^{02}_{0},0\right)}{- i \Gamma_{D^{*}(2007)^{0}} m_{D^{*}(2007)^{0}} - m_{02}^{2} + \left(m_{D^{*}(2007)^{0}}\right)^{2}} \\ \end{aligned}\end{split}\]

In case of multiple decay topologies, AmpForm also takes care of spin alignment with [Marangotto, 2020]!

reaction = qrules.generate_transitions(
    initial_state="Lambda(c)+",
    final_state=["p", "K-", "pi+"],
    allowed_intermediate_particles=[
        "Lambda(1405)",
        "Delta(1232)++",
    ],
)

Hide code cell source

 
import graphviz

dot = qrules.io.asdot(reaction, collapse_graphs=True)
graphviz.Source(dot)
_images/94f33103f3de86678634dd4a26edf4390204c6964ba92236b5c3c2554c93afc7.svg 
builder = ampform.get_builder(reaction)
model = builder.formulate()
model.intensity
\[\displaystyle \sum_{m_{A}=-1/2}^{1/2} \sum_{m_{0}=-1/2}^{1/2} \sum_{m_{1}=0} \sum_{m_{2}=0}{\left|{A^{01}_{m_{A}, m_{0}, m_{1}, m_{2}} + A^{02}_{m_{A}, m_{0}, m_{1}, m_{2}}}\right|^{2}}\]

Tip

Amplitude models for three-body decays that involve spin in the final state are best formulated with the AmpForm-DPD extension.

Advanced examples#

The following pages provide more advanced examples of how to use AmpForm.