diff --git a/docs/amplitude-analysis.ipynb b/docs/amplitude-analysis.ipynb index 800a7c73..668af34a 100644 --- a/docs/amplitude-analysis.ipynb +++ b/docs/amplitude-analysis.ipynb @@ -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", @@ -1871,6 +1875,7 @@ "maxdepth: 2\n", "---\n", "amplitude-analysis/analytic-continuation\n", + "amplitude-analysis/phase-space\n", "```" ] } diff --git a/docs/amplitude-analysis/phase-space.ipynb b/docs/amplitude-analysis/phase-space.ipynb new file mode 100644 index 00000000..4d107cc3 --- /dev/null +++ b/docs/amplitude-analysis/phase-space.ipynb @@ -0,0 +1,239 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\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 ` 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 +} diff --git a/docs/conf.py b/docs/conf.py index f12aefe9..eb1a952e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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"), diff --git a/docs/usage/basics.ipynb b/docs/usage/basics.ipynb index 50e12b0c..0202596e 100644 --- a/docs/usage/basics.ipynb +++ b/docs/usage/basics.ipynb @@ -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`." ] }, { diff --git a/src/tensorwaves/data/phasespace.py b/src/tensorwaves/data/phasespace.py index 3b482ed1..1de7ddd5 100644 --- a/src/tensorwaves/data/phasespace.py +++ b/src/tensorwaves/data/phasespace.py @@ -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 @@ -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): @@ -33,6 +35,16 @@ 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__( @@ -40,11 +52,14 @@ def __init__( 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 @@ -56,7 +71,8 @@ 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, @@ -64,6 +80,7 @@ def generate(self, size: int, rng: RealNumberGenerator) -> DataSample: 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") @@ -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)) diff --git a/tests/data/test_phasespace.py b/tests/data/test_phasespace.py index 38519be8..ebac2ce2 100644 --- a/tests/data/test_phasespace.py +++ b/tests/data/test_phasespace.py @@ -1,5 +1,6 @@ from __future__ import annotations +import logging from pprint import pprint from typing import TYPE_CHECKING @@ -139,6 +140,93 @@ def it_generates_an_empty_sample_for_zero_events(pdg: ParticleCollection): phsp_momenta = phsp_generator.generate(0, rng) assert len(phsp_momenta) == 0 + def describe_adaptive_max_weight(): + masses = dict.fromkeys(range(4), 0.1396) + + def it_conserves_four_momentum_and_masses(): + generator = TFPhaseSpaceGenerator(3.0, masses, adaptive_max_weight=True) + phsp = generator.generate(1_000, TFUniformRealNumberGenerator(seed=0)) + assert set(phsp) == {"p0", "p1", "p2", "p3"} + total = sum(phsp.values()) + assert pytest.approx(total) == np.broadcast_to([3.0, 0, 0, 0], (1_000, 4)) + for momenta in phsp.values(): + assert momenta.shape == (1_000, 4) + mass_squared = momenta[:, 0] ** 2 - np.sum(momenta[:, 1:] ** 2, axis=1) + assert pytest.approx(mass_squared, abs=1e-6) == np.full( + 1_000, 0.1396**2 + ) + + def it_is_reproducible(): + generator = TFPhaseSpaceGenerator(3.0, masses, adaptive_max_weight=True) + sample1 = generator.generate(100, TFUniformRealNumberGenerator(seed=0)) + sample2 = generator.generate(100, TFUniformRealNumberGenerator(seed=0)) + for key, momenta in sample1.items(): + assert pytest.approx(momenta) == sample2[key] + + def it_needs_fewer_bunches(monkeypatch: pytest.MonkeyPatch): + n_calls = [] + original_generate = TFWeightedPhaseSpaceGenerator.generate + + def counted_generate(self, size, rng): + n_calls[-1] += 1 + return original_generate(self, size, rng) + + monkeypatch.setattr( + TFWeightedPhaseSpaceGenerator, "generate", counted_generate + ) + five_pions = dict.fromkeys(range(5), 0.1396) + for adaptive_max_weight in [False, True]: + n_calls.append(0) + generator = TFPhaseSpaceGenerator( + 3.0, + five_pions, + bunch_size=10_000, + adaptive_max_weight=adaptive_max_weight, + ) + generator.show_progress = False + generator.generate(1_000, TFUniformRealNumberGenerator(seed=0)) + default_calls, adaptive_calls = n_calls + assert 5 * adaptive_calls < default_calls + + @pytest.mark.parametrize("bunch_size", [500, 50_000]) + def it_reproduces_the_default_distribution(bunch_size: int): + size = 100_000 + samples = [] + for adaptive_max_weight in [False, True]: + generator = TFPhaseSpaceGenerator( + 3.0, + masses, + bunch_size=bunch_size, + adaptive_max_weight=adaptive_max_weight, + ) + generator.show_progress = False + rng = TFUniformRealNumberGenerator(seed=int(adaptive_max_weight)) + samples.append(generator.generate(size, rng)) + for i, j in [(0, 1), (0, 2), (1, 3), (2, 3)]: + histograms = [] + for sample in samples: + p = sample[f"p{i}"] + sample[f"p{j}"] + mass = np.sqrt(p[:, 0] ** 2 - np.sum(p[:, 1:] ** 2, axis=1)) + histograms.append(np.histogram(mass, bins=40, range=(0.2, 2.8))[0]) + default, adaptive = histograms + mask = default + adaptive > 50 + chi2 = np.sum( + (default - adaptive)[mask] ** 2 / (default + adaptive)[mask] + ) + assert chi2 / np.count_nonzero(mask) < 1.5 + + def it_restarts_when_a_bunch_exceeds_the_estimate( + caplog: pytest.LogCaptureFixture, + ): + generator = TFPhaseSpaceGenerator( + 3.0, masses, bunch_size=1, adaptive_max_weight=True + ) + generator.show_progress = False + with caplog.at_level(logging.INFO, logger="tensorwaves.data.phasespace"): + sample = generator.generate(50, TFUniformRealNumberGenerator(seed=0)) + assert len(sample["p0"]) == 50 + assert "Restarting generation" in caplog.text + def describe_TFWeightedPhaseSpaceGenerator(): def it_generates_deterministic_four_momenta_and_weights(pdg: ParticleCollection):