{
 "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
    },
    "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.io import 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$ function into the amplitude model in case there is more than one underlying {class}`~qrules.topology.Topology`. It is easiest to see this by inspecting the resulting {attr}`.HelicityModel.intensity` and its {attr}`~.HelicityModel.amplitudes`:"
   ]
  },
  {
   "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": [
    "'Spin alignment' can be now switched off or on by setting {attr}`.HelicityAmplitudeBuilder.align_spin`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "full-width"
    ]
   },
   "outputs": [],
   "source": [
    "builder = ampform.get_builder(reaction)\n",
    "builder.align_spin = True\n",
    "model = builder.formulate()\n",
    "model.intensity"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "source_hidden": true
    },
    "tags": [
     "full-width",
     "hide-input"
    ]
   },
   "outputs": [],
   "source": [
    "latex = sp.multiline_latex(\n",
    "    sp.Symbol(\"I\"),\n",
    "    model.intensity.evaluate(),\n",
    "    environment=\"eqnarray\",\n",
    ")\n",
    "Math(latex)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This also introduces several **Wigner rotation angles** to the {attr}`.HelicityModel.kinematic_variables`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "alpha = sp.Symbol(\"alpha_0^01\", real=True)\n",
    "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 TR-015.\n",
    "\n",
    "By default, {attr}`~.HelicityAmplitudeBuilder.align_spin` is set to {obj}`False` and the total {attr}`.HelicityModel.intensity` does not contain alignment Wigner-$D$ functions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "builder.align_spin = False\n",
    "non_aligned_model = builder.formulate()\n",
    "non_aligned_model.intensity"
   ]
  }
 ],
 "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.8.17"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}