phasespace

import ampform.dynamics.phasespace

Different parametrizations of phase space factors.

Phase space factors are computed by integrating over the phase space element given by PDG2026, Eq. (49.12). See also PDG2026, Eq. (50.11). This integral is not always easy to solve, which leads to different parametrizations.

This module provides several parametrizations. They all comply with the PhaseSpaceFactorProtocol, so that they can be used in parametrizations like EnergyDependentWidth.

class PhaseSpaceFactorProtocol(*args, **kwargs)

Bases: Protocol

Protocol that is used by EnergyDependentWidth.

Follow this Protocol when defining other implementations of a phase space. Even functions like BreakupMomentum comply with this protocol, but are technically speaking not phase space factors.

__call__(s, m1, m2) → Expr

Expected signature.

Parameters:

• s – Mandelstam variable \(s\). Commonly, this is just \(s = m_R^2\), with \(m_R\) the invariant mass of decaying particle \(R\).

• m1 – Mass of decay product \(a\).

• m2 – Mass of decay product \(b\).

class PhaseSpaceFactor(s, m1, m2, name, *args, evaluate: bool = False, **kwargs)

Bases: Expr

Standard phase-space factor, using a definition consistent with BreakupMomentum.

See PDG2026, Eq. (50.11). We ignore the factor \(\frac{1}{16\pi}\) as done in [Chung and Klempt, 1995], p.5.

Similarly to BreakupMomentum, this class represents the numerator as a single square root for better numerical performance. This comes at the cost of a more complicated cut structure when the function is continued to the complex plane.

Alternative implementations:

• PhaseSpaceFactorAbs

• PhaseSpaceFactorComplex

• PhaseSpaceFactorKallen

• PhaseSpaceFactorSplitSqrt

• PhaseSpaceFactorSWave

(1)\[\begin{split} \begin{aligned} \rho\left(s\right) \;&=\; \frac{\sqrt{\left(s - \left(m_{1} - m_{2}\right)^{2}\right) \left(s - \left(m_{1} + m_{2}\right)^{2}\right)}}{s} \\ \end{aligned}\end{split}\]

property func: type

Return a class-valued constructor preserving non-sympy arguments.

SymPy’s type queries require a class, while downstream dispatch compares it with the original class. Constructed instances retain their original type and pickle representation.

class PhaseSpaceFactorAbs(s, m1, m2, name, *args, evaluate: bool = False, **kwargs)

Bases: Expr

Phase space factor with square root over the absolute value.

As opposed to PhaseSpaceFactor, this takes the square root of the Abs value of BreakupMomentumSquared.

This version of the phase space factor is often denoted as \(\hat{\rho}\) and is used in EqualMassPhaseSpaceFactor.

(2)\[\begin{split} \begin{aligned} \hat{\rho}\left(s\right) \;&=\; \frac{2 \sqrt{\left|{q^2\left(s\right)}\right|}}{\sqrt{s}} \\ \end{aligned}\end{split}\]

with \(q^2\left(s\right)\) defined by BreakupMomentumSquared.

property func: type

Return a class-valued constructor preserving non-sympy arguments.

SymPy’s type queries require a class, while downstream dispatch compares it with the original class. Constructed instances retain their original type and pickle representation.

class PhaseSpaceFactorComplex(s, m1, m2, name, *args, evaluate: bool = False, **kwargs)

Bases: Expr

Phase-space factor with ComplexSqrt.

Same as PhaseSpaceFactorSplitSqrt, but using a ComplexSqrt that does have defined behavior for defined for negative input values along the real axis.

(3)\[\begin{split} \begin{aligned} \rho^\mathrm{c}\left(s\right) \;&=\; \frac{\sqrt[\mathrm{c}]{s - \left(m_{1} - m_{2}\right)^{2}} \sqrt[\mathrm{c}]{s - \left(m_{1} + m_{2}\right)^{2}}}{s} \\ \end{aligned}\end{split}\]

with \(\sqrt[\mathrm{c}]{x}\) defined by ComplexSqrt.

property func: type

Return a class-valued constructor preserving non-sympy arguments.

SymPy’s type queries require a class, while downstream dispatch compares it with the original class. Constructed instances retain their original type and pickle representation.

class PhaseSpaceFactorKallen(s, m1, m2, name, *args, evaluate: bool = False, **kwargs)

Bases: Expr

Phase-space factor that is the equivalent of BreakupMomentumKallen.

(4)\[\begin{split} \begin{aligned} \rho\left(s\right) \;&=\; \frac{\sqrt{\lambda\left(s, m_{1}^{2}, m_{2}^{2}\right)}}{s} \\ \end{aligned}\end{split}\]

with \(\lambda\left(x, y, z\right)\) defined by Kallen.

property func: type

Return a class-valued constructor preserving non-sympy arguments.

SymPy’s type queries require a class, while downstream dispatch compares it with the original class. Constructed instances retain their original type and pickle representation.

