DOC: switch to author-year citation style

.cspell.json

@@ -244,6 +244,7 @@
     "hankel",
     "helicities",
     "helicity",
+    "Hippel",
     "htmlcov",
     "imap",
     "ipynb",

docs/_extend_docstrings.py

@@ -63,12 +63,19 @@ def extend_docstrings() -> None:
 
 
 def extend_BlattWeisskopfSquared() -> None:
-    from ampform.dynamics.form_factor import BlattWeisskopfSquared
+    from ampform.dynamics.form_factor import BlattWeisskopfSquared, SphericalHankel1
 
-    z = sp.Symbol("z", real=True)
-    L = sp.Symbol("L", integer=True)
+    z = sp.Symbol("z", nonnegative=True, real=True)
+    L = sp.Symbol("L", integer=True, nonnegative=True)
     expr = BlattWeisskopfSquared(z, angular_momentum=L)
-    _append_latex_doit_definition(expr, deep=True, full_width=True)
+    h1lz = SphericalHankel1(L, z)
+    _append_latex_doit_definition(expr)
+    _append_to_docstring(
+        BlattWeisskopfSquared,
+        f"""\n
+    where :math:`{sp.latex(h1lz)}` is defined by :eq:`SphericalHankel1`.
+    """,
+    )
 
 
 def extend_BoostMatrix() -> None:
@@ -472,6 +479,15 @@ def extend_RotationZMatrix() -> None:
     )
 
 
+def extend_SphericalHankel1() -> None:
+    from ampform.dynamics.form_factor import SphericalHankel1
+
+    z = sp.Symbol("z", nonnegative=True, real=True)
+    ell = sp.Symbol(R"\ell", integer=True, nonnegative=True)
+    expr = SphericalHankel1(ell, z)
+    _append_latex_doit_definition(expr)
+
+
 def extend_Theta() -> None:
     from ampform.kinematics.angles import Theta
 

docs/bibliography.bib

