release: 1.5.0

CHANGELOG.rst

@@ -2,19 +2,18 @@
 Changelog
 *********
 
-Develop
-==========
+
+1.5.0 (27 Nov 2021)
+===================
 
 
 Major Features and Improvements
 -------------------------------
+- add support to generate from a DecayChain using
+  `the decaylanguage <https://github.com/scikit-hep/decaylanguage>`_ package from Scikit-HEP.
+  This is in the new subpackage "fromdecay" and can be used by installing the extra with
+  ``pip install phasespace[fromdecay]``.
 
-Behavioral changes
-------------------
-
-
-Bug fixes and small changes
----------------------------
 
 Requirement changes
 -------------------
@@ -23,6 +22,7 @@ Requirement changes
 
 Thanks
 ------
+- to Simon Thor for contributing the ``fromdecay`` subpackage.
 
 1.4.2 (5.11.2021)
 ==================

docs/GenMultiDecay_Tutorial.ipynb

@@ -10,8 +10,11 @@
     }
    },
    "source": [
-    "# Tutorial for `GenMultiDecay` class\n",
-    "This tutorial shows how `phasespace.fromdecay.GenMultiDecay` can be used.\n",
+    "# Tutorial for *GenMultiDecay* class\n",
+    "This tutorial shows how ``phasespace.fromdecay.GenMultiDecay`` can be used.\n",
+    "\n",
+    "In order to use this functionality, you need to install the extra `fromdecay`, for example through\n",
+    "``pip install phasespace[fromdecay]``.\n",
     "\n",
     "This submodule makes it possible for `phasespace` and [`DecayLanguage`](https://github.com/scikit-hep/decaylanguage/) to work together.\n",
     "More generally, `GenMultiDecay` can also be used as a high-level interface for simulating particles that can decay in multiple different ways."
@@ -83,7 +86,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This `dict` can also be displayed in a more human-readable way using `DecayChainViewer`: "
+    "This `dict` can also be displayed in a more human-readable way using `DecayChainViewer`:"
    ]
   },
   {
@@ -155,16 +158,16 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We can confirm that the counts above are close to the expected counts based on the probabilities. "
+    "We can confirm that the counts above are close to the expected counts based on the probabilities."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Changing mass settings\n",
-    "Since DecayLanguage dicts do not contain any information about the mass of a particle, the `fromdecay` submodule uses the [particle](https://github.com/scikit-hep/particle) package to find the mass of a particle based on its name. \n",
-    "The mass can either be a constant value or a function (besides the top particle, which is always a constant). \n",
+    "Since DecayLanguage dicts do not contain any information about the mass of a particle, the `fromdecay` submodule uses the [particle](https://github.com/scikit-hep/particle) package to find the mass of a particle based on its name.\n",
+    "The mass can either be a constant value or a function (besides the top particle, which is always a constant).\n",
     "These settings can be modified by passing in additional parameters to `GenMultiDecay.from_dict`.\n",
     "There are two optional parameters that can be passed to `GenMultiDecay.from_dict`: `tolerance` and `mass_converter`.\n",
     "\n",
@@ -197,8 +200,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "$\\pi^0$ has a greater width than $D^0$. \n",
-    "If the tolerance is set to a value between their widths, the $D^0$ particle will have a constant mass while $\\pi^0$ will not.  "
+    "$\\pi^0$ has a greater width than $D^0$.\n",
+    "If the tolerance is set to a value between their widths, the $D^0$ particle will have a constant mass while $\\pi^0$ will not."
    ]
   },
   {
@@ -212,7 +215,7 @@
     "for particle in dstar_decay.gen_particles[0][1].children:\n",
     "    # If a particle width is less than tolerance or if it does not have any children, its mass will be fixed.\n",
     "    assert particle.has_fixed_mass\n",
-    "    \n",
+    "\n",
     "# Loop over D+ and pi0. See above.\n",
     "for particle in dstar_decay.gen_particles[1][1].children:\n",
     "    if particle.name == \"pi0\":\n",
@@ -263,7 +266,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The built-in supported mass function names are `gauss`, `bw`, and `relbw`, with `gauss` being the gaussian distribution, `bw` being the Breit-Wigner distribution, and `relbw` being the relativistic Breit-Wigner distribution. \n",
+    "The built-in supported mass function names are `gauss`, `bw`, and `relbw`, with `gauss` being the gaussian distribution, `bw` being the Breit-Wigner distribution, and `relbw` being the relativistic Breit-Wigner distribution.\n",
     "\n",
     "If a non-supported value for the `zfit` parameter is used or if it is not specified, it will automatically use the relativistic Breit-Wigner distribution. This behavior can be changed by changing the value of `GenMultiDecay.DEFAULT_MASS_FUNC` to a different string, e.g., `\"gauss\"`.\n",
     "\n",
@@ -279,7 +282,7 @@
     "def custom_gauss(mass, width):\n",
     "    particle_mass = tf.cast(mass, tf.float64)\n",
     "    particle_width = tf.cast(width, tf.float64)\n",
-    "    \n",
+    "\n",
     "    # This is the actual mass function that will be returned\n",
     "    def mass_func(min_mass, max_mass, n_events):\n",
     "        min_mass = tf.cast(min_mass, tf.float64)\n",
@@ -311,7 +314,7 @@
     "print(\"Before:\")\n",
     "pprint(dsplus_chain_subset)\n",
     "\n",
-    "# Set the mass function of pi0 to the custom gaussian distribution \n",
+    "# Set the mass function of pi0 to the custom gaussian distribution\n",
     "#  when it decays into an electron-positron pair and a photon (gamma)\n",
     "dsplus_chain_subset[\"pi0\"][1][\"zfit\"] = \"custom_gauss\"\n",
     "print(\"After:\")\n",

docs/conf.py

@@ -40,6 +40,7 @@
     "sphinx.ext.mathjax",
     "sphinx_math_dollar",
     "jupyter_sphinx",
+    "myst_nb",
 ]
 
 
