Skip to content
5 changes: 5 additions & 0 deletions docs/amplitude-analysis.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -406,6 +406,10 @@
"raw_mimetype": "text/restructuredtext"
},
"source": [
":::{tip}\n",
"For decays into many final state particles, `adaptive_max_weight=True` makes {class}`.TFPhaseSpaceGenerator` much faster. See {doc}`/amplitude-analysis/phase-space`.\n",
":::\n",
"\n",
"The resulting phase space sample is a {obj}`dict` of final state IDs to an {obj}`~numpy.array` of four-momenta. In the last step, we converted this sample in such a way that it is rendered as an understandable {class}`pandas.DataFrame`.\n",
"\n",
":::{admonition} Four-momentum arrays\n",
Expand Down Expand Up @@ -1871,6 +1875,7 @@
"maxdepth: 2\n",
"---\n",
"amplitude-analysis/analytic-continuation\n",
"amplitude-analysis/phase-space\n",
"```"
]
}
Expand Down
239 changes: 239 additions & 0 deletions docs/amplitude-analysis/phase-space.ipynb
Original file line number Diff line number Diff line change
@@ -0,0 +1,239 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"<!-- cspell:ignore colorbar dalitz fromkeys linalg mystnb yscale -->\n",
"\n",
"# Phase space generators\n",
"\n",
":::{autolink-concat}\n",
":::"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Amplitude analysis needs samples of four-momenta that are distributed uniformly over the phase space of a decay. {class}`.TFPhaseSpaceGenerator` produces such samples with [`phasespace`](https://phasespace.readthedocs.io). That package generates *weighted* events, so {class}`.TFPhaseSpaceGenerator` turns them into unweighted events with a hit-and-miss step: an event is kept if a uniform random number is below its weight. This page shows how the `adaptive_max_weight` option makes that step faster without changing the generated distribution."
]
},
{
"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",
"import os\n",
"\n",
"import matplotlib.pyplot as plt\n",
"import numpy as np\n",
"import tensorflow as tf\n",
"from matplotlib_inline.backend_inline import set_matplotlib_formats\n",
"\n",
"os.environ[\"TF_CPP_MIN_LOG_LEVEL\"] = \"3\"\n",
"logging.getLogger(\"tensorwaves\").setLevel(logging.ERROR)\n",
"tf.get_logger().setLevel(logging.ERROR)\n",
"set_matplotlib_formats(\"svg\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Hit-and-miss against an estimated maximum weight\n",
"\n",
"By default, the random numbers of the hit-and-miss step are drawn up to $1$, the upper bound of the normalized weights that `phasespace` guarantees. The weights that actually occur are often far below that bound, especially for decays into many particles, so most events are rejected. With `adaptive_max_weight=True`, the random numbers are drawn up to an estimate of the maximum weight instead. The estimate is the largest weight seen so far plus a margin of 5%. If a later bunch contains a larger weight, the estimate is raised and the sample is generated anew, so that the result remains unbiased.\n",
"\n",
"The option is keyword-only and is off by default, so existing code keeps producing the same events for the same seed."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The following plots illustrate this for a $5\\,\\mathrm{GeV}$ particle that decays into an increasing number of pions. The left panel shows the weight distributions relative to the largest weight in each sample. The right panel shows the fraction of events that survive the hit-and-miss step: with the default setting, this is the mean weight, while with `adaptive_max_weight=True` it is the mean weight divided by the estimated maximum."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"jupyter": {
"source_hidden": true
},
"mystnb": {
"code_prompt_show": "Plot weight distributions"
},
"tags": [
"hide-input"
]
},
"outputs": [],
"source": [
"from tensorwaves.data import TFUniformRealNumberGenerator, TFWeightedPhaseSpaceGenerator\n",
"\n",
"n_particles = list(range(3, 9))\n",
"weights = {}\n",
"for n in n_particles:\n",
" weighted_generator = TFWeightedPhaseSpaceGenerator(\n",
" initial_state_mass=5.0,\n",
" final_state_masses=dict.fromkeys(range(n), 0.13957),\n",
" )\n",
" rng = TFUniformRealNumberGenerator(seed=0)\n",
" weights[n] = weighted_generator.generate(100_000, rng)[\"weights\"]\n",
"\n",
"fig, (ax1, ax2) = plt.subplots(ncols=2, figsize=(10, 3.8), layout=\"constrained\")\n",
"for n, w in weights.items():\n",
" ax1.hist(w / w.max(), bins=60, histtype=\"step\", density=True, label=f\"{n} pions\")\n",
"ax1.set_xlabel(\"Weight / maximum weight in sample\")\n",
"ax1.set_yticks([])\n",
"ax1.legend()\n",
"ax2.plot(n_particles, [w.mean() for w in weights.values()], \"o-\", label=\"Default\")\n",
"ax2.plot(\n",
" n_particles,\n",
" [w.mean() / (1.05 * w.max()) for w in weights.values()],\n",
" \"s-\",\n",
" label=\"adaptive_max_weight=True\",\n",
")\n",
"ax2.set_xlabel(\"Number of pions\")\n",
"ax2.set_ylabel(\"Fraction of accepted events\")\n",
"ax2.set_yscale(\"log\")\n",
"ax2.legend()\n",
"plt.show()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The shape of the weight distribution relative to its maximum changes only moderately with more particles, but the mean weight relative to the bound of $1$ drops by several orders of magnitude. With the estimated maximum, the fraction of accepted events stays above 10%. The gain in speed grows accordingly: for five or more pions, generation is orders of magnitude faster. {doc}`TR-038 <compwa-report:038/index>` benchmarks this and confirms with statistical tests that both settings produce the same distributions."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Usage\n",
"\n",
"The option is a keyword argument of {class}`.TFPhaseSpaceGenerator`. The following example generates a sample of a three-body decay with both settings. The events differ, because the hit-and-miss step consumes the random numbers differently, but both samples are distributed uniformly over phase space: the events fill the kinematically allowed region of the Dalitz plot evenly."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from tensorwaves.data import TFPhaseSpaceGenerator, TFUniformRealNumberGenerator\n",
"\n",
"initial_state_mass = 3.0969\n",
"final_state_masses = {0: 0.1350, 1: 0.1396, 2: 0.4937}\n",
"default_generator = TFPhaseSpaceGenerator(initial_state_mass, final_state_masses)\n",
"adaptive_generator = TFPhaseSpaceGenerator(\n",
" initial_state_mass, final_state_masses, adaptive_max_weight=True\n",
")"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"size = 500_000\n",
"default_generator.show_progress = False\n",
"adaptive_generator.show_progress = False\n",
"samples = {\n",
" \"Default\": default_generator.generate(size, TFUniformRealNumberGenerator(seed=0)),\n",
" \"adaptive_max_weight=True\": adaptive_generator.generate(\n",
" size, TFUniformRealNumberGenerator(seed=0)\n",
" ),\n",
"}"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"jupyter": {
"source_hidden": true
},
"mystnb": {
"code_prompt_show": "Plot Dalitz plots"
},
"tags": [
"hide-input"
]
},
"outputs": [],
"source": [
"def invariant_mass_squared(*momenta: np.ndarray) -> np.ndarray:\n",
" p = np.sum(momenta, axis=0)\n",
" return p[:, 0] ** 2 - np.sum(p[:, 1:] ** 2, axis=1)\n",
"\n",
"\n",
"variables = {\n",
" label: (\n",
" invariant_mass_squared(sample[\"p0\"], sample[\"p1\"]),\n",
" invariant_mass_squared(sample[\"p1\"], sample[\"p2\"]),\n",
" )\n",
" for label, sample in samples.items()\n",
"}\n",
"\n",
"fig, axes = plt.subplots(1, 2, figsize=(10, 4.5), sharey=True, layout=\"constrained\")\n",
"for ax, (label, (m12, m23)) in zip(axes, variables.items(), strict=True):\n",
" ax.hist2d(m12, m23, bins=150, cmin=1, rasterized=True)\n",
" ax.set_title(label)\n",
" ax.set_xlabel(R\"$m^2_{12}$ [GeV$^2$]\")\n",
"axes[0].set_ylabel(R\"$m^2_{23}$ [GeV$^2$]\")\n",
"fig.colorbar(axes[0].collections[0], ax=axes, label=\"Events\")\n",
"plt.show()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## When to use the option\n",
"\n",
"The option pays off for decays into five or more particles, where the default setting rejects most events. Keep the default when samples have to be identical to those of earlier versions for the same seed, for instance when tests compare against stored values. A small `bunch_size` makes the estimate of the maximum weight less accurate and leads to more restarts, so the option works best with the default bunch size."
]
}
],
"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"
}
},
"nbformat": 4,
"nbformat_minor": 4
}
1 change: 1 addition & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -258,6 +258,7 @@ def get_tensorflow_url() -> str:
nb_output_stderr = "remove"
nb_render_markdown_format = "myst"
nitpick_ignore = [
("std:doc", "compwa-report:038/index"),
("py:class", "tensorflow.keras.losses.Loss"),
("py:class", "tensorflow.python.keras.losses.Loss"),
("py:obj", "Loss"),
Expand Down
2 changes: 1 addition & 1 deletion docs/usage/basics.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -513,7 +513,7 @@
"metadata": {},
"source": [
"> [!NOTE]\n",
"> In PWA, the sample on which we perform hit-and-miss is not uniform, because the available space is limited by the masses of the initial and final state (phase space). See {class}`.TFPhaseSpaceGenerator` and {ref}`amplitude-analysis:Step 2: Generate data`."
"> In PWA, the sample on which we perform hit-and-miss is not uniform, because the available space is limited by the masses of the initial and final state (phase space). See {class}`.TFPhaseSpaceGenerator`, {doc}`/amplitude-analysis/phase-space`, and {ref}`amplitude-analysis:Step 2: Generate data`."
]
},
{
Expand Down
36 changes: 33 additions & 3 deletions src/tensorwaves/data/phasespace.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
import logging
from typing import TYPE_CHECKING

import numpy as np
from tqdm.auto import tqdm

from tensorwaves.function._backend import raise_missing_module_error
Expand All @@ -21,10 +22,11 @@
if TYPE_CHECKING:
from collections.abc import Mapping

import numpy as np
import tensorflow as tf

_LOGGER = logging.getLogger(__name__)
_MAX_PHASESPACE_WEIGHT = 1.0
"""Upper bound of the normalized weights that `phasespace` generates."""


class TFPhaseSpaceGenerator(DataGenerator):
Expand All @@ -33,18 +35,31 @@ class TFPhaseSpaceGenerator(DataGenerator):
:param initial_state_mass: Mass of the decaying state.
:param final_state_masses: Masses keyed by final-state ID.
:param bunch_size: Number of candidates generated per hit-and-miss iteration.
:param adaptive_max_weight: Perform the hit-and-miss step against an estimate of the
maximum weight instead of against the upper bound of the weights that
``phasespace`` guarantees. This bound is much larger than the weights that
actually occur, especially for many final state particles, so the estimate
accepts far more events per bunch. The maximum is estimated from the generated
bunches with a margin of 5%. If a bunch contains a weight above the current
estimate, the estimate is raised and the sample is generated anew, like in
`.IntensityDistributionGenerator`. The generated distribution stays the same,
but the events differ from those that are generated without this option for the
same seed. See :doc:`/amplitude-analysis/phase-space`.
"""

def __init__(
self,
initial_state_mass: float,
final_state_masses: Mapping[int, float],
bunch_size: int = 50_000,
*,
adaptive_max_weight: bool = False,
) -> None:
self.__phsp_generator = TFWeightedPhaseSpaceGenerator(
initial_state_mass, final_state_masses
)
self.__bunch_size = bunch_size
self.__adaptive_max_weight = adaptive_max_weight
# https://github.com/ComPWA/tensorwaves/issues/395
self.show_progress = True

Expand All @@ -56,14 +71,16 @@ def generate(self, size: int, rng: RealNumberGenerator) -> DataSample:

.. seealso::

:ref:`amplitude-analysis:2.1 Generate phase space sample`
:ref:`amplitude-analysis:2.1 Generate phase space sample` and
:doc:`/amplitude-analysis/phase-space`
"""
progress_bar = tqdm(
total=size,
desc="Generating phase space sample",
disable=not self.show_progress or _LOGGER.level > logging.WARNING,
)
momentum_pool: DataSample = {}
max_weight = 0.0
while get_number_of_events(momentum_pool) < size:
phsp_momenta = self.__phsp_generator.generate(self.__bunch_size, rng)
weights = phsp_momenta.get("weights")
Expand All @@ -74,7 +91,20 @@ def generate(self, size: int, rng: RealNumberGenerator) -> DataSample:
' "weights"'
)
raise ValueError(msg)
hit_and_miss_randoms = rng(self.__bunch_size)
if self.__adaptive_max_weight:
bunch_max = float(np.max(weights))
if bunch_max > max_weight:
max_weight = min(1.05 * bunch_max, _MAX_PHASESPACE_WEIGHT)
if get_number_of_events(momentum_pool) > 0:
_LOGGER.info(
f"Bunch maximum weight {bunch_max} exceeds the estimated"
" maximum weight. Restarting generation!"
)
momentum_pool = {}
progress_bar.update(n=-progress_bar.n)
hit_and_miss_randoms = rng(self.__bunch_size, max_value=max_weight)
else:
hit_and_miss_randoms = rng(self.__bunch_size)
bunch = select_events(phsp_momenta, selector=weights > hit_and_miss_randoms)
momentum_pool = merge_events(momentum_pool, bunch)
progress_bar.update(n=get_number_of_events(bunch))
Expand Down
Loading
Loading