@@ -187,19 +187,24 @@ @misc{meyerMatrixTutorial2008
   url = {http://www.curtismeyer.com/talks/PWA_Munich_KMatrix.pdf}
 }
 
-@phdthesis{pychyGekoppeltePartialwellenanalyseAnnihilationen2016,
-  title = {{Gekoppelte Partialwellenanalyse von 𝑝̅𝑝-Annihilationen im Fluge in die Endzustände 𝐾⁺𝐾⁻𝜋⁰, 𝜋⁰𝜋⁰𝜂 und 𝜋⁰𝜂𝜂}},
-  author = {Pychy, Julian},
-  year = {2016},
-  month = apr,
-  url = {https://hss-opus.ub.ruhr-uni-bochum.de/opus4/frontdoor/deliver/index/docId/4943/file/diss.pdf},
-  school = {Ruhr-Universität Bochum}
-}
-
 @misc{richmanExperimenterGuideHelicity1984,
   title = {An {{Experimenter}}'s {{Guide}} to the {{Helicity Formalism}}},
   author = {Richman, Jeffrey D.},
   year = {1984},
   month = jun,
   url = {https://inspirehep.net/literature/202987}
 }
+
+@article{VonHippel:1972fg,
+  title = {Centrifugal-{{Barrier Effects}} in {{Resonance Partial Decay Widths}}, {{Shapes}}, and {{Production Amplitudes}}},
+  author = {{von Hippel}, Frank and Quigg, C.},
+  year = {1972},
+  month = feb,
+  journal = {Physical Review D},
+  volume = {5},
+  number = {3},
+  pages = {624--638},
+  issn = {0556-2821},
+  doi = {10.1103/PhysRevD.5.624},
+  url = {https://link.aps.org/doi/10.1103/PhysRevD.5.624}
+}

docs/conf.py

@@ -109,6 +109,7 @@
 autosectionlabel_prefix_document = True
 bibtex_bibfiles = ["bibliography.bib"]
 bibtex_default_style = "unsrt_et_al"
+bibtex_reference_style = "author_year"
 codeautolink_concat_default = True
 codeautolink_global_preface = """
 import numpy

src/ampform/dynamics/form_factor.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any, ClassVar
+from typing import Any
 
 import sympy as sp
 
@@ -11,8 +11,7 @@
 
 @unevaluated
 class BlattWeisskopfSquared(sp.Expr):
-    # cspell:ignore asner pychyGekoppeltePartialwellenanalyseAnnihilationen
-    r"""Blatt-Weisskopf function :math:`B_L^2(z)`, up to :math:`L \leq 8`.
+    r"""Normalized Blatt-Weisskopf function :math:`B_L^2(z)`, with :math:`B_L^2(1)=1`.
 
     Args:
         z: Argument of the Blatt-Weisskopf function :math:`B_L^2(z)`. A usual
@@ -22,95 +21,64 @@ class BlattWeisskopfSquared(sp.Expr):
         angular_momentum: Angular momentum :math:`L` of the decaying particle.
 
     Note that equal powers of :math:`z` appear in the nominator and the denominator,
-    while some sources have nominator :math:`1`, instead of :math:`z^L`. Compare for
-    instance Equation (50.27) in :pdg-review:`2021; Resonances; p.9`.
+    while some sources define an *non-normalized* form factor :math:`F_L` with :math:`1`
+    in the nominator, instead of :math:`z^L`. See for instance Equation (50.27) in
+    :pdg-review:`2021; Resonances; p.9`. We normalize the form factor such that
+    :math:`B_L^2(1)=1` and that :math:`B_L^2` is unitless no matter what :math:`z` is.
 
-    Each of these cases for :math:`L` has been taken from
-    :cite:`pychyGekoppeltePartialwellenanalyseAnnihilationen2016`, p.59,
-    :cite:`chungPartialWaveAnalysis1995`, p.415, and
-    :cite:`chungFormulasAngularMomentumBarrier2015`. For a good overview of where to use
-    these Blatt-Weisskopf functions, see :cite:`asnerDalitzPlotAnalysis2006`.
+    .. seealso:: :ref:`usage/dynamics:Form factor`, :doc:`TR-029<compwa:report/029>`,
+      and :cite:`chungFormulasAngularMomentumBarrier2015`.
 
-    See also :ref:`usage/dynamics:Form factor`.
+    With this, the implementation becomes
     """
 
     z: Any
     angular_momentum: Any
     _latex_repr_ = R"B_{{{angular_momentum}}}^2\left({z}\right)"
 
-    max_angular_momentum: ClassVar[int | None] = None
-    """Limit the maximum allowed angular momentum :math:`L`.
+    def evaluate(self) -> sp.Expr:
+        z, angular_momentum = self.args
+        return (
+            sp.Abs(SphericalHankel1(angular_momentum, 1)) ** 2
+            / sp.Abs(SphericalHankel1(angular_momentum, sp.sqrt(z))) ** 2
+            / z
+        )
+
+
+@unevaluated(implement_doit=False)
+class SphericalHankel1(sp.Expr):
+    r"""Spherical Hankel function of the first kind for real-valued :math:`z`.
+
+    See :cite:`VonHippel:1972fg`, Equation (A12), and :doc:`TR-029<compwa:report/029>`
+    for more info. `This page
+    <https://mathworld.wolfram.com/SphericalHankelFunctionoftheFirstKind.html>`_
+    explains the difference with the *general* Hankel function of the first kind,
+    :math:`H_\ell^{(1)}`.
 
-    This improves performance when :math:`L` is a `~sympy.core.symbol.Symbol` and you
-    are note interested in higher angular momenta.
+    This expression class assumes that :math:`z` is real and evaluates to the following
+    series:
     """
 
+    l: Any  # noqa: E741
+    z: Any
+    _latex_repr_ = R"h_{{{l}}}^{{(1)}}\left({z}\right)"
+
+    def doit(self, deep: bool = True, **kwargs):
+        expr = self.evaluate()
+        if deep and isinstance(self.l, sp.Integer):
+            return expr.doit()
+        return expr
+
     def evaluate(self) -> sp.Expr:
-        z: sp.Expr = self.args[0]  # type: ignore[assignment]
-        angular_momentum: sp.Expr = self.args[1]  # type: ignore[assignment]
-        cases: dict[int, sp.Expr] = {
-            0: sp.S.One,
-            1: 2 * z / (z + 1),
-            2: 13 * z**2 / ((z - 3) * (z - 3) + 9 * z),
-            3: 277 * z**3 / (z * (z - 15) * (z - 15) + 9 * (2 * z - 5) * (2 * z - 5)),
-            4: (
-                12746
-                * z**4
-                / (
-                    (z**2 - 45 * z + 105) * (z**2 - 45 * z + 105)
-                    + 25 * z * (2 * z - 21) * (2 * z - 21)
-                )
-            ),
-            5: (
-                998881
-                * z**5
-                / (z**5 + 15 * z**4 + 315 * z**3 + 6300 * z**2 + 99225 * z + 893025)
-            ),
-            6: (
-                118394977
-                * z**6
-                / (
-                    z**6
-                    + 21 * z**5
-                    + 630 * z**4
-                    + 18900 * z**3
-                    + 496125 * z**2
-                    + 9823275 * z
-                    + 108056025
-                )
-            ),
-            7: (
-                19727003738
-                * z**7
-                / (
-                    z**7
-                    + 28 * z**6
-                    + 1134 * z**5
-                    + 47250 * z**4
-                    + 1819125 * z**3
-                    + 58939650 * z**2
-                    + 1404728325 * z
-                    + 18261468225
-                )
-            ),
-            8: (
-                4392846440677
-                * z**8
-                / (
-                    z**8
-                    + 36 * z**7
-                    + 1890 * z**6
-                    + 103950 * z**5
-                    + 5457375 * z**4
-                    + 255405150 * z**3
-                    + 9833098275 * z**2
-                    + 273922023375 * z
-                    + 4108830350625
-                )
-            ),
-        }
-        return sp.Piecewise(*[
-            (expression, sp.Eq(angular_momentum, value))
-            for value, expression in cases.items()
-            if self.max_angular_momentum is None or value <= self.max_angular_momentum
-        ])
+        l, z = self.args  # noqa: E741
+        k = sp.Dummy("k", integer=True, nonnegative=True)
+        return (
+            (-sp.I) ** (1 + l)  # type:ignore[operator]
+            * (sp.exp(z * sp.I) / z)
+            * sp.Sum(
+                sp.factorial(l + k)
+                / (sp.factorial(l - k) * sp.factorial(k))
+                * (sp.I / (2 * z)) ** k,  # type:ignore[operator]
+                (k, 0, l),
+            )
+        )