@@ -108,15 +109,15 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
-# makes the jupyter extension executable
-jupyter_sphinx_thebelab_config = {
-    "requestKernel": True,
-    "binderOptions": {
-        "repo": "zfit/phasespace",
-        "binderUrl": "https://mybinder.org",
-        "repoProvider": "github",
-    },
-}
+# # makes the jupyter extension executable
+# jupyter_sphinx_thebelab_config = {
+#     "requestKernel": True,
+#     "binderOptions": {
+#         "repo": "zfit/phasespace",
+#         "binderUrl": "https://mybinder.org",
+#         "repoProvider": "github",
+#     },
+# }
 
 # -- Options for HTML output -------------------------------------------
 
@@ -141,6 +142,7 @@
     "navbar_links": [
         ("Phasespace", "index"),
         ("Usage", "usage"),
+        ("DecayChain", "GenMultiDecay_Tutorial"),
         ("API", "phasespace"),
         ("Contributing", "contributing"),
         # ("Link", "http://example.com", True),

docs/index.rst

@@ -11,6 +11,7 @@ Table of Contents
    :maxdepth: 1
 
    usage
+   DecayChain <GenMultiDecay_Tutorial.ipynb>
    API <phasespace>
    contributing
    authors

docs/phasespace.rst

@@ -16,3 +16,16 @@ phasespace.kinematics module
     :members:
     :undoc-members:
     :show-inheritance:
+
+phasespace.fromdecay module
+------------------------------
+
+.. automodule:: phasespace.fromdecay.genmultidecay
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: phasespace.fromdecay.mass_functions
+    :members:
+    :undoc-members:
+    :show-inheritance:

setup.cfg

@@ -62,6 +62,7 @@ doc =
     %(fromdecay)s
     graphviz
     Sphinx
+    myst-nb
     sphinx_bootstrap_theme
     jupyter_sphinx
     sphinx-math-dollar