docs/usage/helicity/spin-alignment.ipynb

{
 "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",
     "skip-execution"
    ]
   },
   "outputs": [],
   "source": [
    "# WARNING: advised to install a specific version, e.g. ampform==0.1.2\n",
    "%pip install -q ampform[doc,viz] IPython"
   ]
  },
  {
   "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": [
    "import os\n",
    "\n",
    "STATIC_WEB_PAGE = {\"EXECUTE_NB\", \"READTHEDOCS\"}.intersection(os.environ)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```{autolink-concat}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Spin alignment"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "mystnb": {
     "code_prompt_show": "Import Python libraries"
    },
    "tags": [
     "hide-cell"
    ]
   },
   "outputs": [],
   "source": [
    "import logging\n",
    "\n",
    "import graphviz\n",
    "import qrules\n",
    "import sympy as sp\n",
    "from IPython.display import Math\n",
    "\n",
    "import ampform\n",
    "from ampform.helicity import HelicityModel\n",
    "from ampform.io import aslatex, improve_latex_rendering\n",
    "\n",
    "LOGGER = logging.getLogger()\n",
    "LOGGER.setLevel(logging.ERROR)\n",
    "improve_latex_rendering()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As described in {doc}`compwa:report/015`, the {doc}`'standard' helicity formalism </usage/helicity/formalism>` is not suited for state transitions that have different decay topologies. For this reason, the {class}`.HelicityAmplitudeBuilder` can insert a number of Wigner-$D$ functions into the amplitude model to 'align' the final state spins of underlying {class}`~qrules.topology.Topology` instances in the full decay.\n",
    "\n",
    "Imagine we have the following the decay:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "reaction = qrules.generate_transitions(\n",
    "    initial_state=(\"J/psi(1S)\", [-1, +1]),\n",
    "    final_state=[\"K0\", \"Sigma+\", \"p~\"],\n",
    "    allowed_intermediate_particles=[\"Sigma(1660)\", \"N(1650)\"],\n",
    "    allowed_interaction_types=[\"strong\"],\n",
    "    formalism=\"helicity\",\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "tags": [
     "hide-input"
    ]
   },
   "outputs": [],
   "source": [
    "src = qrules.io.asdot(\n",
    "    reaction,\n",
    "    collapse_graphs=True,\n",
    "    render_initial_state_id=True,\n",
    ")\n",
    "graphviz.Source(src)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This decay has **two** different decay topologies, that is, it has resonances in **two different sub-systems**. By default, the {class}`.HelicityAmplitudeBuilder` does not take these differing decay topologies into account and falls back aligning the amplitudes with {class}`.NoAlignment`. Explicitly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from ampform.helicity.align import NoAlignment\n",
    "\n",
    "builder = ampform.get_builder(reaction)\n",
    "builder.config.spin_alignment = NoAlignment()\n",
    "non_aligned_model = builder.formulate()\n",
    "non_aligned_model.intensity"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The symbols for the amplitudes are defined through {attr}`.HelicityModel.amplitudes`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "tags": [
     "full-width",
     "hide-input"
    ]
   },
   "outputs": [],
   "source": [
    "def render_amplitudes(model: HelicityModel) -> Math:\n",
    "    selected_amplitudes = {\n",
    "        symbol: expr\n",
    "        for i, (symbol, expr) in enumerate(model.amplitudes.items())\n",
    "        if i % 5 == 0\n",
    "    }\n",
    "    src = aslatex(selected_amplitudes, terms_per_line=1)\n",
    "    src = src.replace(R\"\\end{array}\", R\"\\dots \\\\ \\end{array}\")\n",
    "    return Math(src)\n",
    "\n",
    "\n",
    "render_amplitudes(non_aligned_model)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Dalitz-Plot Decomposition"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One way of aligning the spins of each sub-system, is Dalitz-Plot Decomposition (DPD) {cite}`Marangotto:2019ucc`. DPD **can only be used for three-body decays**, but results in a quite condense amplitude model expression.\n",
    "\n",
    "We can select DPD alignment as follows:\n",
    "\n",
    ":::{warning}\n",
    "The {class}`.DalitzPlotDecomposition` is not yet fully functional for reactions with a polarized initial or final state. In this example, the sums inside the incoherent sum should also include $\\lambda_0=0$.\n",
    ":::"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "full-width"
    ]
   },
   "outputs": [],
   "source": [
    "from ampform.helicity.align.dpd import DalitzPlotDecomposition, relabel_edge_ids\n",
    "\n",
    "reaction_123 = relabel_edge_ids(reaction)\n",
    "builder_123 = ampform.get_builder(reaction_123)\n",
    "builder_123.config.spin_alignment = DalitzPlotDecomposition(reference_subsystem=1)\n",
    "builder_123.config.scalar_initial_state_mass = True\n",
    "builder_123.config.stable_final_state_ids = [1, 2, 3]\n",
    "dpd_model = builder_123.formulate()\n",
    "dpd_model.intensity.cleanup()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::{warning}\n",
    "The {class}`.DalitzPlotDecomposition` formalism uses different indices for the initial and final state, so relabel the reaction with {func}`.relabel_edge_ids` first.\n",
    ":::"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "tags": [
     "hide-input"
    ]
   },
   "outputs": [],
   "source": [
    "src = qrules.io.asdot(\n",
    "    reaction_123,\n",
    "    collapse_graphs=True,\n",
    "    render_initial_state_id=True,\n",
    ")\n",
    "graphviz.Source(src)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This method introduces several new angles that are defined through the {attr}`~.HelicityModel.kinematic_variables`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "tags": [
     "hide-input"
    ]
   },
   "outputs": [],
   "source": [
    "dpd_angles = {\n",
    "    k: v for k, v in dpd_model.kinematic_variables.items() if \"zeta\" in str(k)\n",
    "}\n",
    "src = aslatex(dpd_angles)\n",
    "Math(src)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the amplitudes are the same as those in the non-aligned model:\n",
    "\n",
    ":::{warning}\n",
    "This behavior is a bug that will be fixed through [ComPWA/ampform#318](https://github.com/ComPWA/ampform/issues/318).\n",
    ":::"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "tags": [
     "full-width",
     "hide-input"
    ]
   },
   "outputs": [],
   "source": [
    "render_amplitudes(dpd_model)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Axis-angle method"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The second spin alignment method is the 'axis-angle method' {cite}`Marangotto:2019ucc`. This method results in much larger expressions and is therefore much less efficient, but theoretically it **can handle $n$-body final states**. It can be selected as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from ampform.helicity.align.axisangle import AxisAngleAlignment\n",
    "\n",
    "builder.config.spin_alignment = AxisAngleAlignment()\n",
    "axisangle_model = builder.formulate()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "tags": [
     "full-width",
     "hide-input"
    ]
   },
   "outputs": [],
   "source": [
    "Math(aslatex({\"I\": axisangle_model.intensity.evaluate()}, terms_per_line=1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This method of alignment introduces several **Wigner rotation angles** to the {attr}`.HelicityModel.kinematic_variables`. An example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "tags": [
     "full-width",
     "hide-input"
    ]
   },
   "outputs": [],
   "source": [
    "alpha = sp.Symbol(\"alpha_0^01\", real=True)\n",
    "Math(aslatex({alpha: axisangle_model.kinematic_variables[alpha]}))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more information about these angles, see {ref}`compwa:report/015:Compute Wigner rotation angles` in {doc}`TR-015 <compwa:report/015>`."
   ]
  }
 ],
 "metadata": {
  "colab": {
   "toc_visible": true
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}