BREAK: convert chew_manelstam_s_wave() to expression class (#493)

* DOC: disable full-screen button on website
* DOC: improve phase space expressions in API
* DOC: update `README`
* DOC: use en-dash in names
* DX: make `_get_subscript()` positional only
* ENH: let `name` attribute overwrite function LaTeX
* FIX: remove redundant `typings/` directory
* MAINT: reduce number of declared variables
* MAINT: remove `pyright` comments

Author: redeboer

.cspell.json

@@ -35,8 +35,7 @@
     "CITATION.cff",
     "codecov.yml",
     "docs/conf.py",
-    "pyproject.toml",
-    "typings"
+    "pyproject.toml"
   ],
   "ignoreWords": [
     "Autoupdate",

README.md

@@ -43,15 +43,16 @@ an overview of **upcoming releases and planned functionality**, see
   - [Helicity formalism](https://ampform.readthedocs.io/en/stable/usage/helicity/formalism.html)
   - Canonical formalism
   - [Spin alignment](https://ampform.readthedocs.io/en/stable/usage/helicity/spin-alignment.html)
-    for generic, multi-body decays that feature different decay topologies
+    for generic, multi-body decays that feature different decay topologies. **See also [`ampform-dpd`](https://github.com/ComPWA/ampform-dpd)!**
 - **Dynamics**
-  - [Relativistic Breit-Wigner](https://ampform.readthedocs.io/en/stable/api/ampform.dynamics.html#ampform.dynamics.relativistic_breit_wigner_with_ff),
+  - [Relativistic Breit–Wigner](https://ampform.readthedocs.io/en/stable/api/ampform.dynamics.html#ampform.dynamics.relativistic_breit_wigner_with_ff),
     optionally with form factors and/or
     [energy-dependent width](https://ampform.readthedocs.io/en/stable/api/ampform.dynamics.html#ampform.dynamics.EnergyDependentWidth)
   - [Symbolic _K_-matrix](https://ampform.readthedocs.io/en/stable/usage/dynamics/k-matrix.html#non-relativistic-k-matrix)
     for an arbitrary number of poles and channels
   - [Symbolic _P_-vector](https://ampform.readthedocs.io/en/stable/usage/dynamics/k-matrix.html#p-vector)
     for an arbitrary number of poles and channels
+  - Chew–Mandelstam dispersion integral for a correct treatment of analyticity in the presence of thresholds.
 
 ## Contribute
 

docs/_extend_docstrings.py

@@ -11,17 +11,24 @@
 import textwrap
 from importlib.metadata import version as get_package_version
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 import attrs
 import graphviz  # sphinx.ext.graphviz does not work well on RTD
 import qrules
 import sympy as sp
 from sympy.printing.numpy import NumPyPrinter
 
+from ampform.dynamics.form_factor import FormFactor
 from ampform.dynamics.phasespace import (
+    ChewMandelstamIntegral,
+    ChewMandelstamSWave,
+    EqualMassPhaseSpaceFactor,
     PhaseSpaceFactor,
+    PhaseSpaceFactorAbs,
+    PhaseSpaceFactorComplex,
     PhaseSpaceFactorKallen,
+    PhaseSpaceFactorPWave,
     PhaseSpaceFactorSplitSqrt,
     PhaseSpaceFactorSWave,
 )
@@ -33,9 +40,11 @@
     BreakupMomentumKallen,
     BreakupMomentumSplitSqrt,
     BreakupMomentumSquared,
+    Kallen,
 )
 from ampform.sympy._array_expressions import ArrayMultiplication
 from ampform.sympy._cache import get_readable_hash, make_hashable
+from ampform.sympy.math import ComplexSqrt
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -49,15 +58,107 @@
 
 
 def append_phsp_doit(
-    phsp_factor: PhaseSpaceFactorProtocol,
-    wide: bool = True,
-) -> Callable[[], None]:
-    def _extend() -> None:
-        s, m1, m2 = sp.symbols("s m1 m2", nonnegative=True)
-        expr = phsp_factor(s, m1, m2)
-        _append_latex_doit_definition(expr, full_width=wide)
+    _phsp_factor: PhaseSpaceFactorProtocol,
+    *,
+    extra_args: list[sp.Symbol] | None = None,
+    subexpression: list[sp.Expr] | sp.Expr | None = None,
+    wide: bool = False,
+) -> None:
+    expr = _phsp_factor(s, m1, m2, *(extra_args or []))
+    _append_latex_doit_definition(expr, full_width=wide)
+    if subexpression is not None:
+        if not isinstance(subexpression, list):
+            subexpression = [subexpression]
+        items = []
+        for expr in subexpression:
+            expression_type = f"{type(expr).__name__}"
+            items.append(f":math:`{sp.latex(expr)}` defined by `.{expression_type}`")
+        match len(items):
+            case 1:
+                appended_text = items[0]
+            case 2:
+                appended_text = f"{items[0]} and {items[1]}"
+            case _:
+                appended_text = ", ".join(items[:-1]) + f", and {items[-1]}"
+        _append_to_docstring(_phsp_factor, f"\n\nwith {appended_text}.")
+
+
+def _append_latex_doit_definition(
+    expr: sp.Expr,
+    deep: bool = False,
+    full_width: bool = False,
+    inline: bool = False,
+) -> None:
+    if inline:
+        return _append_to_docstring(
+            type(expr),
+            f":math:`{sp.latex(expr)}={sp.latex(expr.doit(deep=deep))}`",
+        )
+    latex = _create_latex_doit_definition(expr, deep)
+    extras = ""
+    if full_width:
+        extras = """
+        :class: full-width
+        """
+    return _append_to_docstring(
+        type(expr),
+        f"""\n
+    .. math::
+        :label: {type(expr).__name__}{extras}
+
+        {latex}
+    """,
+    )
+
+
+def _append_to_docstring(class_type: Callable | type, appended_text: str) -> None:
+    appended_text = textwrap.dedent(appended_text)
+    if class_type.__doc__ is None:
+        class_type.__doc__ = appended_text
+    else:
+        class_type.__doc__ += appended_text
 
-    return _extend
+
+def _create_latex_doit_definition(expr: sp.Expr, deep: bool = False) -> str:
+    latex = aslatex({expr: expr.doit(deep=deep)})
+    return textwrap.indent(latex, prefix=8 * " ")
+
+
+s, m1, m2, x, y, z = cast("list[sp.Symbol]", sp.symbols("s m1 m2 x:z"))
+ell = sp.Symbol("ell", integer=True, nonnegative=True)
+append_phsp_doit(BreakupMomentum)
+append_phsp_doit(BreakupMomentumComplex, subexpression=ComplexSqrt(x))
+append_phsp_doit(BreakupMomentumKallen, subexpression=Kallen(x, y, z))
+append_phsp_doit(BreakupMomentumSplitSqrt)
+append_phsp_doit(BreakupMomentumSquared)
+append_phsp_doit(
+    EqualMassPhaseSpaceFactor,
+    subexpression=PhaseSpaceFactorAbs(s, m1, m2),
+)
+append_phsp_doit(PhaseSpaceFactor)
+append_phsp_doit(PhaseSpaceFactorAbs, subexpression=BreakupMomentumSquared(s, m1, m2))
+append_phsp_doit(PhaseSpaceFactorComplex, subexpression=ComplexSqrt(x))
+append_phsp_doit(PhaseSpaceFactorKallen, subexpression=Kallen(x, y, z))
+append_phsp_doit(PhaseSpaceFactorSplitSqrt)
+append_phsp_doit(
+    ChewMandelstamSWave,
+    subexpression=BreakupMomentumComplex(s, m1, m2),
+    wide=True,
+)
+append_phsp_doit(
+    ChewMandelstamIntegral,
+    extra_args=[ell],
+    subexpression=[FormFactor(x, m1, m2, ell), PhaseSpaceFactor(x, m1, m2)],
+    wide=True,
+)
+append_phsp_doit(
+    PhaseSpaceFactorSWave,
+    subexpression=ChewMandelstamSWave(s, m1, m2),
+)
+append_phsp_doit(
+    PhaseSpaceFactorPWave,
+    subexpression=ChewMandelstamIntegral(s, m1, m2, ell),
+)
 
 
 def extend_docstrings() -> None:
@@ -83,17 +184,6 @@ def extend_docstrings() -> None:
         definition()
 
 
-extend_BreakupMomentum = append_phsp_doit(BreakupMomentum)
-extend_BreakupMomentumComplex = append_phsp_doit(BreakupMomentumComplex)
-extend_BreakupMomentumKallen = append_phsp_doit(BreakupMomentumKallen)
-extend_BreakupMomentumSplitSqrt = append_phsp_doit(BreakupMomentumSplitSqrt)
-extend_BreakupMomentumSquared = append_phsp_doit(BreakupMomentumSquared)
-extend_PhaseSpaceFactor = append_phsp_doit(PhaseSpaceFactor)
-extend_PhaseSpaceFactorKallen = append_phsp_doit(PhaseSpaceFactorKallen)
-extend_PhaseSpaceFactorSplitSqrt = append_phsp_doit(PhaseSpaceFactorSplitSqrt)
-extend_PhaseSpaceFactorSWave = append_phsp_doit(PhaseSpaceFactorSWave, wide=True)
-
-
 def extend_BlattWeisskopfSquared() -> None:
     from ampform.dynamics.form_factor import BlattWeisskopfSquared, SphericalHankel1
 
@@ -205,17 +295,7 @@ def extend_BoostZMatrix() -> None:
     )
 
 
-def extend_ChewMandelstamIntegral() -> None:
-    from ampform.dynamics.phasespace import ChewMandelstamIntegral
-
-    s, m_a, m_b, ell = sp.symbols(R"s m_a m_b \ell")
-    expr = ChewMandelstamIntegral(s, m_a, m_b, ell)
-    _append_latex_doit_definition(expr)
-
-
 def extend_ComplexSqrt() -> None:
-    from ampform.sympy.math import ComplexSqrt
-
     x = sp.Symbol("x", real=True)
     expr = ComplexSqrt(x)
     _append_to_docstring(
@@ -245,25 +325,6 @@ def extend_compute_third_mandelstam() -> None:
     )
 
 
-def extend_EqualMassPhaseSpaceFactor() -> None:
-    from ampform.dynamics.phasespace import (
-        EqualMassPhaseSpaceFactor,
-        PhaseSpaceFactorAbs,
-    )
-
-    s, m_a, m_b = sp.symbols(R"s, m_a, m_b")
-    expr = EqualMassPhaseSpaceFactor(s, m_a, m_b)
-    _append_latex_doit_definition(expr)
-    rho_hat = PhaseSpaceFactorAbs(s, m_a, m_b)
-    _append_to_docstring(
-        EqualMassPhaseSpaceFactor,
-        f"""
-    with :math:`{sp.latex(rho_hat)}` defined by `.PhaseSpaceFactorAbs`
-    :eq:`PhaseSpaceFactorAbs`.
-    """,
-    )
-
-
 def extend_EnergyDependentWidth() -> None:
     from ampform.dynamics import EnergyDependentWidth
 
@@ -275,8 +336,7 @@ def extend_EnergyDependentWidth() -> None:
     """,
     )
     L = sp.Symbol("L", integer=True)
-    symbols: tuple[sp.Symbol, ...] = sp.symbols("s m0 Gamma0 m_a m_b")
-    s, m0, w0, m_a, m_b = symbols
+    s, m0, w0, m_a, m_b = sp.symbols("s m0 Gamma0 m_a m_b")
     expr = EnergyDependentWidth(
         s=s,
         mass0=m0,
@@ -328,15 +388,12 @@ def extend_EuclideanNorm() -> None:
 
 
 def extend_FormFactor() -> None:
-    from ampform.dynamics.form_factor import FormFactor
-
     s, m_a, m_b, L, d = sp.symbols("s m_a m_b L d")
     form_factor = FormFactor(s, m_a, m_b, angular_momentum=L, meson_radius=d)
     _append_latex_doit_definition(form_factor)
 
 
 def extend_Kallen() -> None:
-    from ampform.kinematics.phasespace import Kallen
 
     x, y, z = sp.symbols("x:z")
     expr = Kallen(x, y, z)
@@ -390,34 +447,6 @@ def extend_is_within_phasespace() -> None:
     )
 
 
-def extend_PhaseSpaceFactorAbs() -> None:
-    from ampform.dynamics.phasespace import PhaseSpaceFactorAbs
-
-    s, m_a, m_b = sp.symbols("s, m_a, m_b")
-    expr = PhaseSpaceFactorAbs(s, m_a, m_b)
-    _append_latex_doit_definition(expr)
-    _append_to_docstring(
-        PhaseSpaceFactorAbs,
-        """
-    with :math:`q^2(s)` defined as :eq:`BreakupMomentumSquared`.
-    """,
-    )
-
-
-def extend_PhaseSpaceFactorComplex() -> None:
-    from ampform.dynamics.phasespace import PhaseSpaceFactorComplex
-
-    s, m_a, m_b = sp.symbols("s, m_a, m_b")
-    expr = PhaseSpaceFactorComplex(s, m_a, m_b)
-    _append_latex_doit_definition(expr)
-    _append_to_docstring(
-        PhaseSpaceFactorComplex,
-        """
-    with :math:`q^2(s)` defined as :eq:`BreakupMomentumSquared`.
-    """,
-    )
-
-
 def extend_Phi() -> None:
     from ampform.kinematics.angles import Phi
 
@@ -510,26 +539,6 @@ def extend_ThreeMomentum() -> None:
     _append_code_rendering(expr)
 
 
-def extend_chew_mandelstam_s_wave() -> None:
-    from ampform.dynamics.phasespace import chew_mandelstam_s_wave
-
-    s, m_a, m_b = sp.symbols("s m_a m_b")
-    expr = chew_mandelstam_s_wave(s, m_a, m_b)
-    _append_to_docstring(
-        chew_mandelstam_s_wave,
-        Rf"""
-
-    .. math:: {sp.latex(expr)}
-        :class: full-width
-        :label: chew_mandelstam_s_wave
-
-    with :math:`q^2(s)` defined as :eq:`BreakupMomentumSquared`.
-
-    .. seealso:: :doc:`compwa-report:003/index`
-    """,
-    )
-
-
 def extend_formulate_isobar_cg_coefficients() -> None:
     from ampform.helicity import formulate_isobar_cg_coefficients
 
@@ -645,7 +654,7 @@ def extend_relativistic_breit_wigner_with_ff() -> None:
     _append_to_docstring(
         relativistic_breit_wigner_with_ff,
         Rf"""
-    The general form of a relativistic Breit-Wigner with Blatt-Weisskopf form factor is:
+    The general form of a relativistic Breit–Wigner with Blatt–Weisskopf form factor is:
 
     .. math:: {sp.latex(rel_bw_with_ff)}
         :label: relativistic_breit_wigner_with_ff
@@ -696,47 +705,6 @@ def __get_text_width(text: str) -> int:
     return max(widths)
 
 
-def _append_latex_doit_definition(
-    expr: sp.Expr,
-    deep: bool = False,
-    full_width: bool = False,
-    inline: bool = False,
-) -> None:
-    if inline:
-        return _append_to_docstring(
-            type(expr),
-            f":math:`{sp.latex(expr)}={sp.latex(expr.doit(deep=deep))}`",
-        )
-    latex = _create_latex_doit_definition(expr, deep)
-    extras = ""
-    if full_width:
-        extras = """
-        :class: full-width
-        """
-    return _append_to_docstring(
-        type(expr),
-        f"""\n
-    .. math::
-        :label: {type(expr).__name__}{extras}
-
-        {latex}
-    """,
-    )
-
-
-def _create_latex_doit_definition(expr: sp.Expr, deep: bool = False) -> str:
-    latex = aslatex({expr: expr.doit(deep=deep)})
-    return textwrap.indent(latex, prefix=8 * " ")
-
-
-def _append_to_docstring(class_type: Callable | type, appended_text: str) -> None:
-    appended_text = textwrap.dedent(appended_text)
-    if class_type.__doc__ is None:
-        class_type.__doc__ = appended_text
-    else:
-        class_type.__doc__ += appended_text
-
-
 def __generate_transitions_cached(
     initial_state: list[tuple[str, list[float]] | str],
     final_state: list[tuple[str, list[float]] | str],

docs/conf.py

@@ -275,6 +275,7 @@ def _get_scipy_url() -> str:
     "show_toc_level": 2,
     "use_download_button": False,
     "use_edit_page_button": True,
+    "use_fullscreen_button": False,
     "use_issues_button": True,
     "use_repository_button": True,
     "use_source_button": True,