ComPWA · Leongrim · Nov 19, 2021 · Nov 17, 2021 · Nov 17, 2021 · Nov 17, 2021
diff --git a/.cspell.json b/.cspell.json
@@ -134,6 +134,7 @@
         "dtype",
         "einsum",
         "epem",
+        "eqnarray",
         "eval",
         "evalf",
         "expertsystem",

diff --git a/docs/usage.ipynb b/docs/usage.ipynb
@@ -253,6 +253,7 @@
     "usage/visualize\n",
     "usage/conservation\n",
     "usage/custom-topology\n",
+    "usage/ls-coupling\n",
     "```"
    ]
   }

diff --git a/docs/usage/ls-coupling.ipynb b/docs/usage/ls-coupling.ipynb
@@ -0,0 +1,330 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "hideCode": true,
+    "hideOutput": true,
+    "hidePrompt": true,
+    "jupyter": {
+     "source_hidden": true
+    },
+    "slideshow": {
+     "slide_type": "skip"
+    },
+    "tags": [
+     "remove-cell"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "%%capture\n",
+    "%config Completer.use_jedi = False\n",
+    "%config InlineBackend.figure_formats = ['svg']\n",
+    "import os\n",
+    "\n",
+    "STATIC_WEB_PAGE = {\"EXECUTE_NB\", \"READTHEDOCS\"}.intersection(os.environ)\n",
+    "\n",
+    "# Install on Google Colab\n",
+    "import subprocess\n",
+    "import sys\n",
+    "\n",
+    "from IPython import get_ipython\n",
+    "\n",
+    "install_packages = \"google.colab\" in str(get_ipython())\n",
+    "if install_packages:\n",
+    "    for package in [\"qrules[doc]\", \"graphviz\"]:\n",
+    "        subprocess.check_call(\n",
+    "            [sys.executable, \"-m\", \"pip\", \"install\", package]\n",
+    "        )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# LS-couplings"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The {func}`.spin_conservation` rule is one of the more complicated checks in the {mod}`.conservation_rules` module. It provides an implementation of $LS$-couplings, which is a procedure to determine which values for **total angular momentum $L$** and **coupled spin $S$** are allowed in an interaction node. In this notebook, we illustrate this procedure with the following decay chain as an example:\n",
+    "\n",
+    "$$\n",
+    "J/\\psi \\to \\Sigma^+ \\bar\\Sigma(1670)^-, \\quad \\bar\\Sigma(1670)^- \\rightarrow \\bar p K^0.\n",
+    "$$\n",
+    "\n",
+    "In this decay chain, there are two decay nodes that we investigate separately. In addition, both decays are mediated interactions by the strong force, which means there is also **parity conservation**.\n",
+    "\n",
+    "In the following derivations, the {attr}`.Particle.spin` and {attr}`.Particle.parity` values are of importance:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "jupyter": {
+     "source_hidden": true
+    },
+    "tags": [
+     "hide-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "from IPython.display import Math\n",
+    "\n",
+    "import qrules\n",
+    "\n",
+    "PDG = qrules.load_pdg()\n",
+    "particle_names = [\n",
+    "    \"J/psi(1S)\",\n",
+    "    \"Sigma+\",\n",
+    "    \"Sigma(1670)~-\",\n",
+    "    \"p~\",\n",
+    "    \"K0\",\n",
+    "]\n",
+    "latex_expressions = []\n",
+    "for name in particle_names:\n",
+    "    particle = PDG[name]\n",
+    "    parity = \"+\" if particle.parity > 0 else \"-\"\n",
+    "    if particle.spin.is_integer():\n",
+    "        spin = int(particle.spin)\n",
+    "    else:\n",
+    "        nominator = int(particle.spin * 2)\n",
+    "        spin = fR\"\\tfrac{{{nominator}}}{2}\"\n",
+    "    latex_expressions.append(f\"{particle.latex}={spin}^{parity}\")\n",
+    "Math(R\"\\qquad \".join(latex_expressions))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Procedure"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Imagine we have a two-body decay of $p_0\\rightarrow p_1p_2$. We denote the {attr}`.Spin.magnitude` of each particle $p_i$ as $s_i$ and their {attr}`~.Particle.parity` as $\\eta_i$. The values for $L$ and $S$ can now be determined as follows:\n",
+    "\n",
+    "1. Determine all values for $S$ that satisfy $\\left| s_1-s_2 \\right| \\le S \\le s_1+s_2$. The difference between each value for $S$ has to integer, so $S = \\left| s_1-s_2 \\right|, \\left| s_1-s_2 \\right|+1, \\dots, s_1+s_2$.\n",
+    "2. Determine all values for $L$ that satisfy $\\left| L-S \\right| \\le s_0 \\le L+S$, with $L$ being a non-negative integer.\n",
+    "3. If there is parity conservation, $L$ has to satisfy an additional constraint: $\\eta_0 = \\eta_1\\cdot\\eta_2\\cdot(-1)^L$."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## $J/\\psi \\to \\Sigma^+\\bar\\Sigma(1670)^-$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The spin and parity of each particle in the first transition can be summarized as $1^-\\to\\frac{1}{2}^+\\frac{3}{2}^+$. Following step 1 in the {ref}`procedure <usage/ls-coupling:procedure>`, we get:\n",
+    "\n",
+    "$$\n",
+    "\\begin{eqnarray}\n",
+    "\\left|s_{\\Sigma^+} - s_{\\bar\\Sigma(1670)^-}\\right| & \\le S & \\le s_{\\Sigma^+} + s_{\\bar\\Sigma(1670)^-} \\\\\n",
+    "\\left|\\tfrac{1}{2}-\\tfrac{3}{2}\\right| & \\le S & \\le \\tfrac{1}{2} + \\tfrac{3}{2} \\\\\n",
+    "1 & \\le S & \\le 2\n",
+    "\\end{eqnarray}\n",
+    "$$\n",
+    "\n",
+    "$$\n",
+    "\\Rightarrow S=1 \\quad \\text{or} \\quad S=2\n",
+    "$$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Next, we determine the allowed total angular momentum values $L$ with {ref}`step 2 <usage/ls-coupling:procedure>`:\n",
+    "\n",
+    "$$\n",
+    "\\begin{eqnarray}\n",
+    "|L-S| & \\le s_{J/\\psi} & \\le L+S \\\\\n",
+    "|L-S| & \\le 1 & \\le L+S\n",
+    "\\end{eqnarray}\n",
+    "$$\n",
+    "\n",
+    "$$\n",
+    "\\Rightarrow \\begin{cases}\n",
+    "L=0,1,2 & \\text{if} & S=1\\\\\n",
+    "L=1,2,3 & \\text{if} & S=2.\n",
+    "\\end{cases}\n",
+    "$$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "So in total, we have 6 $LS$-combinations:\n",
+    "\n",
+    "$$\n",
+    "(L,S) = (0,1), (1,1), (2,1), (1,2), (2,2), (3,2).\n",
+    "$$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This decay however goes via the strong force. This means that parity has to be conserved and we have to follow {ref}`step 3 <usage/ls-coupling:procedure>`:\n",
+    "\n",
+    "$$\n",
+    "\\begin{eqnarray}\n",
+    "\\eta_{J/\\psi} & = & \\eta_{\\Sigma^+} \\cdot \\eta_{\\bar\\Sigma(1670)^-} \\cdot(-1)^L \\\\\n",
+    "(-1) & = & (+1)\\cdot(+1)\\cdot(-1)^L \\\\\n",
+    "(-1) & = & (-1)^{L}.\n",
+    "\\end{eqnarray}\n",
+    "$$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "From this, we can easily see that only odd $L$ values are possible, which leaves us with **3 $LS$-combinations**:\n",
+    "\n",
+    "$$\n",
+    "(L,S) = (1,1), (1,2), (3,2).\n",
+    "$$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## $\\bar \\Sigma(1670)^-\\to \\bar pK^0$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The second part of the decay chain can be expressed as $\\frac{3}{2}^+ \\to \\frac{1}{2}^- 0^-$. Following {ref}`step 1 <usage/ls-coupling:procedure>`, we see:\n",
+    "\n",
+    "$$\n",
+    "\\begin{eqnarray}\n",
+    "|s_{\\bar p} - s_{K^0}| & \\le S  & \\le s_{\\bar p} + s_{K^0} \\\\\n",
+    "\\left|\\tfrac{1}{2}-0 \\right| & \\le S & \\le \\tfrac{1}{2} + 0\n",
+    "\\end{eqnarray}\n",
+    "$$\n",
+    "\n",
+    "$$\n",
+    "\\Rightarrow S = \\tfrac{1}{2}.\n",
+    "$$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This time, only one coupled spin value is allowed. That allows for the following values of $L$:\n",
+    "\n",
+    "$$\n",
+    "\\begin{eqnarray}\n",
+    "|L-S| & \\le s_0 & \\le L+S \\\\\n",
+    "\\left|L-\\tfrac{1}{2}\\right| & \\le \\tfrac{3}{2} & \\le L+\\tfrac{1}{2}.\n",
+    "\\end{eqnarray}\n",
+    "$$\n",
+    "\n",
+    "$$\n",
+    "\\Rightarrow L = 1,2\n",
+    "$$\n",
+    "\n",
+    "By now, only two $LS$-combinations are possible:\n",
+    "\n",
+    "$$\n",
+    "(L,S)=\\left(1,\\tfrac{1}{2}\\right), \\left(2,\\tfrac{1}{2}\\right).\n",
+    "$$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This again is a strong interaction, which means we have to check for parity conservation.\n",
+    "\n",
+    "$$\n",
+    "\\begin{eqnarray}\n",
+    "    \\eta_{\\bar \\Sigma(1670)^-} & = & \\eta_{\\bar p}\\cdot\\eta_{K^0}\\cdot(-1)^L\\\\\n",
+    "    (+1) & = & (-1)\\cdot(-1)\\cdot(-1)^L\\\\\n",
+    "    (+1) & = & (-1)^L.\n",
+    "\\end{eqnarray}\n",
+    "$$\n",
+    "\n",
+    "Again, it is clear that only even $L$'s are allowed. This means that **only one $LS$-combination** is possible:\n",
+    "\n",
+    "$$\n",
+    "(L,S)=\\left(2,\\tfrac{1}{2}\\right)\n",
+    "$$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Check with QRules"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Finally, let's use {func}`.generate_transitions` to check whether the allowed $LS$-couplings are found by {mod}`qrules` as well. Note that we have to increase the maximum angular momentum to find the $(L,S)=(3,2)$ combination as well."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "jupyter": {
+     "source_hidden": true
+    },
+    "tags": [
+     "hide-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "import logging\n",
+    "\n",
+    "import graphviz\n",
+    "\n",
+    "LOGGER = logging.getLogger()\n",
+    "LOGGER.setLevel(logging.ERROR)\n",
+    "\n",
+    "reaction = qrules.generate_transitions(\n",
+    "    initial_state=\"J/psi(1S)\",\n",
+    "    final_state=[\"K0\", \"Sigma+\", \"p~\"],\n",
+    "    allowed_intermediate_particles=[\"Sigma(1670)\"],\n",
+    "    allowed_interaction_types=\"strong\",\n",
+    "    max_angular_momentum=3,\n",
+    ")\n",
+    "dot = qrules.io.asdot(reaction, render_node=True, strip_spin=True)\n",
+    "graphviz.Source(dot)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}
diff --git a/src/qrules/conservation_rules.py b/src/qrules/conservation_rules.py
@@ -735,6 +735,8 @@ def spin_conservation(
 
     Also checks :math:`M_1 + M_2 = M` and if Clebsch-Gordan coefficients
     are all 0.
+
+    .. seealso:: /docs/usage/ls-coupling
     """
     # L and S can only be used if one side is a single state
     # and the other side contains of two states (isobar)