DOC: add 1D projects of Dalitz plot (#15)

* DOC: add `jax`, `matplotlib`, and `tensorwaves` to intersphinx mapping
* DOC: improve wording around lineshape definitions
* DOC: switch to linear scale
* DOC: use correct scales for Dalitz plot
* DOC: warn about final state IDs in J/ψ → K⁰Σ⁺p̅ QRules figure
* FIX: hide input cell of form factor
* FIX: remove redundant f-strings

.cspell.json

@@ -47,6 +47,7 @@
     "caplog",
     "codecov",
     "codemirror",
+    "colorbar",
     "commitlint",
     "concat",
     "docnb",
@@ -64,8 +65,10 @@
     "mathrm",
     "maxdepth",
     "meshgrid",
+    "nansum",
     "nbconvert",
     "nbformat",
+    "ncols",
     "noreply",
     "pandoc",
     "pbar",
@@ -75,9 +78,11 @@
     "prereleased",
     "pygments",
     "redeboer",
+    "sharey",
     "startswith",
     "textwrap",
     "toctree",
+    "wspace",
     "xlabel",
     "xreplace",
     "xrightarrow",

docs/conf.py

@@ -122,11 +122,14 @@ def generate_api() -> None:
 html_title = "Symbolic Dalitz-Plot Decomposition"
 intersphinx_mapping = {
     "IPython": ("https://ipython.readthedocs.io/en/stable", None),
-    "ampform": (f"https://ampform.readthedocs.io/en/stable", None),
+    "ampform": ("https://ampform.readthedocs.io/en/stable", None),
     "attrs": ("https://www.attrs.org/en/stable", None),
-    "compwa-org": (f"https://compwa-org.readthedocs.io", None),
+    "compwa-org": ("https://compwa-org.readthedocs.io", None),
+    "jax": ("https://jax.readthedocs.io/en/latest", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
     "python": ("https://docs.python.org/3", None),
     "sympy": ("https://docs.sympy.org/latest", None),
+    "tensorwaves": ("https://tensorwaves.readthedocs.io/en/stable", None),
 }
 linkcheck_anchors = False
 linkcheck_ignore = [

docs/jpsi2ksp.ipynb

@@ -45,7 +45,6 @@
     "    make_commutative,\n",
     ")\n",
     "from IPython.display import Latex, Markdown\n",
-    "from matplotlib.colors import LogNorm\n",
     "from tensorwaves.function.sympy import create_function\n",
     "\n",
     "from ampform_dpd import (\n",
@@ -80,7 +79,11 @@
    "source": [
     "We follow [this example](https://qrules.readthedocs.io/en/0.9.7/usage.html#investigate-intermediate-resonances), which was generated with QRules, and leave out the $K$-resonances:\n",
     "\n",
-    "![](https://qrules.readthedocs.io/en/0.9.7/_images/usage_9_0.svg)"
+    "![](https://qrules.readthedocs.io/en/0.9.7/_images/usage_9_0.svg)\n",
+    "\n",
+    ":::{warning}\n",
+    "In the above figure, the final states are labeled `0`, `1`, `2`, but in the DPD formalism, the final states are labeled `1`, `2`, `3`.\n",
+    ":::"
    ]
   },
   {
@@ -260,7 +263,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In the following, we define symbols for relativistic Breit-Wigner functions and form factors as follows:"
+    "In the following, we define the **relativistic Breit-Wigner function** as:"
    ]
   },
   {
@@ -270,7 +273,9 @@
     "jupyter": {
      "source_hidden": true
     },
-    "tags": []
+    "tags": [
+     "hide-input"
+    ]
    },
    "outputs": [],
    "source": [
@@ -309,7 +314,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "with $\\Gamma_0(s)$ a {class}`~ampform.dynamics.EnergyDependentWidth`, and"
+    "with $\\Gamma_0(s)$ a {class}`~ampform.dynamics.EnergyDependentWidth`, and we define the **form factor** as:"
    ]
   },
   {
@@ -519,7 +524,9 @@
     "jupyter": {
      "source_hidden": true
     },
-    "tags": []
+    "tags": [
+     "hide-input"
+    ]
    },
    "outputs": [],
    "source": [
@@ -669,6 +676,19 @@
     "func = create_function(dalitz_expression, backend=\"jax\")"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "remove-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "%config InlineBackend.figure_formats = ['png']"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -682,21 +702,65 @@
    },
    "outputs": [],
    "source": [
+    "plt.rc(\"font\", size=18)\n",
     "resolution = 500\n",
     "X, Y = jnp.meshgrid(\n",
-    "    jnp.linspace(1.4, 1.93, num=resolution),\n",
-    "    jnp.linspace(1.65, 2.2, num=resolution),\n",
+    "    jnp.linspace(1.66**2, 2.18**2, num=resolution),\n",
+    "    jnp.linspace(1.4**2, 1.93**2, num=resolution),\n",
     ")\n",
     "data = {\n",
-    "    \"sigma2\": X**2,\n",
-    "    \"sigma3\": Y**2,\n",
+    "    \"sigma3\": X,\n",
+    "    \"sigma2\": Y,\n",
     "}\n",
     "intensities = func(data)\n",
-    "\n",
-    "fig, ax = plt.subplots(figsize=(12, 10))\n",
-    "ax.pcolormesh(X, Y, intensities, norm=LogNorm())\n",
-    "ax.set_xlabel(R\"$M\\left(K^0\\bar{p}\\right)$\")\n",
-    "ax.set_ylabel(R\"$M\\left(K^0\\Sigma^+\\right)$\")\n",
+    "normalized_intensities = intensities / jnp.nansum(intensities)\n",
+    "\n",
+    "fig, ax = plt.subplots(figsize=(14, 10))\n",
+    "mesh = ax.pcolormesh(X, Y, normalized_intensities)\n",
+    "ax.set_aspect(\"equal\")\n",
+    "c_bar = plt.colorbar(mesh, ax=ax, pad=0.01)\n",
+    "c_bar.ax.set_ylabel(\"Normalized intensity (a.u.)\")\n",
+    "ax.set_xlabel(R\"$M^2\\left(K^0\\Sigma^+\\right)$\")\n",
+    "ax.set_ylabel(R\"$M^2\\left(K^0\\bar{p}\\right)$\")\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "remove-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "%config InlineBackend.figure_formats = ['svg']"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "jupyter": {
+     "source_hidden": true
+    },
+    "tags": [
+     "hide-input",
+     "full-width"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "plt.rc(\"font\", size=16)\n",
+    "fig, axes = plt.subplots(figsize=(18, 6), ncols=2, sharey=True)\n",
+    "fig.subplots_adjust(wspace=0.02)\n",
+    "ax1, ax2 = axes\n",
+    "ax1.fill_between(jnp.sqrt(X[0]), jnp.nansum(normalized_intensities, axis=0))\n",
+    "ax2.fill_between(jnp.sqrt(Y[:, 0]), jnp.nansum(normalized_intensities, axis=1))\n",
+    "ax1.set_ylabel(\"Normalized intensity (a.u.)\")\n",
+    "ax1.set_xlabel(R\"$M\\left(K^0\\Sigma^+\\right)$\")\n",
+    "ax2.set_xlabel(R\"$M\\left(K^0\\bar{p}\\right)$\")\n",
     "plt.show()"
    ]
   }