diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 692503ee..db0fde48 100644 --- a/CHANGELOG.rst +++ b/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 `_ 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) ================== diff --git a/docs/GenMultiDecay_Tutorial.ipynb b/docs/GenMultiDecay_Tutorial.ipynb index 642e1adc..8bb26c39 100644 --- a/docs/GenMultiDecay_Tutorial.ipynb +++ b/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,7 +158,7 @@ "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." ] }, { @@ -163,8 +166,8 @@ "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", diff --git a/docs/conf.py b/docs/conf.py index 88dae65b..eb1c7518 100755 --- a/docs/conf.py +++ b/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), diff --git a/docs/index.rst b/docs/index.rst index 24a715e8..db9eb73b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,6 +11,7 @@ Table of Contents :maxdepth: 1 usage + DecayChain API contributing authors diff --git a/docs/phasespace.rst b/docs/phasespace.rst index ab905f15..5a567c5f 100644 --- a/docs/phasespace.rst +++ b/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: diff --git a/setup.cfg b/setup.cfg index 61734113..7f5a0bec 100644 --- a/setup.cfg +++ b/setup.cfg @@ -62,6 +62,7 @@ doc = %(fromdecay)s graphviz Sphinx + myst-nb sphinx_bootstrap_theme jupyter_sphinx sphinx-math-dollar