From 4bfc81e799c052eb756733dd5434abbab1750127 Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Mon, 9 Nov 2026 06:31:33 +0100 Subject: [PATCH 1/8] ENH: add adaptive_max_weight option --- src/tensorwaves/data/phasespace.py | 33 ++++++++++- tests/data/test_phasespace.py | 88 ++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+), 2 deletions(-) diff --git a/src/tensorwaves/data/phasespace.py b/src/tensorwaves/data/phasespace.py index cc823824..dee137d9 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): @@ -34,6 +36,16 @@ class TFPhaseSpaceGenerator(DataGenerator): initial_state_mass: Mass of the decaying state. final_state_masses: A mapping of final state IDs to the corresponding masses. bunch_size: Size of a bunch that is generated during a hit-and-miss iteration. + 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 + :code:`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. """ def __init__( @@ -41,11 +53,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 @@ -63,6 +78,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") @@ -73,7 +89,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): From a0c84ec386b52e91ca7dd62cc996dba0fe8900cb Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Mon, 9 Nov 2026 10:10:48 +0100 Subject: [PATCH 2/8] DOC: illustrate adaptive_max_weight on phase space page --- docs/usage.ipynb | 1 + docs/usage/phase-space.ipynb | 369 +++++++++++++++++++++++++++++++++++ 2 files changed, 370 insertions(+) create mode 100644 docs/usage/phase-space.ipynb diff --git a/docs/usage.ipynb b/docs/usage.ipynb index 364fca47..ab54fce0 100644 --- a/docs/usage.ipynb +++ b/docs/usage.ipynb @@ -764,6 +764,7 @@ "usage/unbinned-fit\n", "usage/caching\n", "usage/faster-lambdify\n", + "usage/phase-space\n", "```" ] } diff --git a/docs/usage/phase-space.ipynb b/docs/usage/phase-space.ipynb new file mode 100644 index 00000000..b5faee35 --- /dev/null +++ b/docs/usage/phase-space.ipynb @@ -0,0 +1,369 @@ +{ + "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", + "import time\n", + "\n", + "import matplotlib.pyplot as plt\n", + "import numpy as np\n", + "import pandas as pd\n", + "from matplotlib_inline.backend_inline import set_matplotlib_formats\n", + "from scipy.stats import ks_2samp\n", + "\n", + "os.environ[\"TF_CPP_MIN_LOG_LEVEL\"] = \"3\"\n", + "logging.getLogger(\"tensorwaves\").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": "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": "markdown", + "metadata": {}, + "source": [ + "## Speed\n", + "\n", + "The gain grows with the number of final state particles, because the spread of the weights grows with it. The following cell times both settings for a $5\\,\\mathrm{GeV}$ particle that decays into an increasing number of pions. These timings only give an impression on the machine that builds this page." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "jupyter": { + "source_hidden": true + }, + "mystnb": { + "code_prompt_show": "Time both settings" + }, + "tags": [ + "hide-input" + ] + }, + "outputs": [], + "source": [ + "def time_generation(n_pions: int, adaptive: bool, size: int = 10_000) -> float:\n", + " generator = TFPhaseSpaceGenerator(\n", + " initial_state_mass=5.0,\n", + " final_state_masses=dict.fromkeys(range(n_pions), 0.13957),\n", + " adaptive_max_weight=adaptive,\n", + " )\n", + " generator.show_progress = False\n", + " rng = TFUniformRealNumberGenerator(seed=0)\n", + " start = time.perf_counter()\n", + " generator.generate(size, rng)\n", + " return time.perf_counter() - start\n", + "\n", + "\n", + "time_generation(3, adaptive=False) # warm up TensorFlow\n", + "timings = pd.DataFrame({\n", + " \"Default\": {n: time_generation(n, adaptive=False) for n in range(3, 7)},\n", + " \"adaptive_max_weight=True\": {\n", + " n: time_generation(n, adaptive=True) for n in range(3, 7)\n", + " },\n", + "})\n", + "timings.index.name = \"Pions\"\n", + "timings[\"Speed-up\"] = timings[\"Default\"] / timings[\"adaptive_max_weight=True\"]\n", + "timings.style.format({\n", + " \"Default\": \"{:.2f} s\",\n", + " \"adaptive_max_weight=True\": \"{:.2f} s\",\n", + " \"Speed-up\": \"{:.1f}x\",\n", + "})" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "For three particles, a single bunch of 50,000 events already contains enough accepted events, so both settings take about equally long. For more particles, the default setting needs many more bunches." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Generated distributions\n", + "\n", + "We now generate a large sample of the three-body decay with both settings. The events differ, because the hit-and-miss step consumes the random numbers differently, but both samples should be distributed uniformly over phase space. The Dalitz plots show this: the events fill the kinematically allowed region evenly with both settings." + ] + }, + { + "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: pd.DataFrame({\n", + " \"m12\": invariant_mass_squared(sample[\"p0\"], sample[\"p1\"]),\n", + " \"m23\": invariant_mass_squared(sample[\"p1\"], sample[\"p2\"]),\n", + " \"m13\": invariant_mass_squared(sample[\"p0\"], sample[\"p2\"]),\n", + " \"cos_theta\": sample[\"p0\"][:, 3] / np.linalg.norm(sample[\"p0\"][:, 1:], axis=1),\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, df) in zip(axes, variables.items(), strict=True):\n", + " ax.hist2d(df[\"m12\"], df[\"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": [ + "## Comparing the distributions\n", + "\n", + "Overlaying the projections of both samples shows that they agree within statistical fluctuations. The lower panels show the difference per bin, divided by its statistical uncertainty. These pulls should scatter around zero with a spread of about one." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "jupyter": { + "source_hidden": true + }, + "mystnb": { + "code_prompt_show": "Plot projections with pulls" + }, + "tags": [ + "hide-input" + ] + }, + "outputs": [], + "source": [ + "labels = {\n", + " \"m12\": R\"$m^2_{12}$ [GeV$^2$]\",\n", + " \"m23\": R\"$m^2_{23}$ [GeV$^2$]\",\n", + " \"m13\": R\"$m^2_{13}$ [GeV$^2$]\",\n", + " \"cos_theta\": R\"$\\cos\\theta_0$\",\n", + "}\n", + "fig, axes = plt.subplots(\n", + " 2,\n", + " len(labels),\n", + " figsize=(13, 4.5),\n", + " height_ratios=[3, 1],\n", + " sharex=\"col\",\n", + " layout=\"constrained\",\n", + ")\n", + "default, adaptive = variables.values()\n", + "for (top, bottom), (key, xlabel) in zip(axes.T, labels.items(), strict=True):\n", + " bins = np.linspace(default[key].min(), default[key].max(), 61)\n", + " n_default, _ = np.histogram(default[key], bins)\n", + " n_adaptive, _ = np.histogram(adaptive[key], bins)\n", + " for label, df in variables.items():\n", + " top.hist(df[key], bins, histtype=\"step\", label=label)\n", + " pulls = (n_adaptive - n_default) / np.sqrt(n_adaptive + n_default)\n", + " bottom.stairs(pulls, bins, fill=True, alpha=0.6)\n", + " bottom.axhline(0, color=\"black\", linewidth=0.5)\n", + " bottom.set_ylim(-4, 4)\n", + " bottom.set_xlabel(xlabel)\n", + "axes[0, 0].set_ylabel(\"Events\")\n", + "axes[1, 0].set_ylabel(\"Pull\")\n", + "axes[0, -1].legend(loc=\"lower center\", fontsize=\"small\")\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "A two-sample [Kolmogorov–Smirnov test](https://en.wikipedia.org/wiki/Kolmogorov%E2%80%93Smirnov_test) quantifies this. A $p$-value well above a typical threshold such as $0.05$ means that the test finds no evidence that the two samples come from different distributions. The table also lists the means and standard deviations, which agree to the precision expected for this sample size." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "pd.DataFrame({\n", + " key: {\n", + " \"Mean (default)\": default[key].mean(),\n", + " \"Mean (adaptive)\": adaptive[key].mean(),\n", + " \"Std (default)\": default[key].std(),\n", + " \"Std (adaptive)\": adaptive[key].std(),\n", + " \"KS p-value\": ks_2samp(default[key], adaptive[key]).pvalue,\n", + " }\n", + " for key in labels\n", + "}).T.style.format(\"{:.4f}\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The same holds for decays into more particles, where the option makes the biggest difference. The comparison below repeats the test for a five-pion decay, using the invariant mass of each pair of neighboring pions." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "jupyter": { + "source_hidden": true + }, + "mystnb": { + "code_prompt_show": "Compare five-pion samples" + }, + "tags": [ + "hide-input" + ] + }, + "outputs": [], + "source": [ + "n_pions = 5\n", + "five_pion_samples = {}\n", + "for adaptive in [False, True]:\n", + " generator = TFPhaseSpaceGenerator(\n", + " initial_state_mass=5.0,\n", + " final_state_masses=dict.fromkeys(range(n_pions), 0.13957),\n", + " adaptive_max_weight=adaptive,\n", + " )\n", + " generator.show_progress = False\n", + " five_pion_samples[adaptive] = generator.generate(\n", + " 100_000, TFUniformRealNumberGenerator(seed=1)\n", + " )\n", + "\n", + "pairs = [(i, i + 1) for i in range(n_pions - 1)]\n", + "fig, axes = plt.subplots(1, len(pairs), figsize=(13, 3), layout=\"constrained\")\n", + "p_values = {}\n", + "for ax, (i, j) in zip(axes, pairs, strict=True):\n", + " m2 = {\n", + " adaptive: invariant_mass_squared(sample[f\"p{i}\"], sample[f\"p{j}\"])\n", + " for adaptive, sample in five_pion_samples.items()\n", + " }\n", + " bins = np.linspace(0, m2[False].max(), 50)\n", + " ax.hist(m2[False], bins, histtype=\"step\", label=\"Default\")\n", + " ax.hist(m2[True], bins, histtype=\"step\", label=\"adaptive_max_weight=True\")\n", + " ax.set_xlabel(Rf\"$m^2_{{{i}{j}}}$ [GeV$^2$]\")\n", + " p_values[f\"m2_{i}{j}\"] = ks_2samp(m2[False], m2[True]).pvalue\n", + "axes[0].set_ylabel(\"Events\")\n", + "axes[-1].legend(fontsize=\"small\")\n", + "plt.show()\n", + "pd.Series(p_values, name=\"KS p-value\").to_frame().style.format(\"{:.3f}\")" + ] + } + ], + "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 +} From 0e4bb59afc3494c6bca8ebd6f4ceedda51c9e15d Mon Sep 17 00:00:00 2001 From: GitHub Date: Mon, 9 Nov 2026 09:12:24 +0000 Subject: [PATCH 3/8] MAINT: implement updates from formatters --- docs/usage.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage.ipynb b/docs/usage.ipynb index ab54fce0..7a134a3f 100644 --- a/docs/usage.ipynb +++ b/docs/usage.ipynb @@ -788,7 +788,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.13.16" + "version": "3.13.18" } }, "nbformat": 4, From 456614fce67c663776833945480085f6f14acdb0 Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Mon, 9 Nov 2026 10:14:54 +0100 Subject: [PATCH 4/8] DOC: explain the low acceptance of the default hit-and-miss step --- docs/usage/phase-space.ipynb | 73 +++++++++++++++++++++++++++++++++++- 1 file changed, 72 insertions(+), 1 deletion(-) diff --git a/docs/usage/phase-space.ipynb b/docs/usage/phase-space.ipynb index b5faee35..35dc13f5 100644 --- a/docs/usage/phase-space.ipynb +++ b/docs/usage/phase-space.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "\n", + "\n", "\n", "# Phase space generators\n", "\n", @@ -61,6 +61,68 @@ "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%." + ] + }, { "cell_type": "code", "execution_count": null, @@ -341,6 +403,15 @@ "plt.show()\n", "pd.Series(p_values, name=\"KS p-value\").to_frame().style.format(\"{:.3f}\")" ] + }, + { + "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": { From f198bc08774dc449ef9052ddfb37171044179426 Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Mon, 9 Nov 2026 10:27:25 +0100 Subject: [PATCH 5/8] DOC: link to the phase space page and hide TensorFlow warnings --- docs/amplitude-analysis.ipynb | 2 +- docs/usage/basics.ipynb | 2 +- docs/usage/phase-space.ipynb | 2 ++ src/tensorwaves/data/phasespace.py | 6 ++++-- 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/amplitude-analysis.ipynb b/docs/amplitude-analysis.ipynb index 281255fe..13d94877 100644 --- a/docs/amplitude-analysis.ipynb +++ b/docs/amplitude-analysis.ipynb @@ -415,7 +415,7 @@ "raw_mimetype": "text/restructuredtext" }, "source": [ - "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", + ":::{tip}\nFor decays into many final state particles, `adaptive_max_weight=True` makes {class}`.TFPhaseSpaceGenerator` much faster. See {doc}`/usage/phase-space`.\n:::\n\nThe 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", "{doc}`Kinematic expressions ` from AmpForm that involve four-momenta should be formatted as $\\left(E, p_x, p_y, p_z\\right)$. In addition, the shape of input arrays should be `(n, 4)` with `n` the number of events.\n", diff --git a/docs/usage/basics.ipynb b/docs/usage/basics.ipynb index 55104ff5..893860c1 100644 --- a/docs/usage/basics.ipynb +++ b/docs/usage/basics.ipynb @@ -523,7 +523,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`.\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`, {doc}`/usage/phase-space`, and {ref}`amplitude-analysis:Step 2: Generate data`.\n", "```" ] }, diff --git a/docs/usage/phase-space.ipynb b/docs/usage/phase-space.ipynb index 35dc13f5..f4bc31b2 100644 --- a/docs/usage/phase-space.ipynb +++ b/docs/usage/phase-space.ipynb @@ -42,11 +42,13 @@ "import matplotlib.pyplot as plt\n", "import numpy as np\n", "import pandas as pd\n", + "import tensorflow as tf\n", "from matplotlib_inline.backend_inline import set_matplotlib_formats\n", "from scipy.stats import ks_2samp\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\")" ] }, diff --git a/src/tensorwaves/data/phasespace.py b/src/tensorwaves/data/phasespace.py index dee137d9..63705959 100644 --- a/src/tensorwaves/data/phasespace.py +++ b/src/tensorwaves/data/phasespace.py @@ -45,7 +45,8 @@ class TFPhaseSpaceGenerator(DataGenerator): 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. + generated without this option for the same seed. See + :doc:`/usage/phase-space`. """ def __init__( @@ -70,7 +71,8 @@ def generate(self, size: int, rng: RealNumberGenerator) -> DataSample: Returns: A `.DataSample` of **four-momenta** arrays of shape :math:`n \times 4`. - .. seealso:: :ref:`amplitude-analysis:2.1 Generate phase space sample` + .. seealso:: :ref:`amplitude-analysis:2.1 Generate phase space sample` and + :doc:`/usage/phase-space` """ progress_bar = tqdm( total=size, From 800ae3f5083ec793a75ef18828cb1fae7c80058e Mon Sep 17 00:00:00 2001 From: GitHub Date: Mon, 9 Nov 2026 10:45:34 +0100 Subject: [PATCH 6/8] MAINT: implement updates from formatters --- docs/amplitude-analysis.ipynb | 8 ++++++-- docs/usage/basics.ipynb | 2 +- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/amplitude-analysis.ipynb b/docs/amplitude-analysis.ipynb index 13d94877..c9fe5ed1 100644 --- a/docs/amplitude-analysis.ipynb +++ b/docs/amplitude-analysis.ipynb @@ -415,7 +415,11 @@ "raw_mimetype": "text/restructuredtext" }, "source": [ - ":::{tip}\nFor decays into many final state particles, `adaptive_max_weight=True` makes {class}`.TFPhaseSpaceGenerator` much faster. See {doc}`/usage/phase-space`.\n:::\n\nThe 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", + ":::{tip}\n", + "For decays into many final state particles, `adaptive_max_weight=True` makes {class}`.TFPhaseSpaceGenerator` much faster. See {doc}`/usage/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", "{doc}`Kinematic expressions ` from AmpForm that involve four-momenta should be formatted as $\\left(E, p_x, p_y, p_z\\right)$. In addition, the shape of input arrays should be `(n, 4)` with `n` the number of events.\n", @@ -1919,7 +1923,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.13.16" + "version": "3.13.18" } }, "nbformat": 4, diff --git a/docs/usage/basics.ipynb b/docs/usage/basics.ipynb index 893860c1..dc096274 100644 --- a/docs/usage/basics.ipynb +++ b/docs/usage/basics.ipynb @@ -1263,7 +1263,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.13.16" + "version": "3.13.18" } }, "nbformat": 4, From 2145f01a71a92ccad53907b83d5f3d2d41fd547d Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Tue, 17 Nov 2026 21:38:26 +0100 Subject: [PATCH 7/8] DOC: move phase space page under amplitude analysis --- docs/amplitude-analysis.ipynb | 3 ++- docs/{usage => amplitude-analysis}/phase-space.ipynb | 0 docs/usage.ipynb | 1 - docs/usage/basics.ipynb | 2 +- src/tensorwaves/data/phasespace.py | 4 ++-- 5 files changed, 5 insertions(+), 5 deletions(-) rename docs/{usage => amplitude-analysis}/phase-space.ipynb (100%) diff --git a/docs/amplitude-analysis.ipynb b/docs/amplitude-analysis.ipynb index 10d0ffa8..668af34a 100644 --- a/docs/amplitude-analysis.ipynb +++ b/docs/amplitude-analysis.ipynb @@ -407,7 +407,7 @@ }, "source": [ ":::{tip}\n", - "For decays into many final state particles, `adaptive_max_weight=True` makes {class}`.TFPhaseSpaceGenerator` much faster. See {doc}`/usage/phase-space`.\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", @@ -1875,6 +1875,7 @@ "maxdepth: 2\n", "---\n", "amplitude-analysis/analytic-continuation\n", + "amplitude-analysis/phase-space\n", "```" ] } diff --git a/docs/usage/phase-space.ipynb b/docs/amplitude-analysis/phase-space.ipynb similarity index 100% rename from docs/usage/phase-space.ipynb rename to docs/amplitude-analysis/phase-space.ipynb diff --git a/docs/usage.ipynb b/docs/usage.ipynb index 85f4071d..192ccb48 100644 --- a/docs/usage.ipynb +++ b/docs/usage.ipynb @@ -755,7 +755,6 @@ "usage/unbinned-fit\n", "usage/caching\n", "usage/faster-lambdify\n", - "usage/phase-space\n", "```" ] } diff --git a/docs/usage/basics.ipynb b/docs/usage/basics.ipynb index a73a6166..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`, {doc}`/usage/phase-space`, 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 e5b111b0..1de7ddd5 100644 --- a/src/tensorwaves/data/phasespace.py +++ b/src/tensorwaves/data/phasespace.py @@ -44,7 +44,7 @@ class TFPhaseSpaceGenerator(DataGenerator): 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:`/usage/phase-space`. + same seed. See :doc:`/amplitude-analysis/phase-space`. """ def __init__( @@ -72,7 +72,7 @@ def generate(self, size: int, rng: RealNumberGenerator) -> DataSample: .. seealso:: :ref:`amplitude-analysis:2.1 Generate phase space sample` and - :doc:`/usage/phase-space` + :doc:`/amplitude-analysis/phase-space` """ progress_bar = tqdm( total=size, From f482a99e559b3814f5bd7c44a8a7820a81bc430c Mon Sep 17 00:00:00 2001 From: Remco de Boer <29308176+redeboer@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:04:44 +0100 Subject: [PATCH 8/8] DOC: move phase space benchmarks to TR-038 --- docs/amplitude-analysis/phase-space.ipynb | 237 ++-------------------- docs/conf.py | 1 + 2 files changed, 18 insertions(+), 220 deletions(-) diff --git a/docs/amplitude-analysis/phase-space.ipynb b/docs/amplitude-analysis/phase-space.ipynb index f4bc31b2..4d107cc3 100644 --- a/docs/amplitude-analysis/phase-space.ipynb +++ b/docs/amplitude-analysis/phase-space.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "\n", + "\n", "\n", "# Phase space generators\n", "\n", @@ -37,14 +37,11 @@ "source": [ "import logging\n", "import os\n", - "import time\n", "\n", "import matplotlib.pyplot as plt\n", "import numpy as np\n", - "import pandas as pd\n", "import tensorflow as tf\n", "from matplotlib_inline.backend_inline import set_matplotlib_formats\n", - "from scipy.stats import ks_2samp\n", "\n", "os.environ[\"TF_CPP_MIN_LOG_LEVEL\"] = \"3\"\n", "logging.getLogger(\"tensorwaves\").setLevel(logging.ERROR)\n", @@ -122,7 +119,16 @@ "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 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." ] }, { @@ -141,76 +147,6 @@ ")" ] }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Speed\n", - "\n", - "The gain grows with the number of final state particles, because the spread of the weights grows with it. The following cell times both settings for a $5\\,\\mathrm{GeV}$ particle that decays into an increasing number of pions. These timings only give an impression on the machine that builds this page." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "jupyter": { - "source_hidden": true - }, - "mystnb": { - "code_prompt_show": "Time both settings" - }, - "tags": [ - "hide-input" - ] - }, - "outputs": [], - "source": [ - "def time_generation(n_pions: int, adaptive: bool, size: int = 10_000) -> float:\n", - " generator = TFPhaseSpaceGenerator(\n", - " initial_state_mass=5.0,\n", - " final_state_masses=dict.fromkeys(range(n_pions), 0.13957),\n", - " adaptive_max_weight=adaptive,\n", - " )\n", - " generator.show_progress = False\n", - " rng = TFUniformRealNumberGenerator(seed=0)\n", - " start = time.perf_counter()\n", - " generator.generate(size, rng)\n", - " return time.perf_counter() - start\n", - "\n", - "\n", - "time_generation(3, adaptive=False) # warm up TensorFlow\n", - "timings = pd.DataFrame({\n", - " \"Default\": {n: time_generation(n, adaptive=False) for n in range(3, 7)},\n", - " \"adaptive_max_weight=True\": {\n", - " n: time_generation(n, adaptive=True) for n in range(3, 7)\n", - " },\n", - "})\n", - "timings.index.name = \"Pions\"\n", - "timings[\"Speed-up\"] = timings[\"Default\"] / timings[\"adaptive_max_weight=True\"]\n", - "timings.style.format({\n", - " \"Default\": \"{:.2f} s\",\n", - " \"adaptive_max_weight=True\": \"{:.2f} s\",\n", - " \"Speed-up\": \"{:.1f}x\",\n", - "})" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "For three particles, a single bunch of 50,000 events already contains enough accepted events, so both settings take about equally long. For more particles, the default setting needs many more bunches." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Generated distributions\n", - "\n", - "We now generate a large sample of the three-body decay with both settings. The events differ, because the hit-and-miss step consumes the random numbers differently, but both samples should be distributed uniformly over phase space. The Dalitz plots show this: the events fill the kinematically allowed region evenly with both settings." - ] - }, { "cell_type": "code", "execution_count": null, @@ -250,18 +186,16 @@ "\n", "\n", "variables = {\n", - " label: pd.DataFrame({\n", - " \"m12\": invariant_mass_squared(sample[\"p0\"], sample[\"p1\"]),\n", - " \"m23\": invariant_mass_squared(sample[\"p1\"], sample[\"p2\"]),\n", - " \"m13\": invariant_mass_squared(sample[\"p0\"], sample[\"p2\"]),\n", - " \"cos_theta\": sample[\"p0\"][:, 3] / np.linalg.norm(sample[\"p0\"][:, 1:], axis=1),\n", - " })\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, df) in zip(axes, variables.items(), strict=True):\n", - " ax.hist2d(df[\"m12\"], df[\"m23\"], bins=150, cmin=1, rasterized=True)\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", @@ -269,143 +203,6 @@ "plt.show()" ] }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Comparing the distributions\n", - "\n", - "Overlaying the projections of both samples shows that they agree within statistical fluctuations. The lower panels show the difference per bin, divided by its statistical uncertainty. These pulls should scatter around zero with a spread of about one." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "jupyter": { - "source_hidden": true - }, - "mystnb": { - "code_prompt_show": "Plot projections with pulls" - }, - "tags": [ - "hide-input" - ] - }, - "outputs": [], - "source": [ - "labels = {\n", - " \"m12\": R\"$m^2_{12}$ [GeV$^2$]\",\n", - " \"m23\": R\"$m^2_{23}$ [GeV$^2$]\",\n", - " \"m13\": R\"$m^2_{13}$ [GeV$^2$]\",\n", - " \"cos_theta\": R\"$\\cos\\theta_0$\",\n", - "}\n", - "fig, axes = plt.subplots(\n", - " 2,\n", - " len(labels),\n", - " figsize=(13, 4.5),\n", - " height_ratios=[3, 1],\n", - " sharex=\"col\",\n", - " layout=\"constrained\",\n", - ")\n", - "default, adaptive = variables.values()\n", - "for (top, bottom), (key, xlabel) in zip(axes.T, labels.items(), strict=True):\n", - " bins = np.linspace(default[key].min(), default[key].max(), 61)\n", - " n_default, _ = np.histogram(default[key], bins)\n", - " n_adaptive, _ = np.histogram(adaptive[key], bins)\n", - " for label, df in variables.items():\n", - " top.hist(df[key], bins, histtype=\"step\", label=label)\n", - " pulls = (n_adaptive - n_default) / np.sqrt(n_adaptive + n_default)\n", - " bottom.stairs(pulls, bins, fill=True, alpha=0.6)\n", - " bottom.axhline(0, color=\"black\", linewidth=0.5)\n", - " bottom.set_ylim(-4, 4)\n", - " bottom.set_xlabel(xlabel)\n", - "axes[0, 0].set_ylabel(\"Events\")\n", - "axes[1, 0].set_ylabel(\"Pull\")\n", - "axes[0, -1].legend(loc=\"lower center\", fontsize=\"small\")\n", - "plt.show()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "A two-sample [Kolmogorov–Smirnov test](https://en.wikipedia.org/wiki/Kolmogorov%E2%80%93Smirnov_test) quantifies this. A $p$-value well above a typical threshold such as $0.05$ means that the test finds no evidence that the two samples come from different distributions. The table also lists the means and standard deviations, which agree to the precision expected for this sample size." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "pd.DataFrame({\n", - " key: {\n", - " \"Mean (default)\": default[key].mean(),\n", - " \"Mean (adaptive)\": adaptive[key].mean(),\n", - " \"Std (default)\": default[key].std(),\n", - " \"Std (adaptive)\": adaptive[key].std(),\n", - " \"KS p-value\": ks_2samp(default[key], adaptive[key]).pvalue,\n", - " }\n", - " for key in labels\n", - "}).T.style.format(\"{:.4f}\")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The same holds for decays into more particles, where the option makes the biggest difference. The comparison below repeats the test for a five-pion decay, using the invariant mass of each pair of neighboring pions." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "jupyter": { - "source_hidden": true - }, - "mystnb": { - "code_prompt_show": "Compare five-pion samples" - }, - "tags": [ - "hide-input" - ] - }, - "outputs": [], - "source": [ - "n_pions = 5\n", - "five_pion_samples = {}\n", - "for adaptive in [False, True]:\n", - " generator = TFPhaseSpaceGenerator(\n", - " initial_state_mass=5.0,\n", - " final_state_masses=dict.fromkeys(range(n_pions), 0.13957),\n", - " adaptive_max_weight=adaptive,\n", - " )\n", - " generator.show_progress = False\n", - " five_pion_samples[adaptive] = generator.generate(\n", - " 100_000, TFUniformRealNumberGenerator(seed=1)\n", - " )\n", - "\n", - "pairs = [(i, i + 1) for i in range(n_pions - 1)]\n", - "fig, axes = plt.subplots(1, len(pairs), figsize=(13, 3), layout=\"constrained\")\n", - "p_values = {}\n", - "for ax, (i, j) in zip(axes, pairs, strict=True):\n", - " m2 = {\n", - " adaptive: invariant_mass_squared(sample[f\"p{i}\"], sample[f\"p{j}\"])\n", - " for adaptive, sample in five_pion_samples.items()\n", - " }\n", - " bins = np.linspace(0, m2[False].max(), 50)\n", - " ax.hist(m2[False], bins, histtype=\"step\", label=\"Default\")\n", - " ax.hist(m2[True], bins, histtype=\"step\", label=\"adaptive_max_weight=True\")\n", - " ax.set_xlabel(Rf\"$m^2_{{{i}{j}}}$ [GeV$^2$]\")\n", - " p_values[f\"m2_{i}{j}\"] = ks_2samp(m2[False], m2[True]).pvalue\n", - "axes[0].set_ylabel(\"Events\")\n", - "axes[-1].legend(fontsize=\"small\")\n", - "plt.show()\n", - "pd.Series(p_values, name=\"KS p-value\").to_frame().style.format(\"{:.3f}\")" - ] - }, { "cell_type": "markdown", "metadata": {}, 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"),