class PhaseSpaceFactorSplitSqrt(s, m1, m2, name, *args, evaluate: bool = False, **kwargs)

Bases: Expr

Phase-space factor that is the equivalent of BreakupMomentumSplitSqrt.

This version of the PhaseSpaceFactor represents the numerator as two separate square roots. This results in a cleaner cut structure at the cost of slightly worse numerical performance than PhaseSpaceFactor.

(5)\[\begin{split} \begin{aligned} \rho\left(s\right) \;&=\; \frac{\sqrt{s - \left(m_{1} - m_{2}\right)^{2}} \sqrt{s - \left(m_{1} + m_{2}\right)^{2}}}{s} \\ \end{aligned}\end{split}\]

property func: type

Return a class-valued constructor preserving non-sympy arguments.

SymPy’s type queries require a class, while downstream dispatch compares it with the original class. Constructed instances retain their original type and pickle representation.

class PhaseSpaceFactorSWave(s, m1, m2, name, *args, evaluate: bool = False, **kwargs)

Bases: Expr

Phase space factor using ChewMandelstamSWave().

This PhaseSpaceFactor provides an analytic continuation for decay products with both equal and unequal masses (compare EqualMassPhaseSpaceFactor). Following PDG2026, §50.3.3, the Chew–Mandelstam function \(\Sigma(s)\) replaces \(i\rho(s)\), so this class returns \(-i\Sigma(s)\).

(6)\[\begin{split} \begin{aligned} \rho^\mathrm{CM}\left(s\right) \;&=\; - i \hat{\Sigma}_0\left(s\right) \\ \end{aligned}\end{split}\]

with \(\hat{\Sigma}_0\left(s\right)\) defined by ChewMandelstamSWave.

property func: type

Return a class-valued constructor preserving non-sympy arguments.

SymPy’s type queries require a class, while downstream dispatch compares it with the original class. Constructed instances retain their original type and pickle representation.

class ChewMandelstamSWave(s, m1, m2, name, *args, evaluate: bool = False, **kwargs)

Bases: Expr

Chew–Mandelstam class for \(S\)-waves (no angular momentum).

See PDG2021, Eq. (50.40). As in PhaseSpaceFactor, we ignore the factor \(\frac{1}{16\pi}\).

As a trick, the square root in \(q\) is defined with ComplexSqrt so that this function has a well-defined behavior along the negative real axis.

Warning

This function is given as PDG2026, Eq. (50.46), which contains two apparent typos: the denominator inside the first logarithm reads \(2m_1m_1\) instead of \(2m_1m_2\), and the last term contains \(1/s_\mathrm{thr}^2\) instead of \(1/s_\mathrm{thr}=1/(m_1+m_2)^2\). This implementation follows the 2021 version.

(7)\[\begin{split} \begin{aligned} \hat{\Sigma}_0\left(s\right) \;&=\; \frac{\frac{2 q^\mathrm{c}\left(s\right)}{\sqrt{s}} \log{\left(\frac{m_{1}^{2} + m_{2}^{2} + 2 \sqrt{s} q^\mathrm{c}\left(s\right) - s}{2 m_{1} m_{2}} \right)} - \left(m_{1}^{2} - m_{2}^{2}\right) \left(- \frac{1}{\left(m_{1} + m_{2}\right)^{2}} + \frac{1}{s}\right) \log{\left(\frac{m_{1}}{m_{2}} \right)}}{\pi} \\ \end{aligned}\end{split}\]

with \(q^\mathrm{c}\left(s\right)\) defined by BreakupMomentumComplex.

property func: type

Return a class-valued constructor preserving non-sympy arguments.

SymPy’s type queries require a class, while downstream dispatch compares it with the original class. Constructed instances retain their original type and pickle representation.

class PhaseSpaceFactorPWave(s, m1, m2, meson_radius, s_prime, epsilon, name, algorithm, configuration, dummify, *args, evaluate: bool = False, **kwargs)

Bases: Expr

Phase space factor using ChewMandelstamIntegral for \(\ell=1\).

Parameters:

• s – Mandelstam variable s.

• m1 – Mass of particle 1.

• m2 – Mass of particle 2.

• meson_radius – Meson radius, default is 1 (optional).

• s_prime – Integration variable defaults to ‘x’ (optional).

• epsilon – Small imaginary part to offset from the real axis (optional).

• **kwargs – See NumericalIntegral for more details on the remaining parameters.

Warning

This PhaseSpaceFactor uses the numerical dispersion integral implemented in ChewMandelstamIntegral (via NumericalIntegral). As such, you have to be careful when lambdifying this function and evaluating this over an array.

>>> import numpy as np
>>> from ampform.dynamics.phasespace import PhaseSpaceFactorPWave
>>> s, m1, m2 = sp.symbols("s m_1 m_2")
>>> rho_expr = PhaseSpaceFactorPWave(s, m1, m2, epsilon=1e-5)
>>> rho_func = sp.lambdify((s, m1, m2), rho_expr.doit())
>>> s_values = np.linspace(0.1, 4.0, num=4)
>>> rho_func(s_values, 0.14, 0.98).real
array([-4.08315012e-07,  8.05561163e-03,  2.65015019e-01,  5.43083429e-01])

(8)\[\begin{split} \begin{aligned} \rho^\mathrm{CM,1}\left(s\right) \;&=\; - i \Sigma_{1}\left(s\right) \\ \end{aligned}\end{split}\]

with \(\Sigma_{\ell}\left(s\right)\) defined by ChewMandelstamIntegral.

algorithm: str | None

See NumericalIntegral.algorithm.

configuration: dict[str, Any] | None

See NumericalIntegral.configuration.

dummify: bool

Whether to dummify the integration variable. See NumericalIntegral.dummify.

property func: type

Return a class-valued constructor preserving non-sympy arguments.

SymPy’s type queries require a class, while downstream dispatch compares it with the original class. Constructed instances retain their original type and pickle representation.

class ChewMandelstamIntegral(s, m1, m2, angular_momentum, meson_radius, s_prime, epsilon, name, algorithm, configuration, dummify, *args, evaluate: bool = False, **kwargs)

Bases: Expr

Dispersion integral for obtaining the analytic phase space factor for angular momenta L>0.

See PDG2026, Eq. (50.45). The integral is subtracted at the channel threshold.

Parameters:

• s – Mandelstam variable s.

• m1 – Mass of particle 1.

• m2 – Mass of particle 2.

• angular_momentum – Angular momentum.

• meson_radius – Meson radius, default is 1 (optional).

• s_prime – Integration variable defaults to ‘x’ (optional).

• epsilon – Small imaginary part to offset from the real axis (optional).

• **kwargs – See NumericalIntegral for more details on the remaining parameters.

(9)\[\begin{split} \begin{aligned} \Sigma_{\ell}\left(s\right) \;&=\; \frac{s - \left(m_{1} + m_{2}\right)^{2}}{\pi} \int\limits_{\left(m_{1} + m_{2}\right)^{2}}^{\infty} \frac{\hat{\mathcal{F}}_{\ell}\left(x, m_{1}, m_{2}\right)^{2} \rho\left(x\right)}{\left(x - \left(m_{1} + m_{2}\right)^{2}\right) \left(- i \epsilon - s + x\right)}\, dx \\ \end{aligned}\end{split}\]

with \(\hat{\mathcal{F}}_{\ell}\left(x, m_{1}, m_{2}\right)\) defined by FormFactor and \(\rho\left(x\right)\) defined by PhaseSpaceFactor.

algorithm: str | None

See NumericalIntegral.algorithm.

configuration: dict[str, Any] | None

See NumericalIntegral.configuration.

dummify: bool

Whether to dummify the integration variable. See NumericalIntegral.dummify.

property func: type

Return a class-valued constructor preserving non-sympy arguments.

SymPy’s type queries require a class, while downstream dispatch compares it with the original class. Constructed instances retain their original type and pickle representation.

class EqualMassPhaseSpaceFactor(s, m1, m2, name, *args, evaluate: bool = False, **kwargs)

Bases: Expr

Analytic continuation for the PhaseSpaceFactor.

See PDG2018, §Resonances, p.9 and Phase space factor definitions.

Warning: The PDG specifically derives this formula for a two-body decay with equal masses.

Warning

This formula no longer appears in PDG2026, §Resonances, p.16. The PDG now gives the \(S\)-wave Chew–Mandelstam function for arbitrary masses instead (Equation (50.46)), which is subtracted at the channel threshold. See ChewMandelstamSWave.

(10)\[\begin{split} \begin{aligned} \rho^\mathrm{eq}\left(s\right) \;&=\; \begin{cases} \frac{i \log{\left(\left|{\frac{\hat{\rho}\left(s\right) + 1}{\hat{\rho}\left(s\right) - 1}}\right| \right)} \hat{\rho}\left(s\right)}{\pi} & \text{for}\: s < 0 \\\frac{i \log{\left(\left|{\frac{\hat{\rho}\left(s\right) + 1}{\hat{\rho}\left(s\right) - 1}}\right| \right)} \hat{\rho}\left(s\right)}{\pi} + \hat{\rho}\left(s\right) & \text{for}\: s > \left(m_{1} + m_{2}\right)^{2} \\\frac{2 i \operatorname{atan}{\left(\frac{1}{\hat{\rho}\left(s\right)} \right)} \hat{\rho}\left(s\right)}{\pi} & \text{otherwise} \end{cases} \\ \end{aligned}\end{split}\]

with \(\hat{\rho}\left(s\right)\) defined by PhaseSpaceFactorAbs.

property func: type

Return a class-valued constructor preserving non-sympy arguments.

SymPy’s type queries require a class, while downstream dispatch compares it with the original class. Constructed instances retain their original type and pickle representation.