Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 115 additions & 17 deletions docs/amplitude-analysis/phase-space.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
"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."
"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), which can run on TensorFlow, NumPy, or JAX. `phasespace` 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. {class}`.TFWeightedPhaseSpaceGenerator` returns the weighted events instead. This page shows how to select a backend and how the `adaptive_max_weight` option makes the hit-and-miss step faster without changing the generated distribution."
]
},
{
Expand All @@ -35,25 +35,129 @@
},
"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",
"## Backends\n",
"\n",
"The backend is selected with the `backend` argument of the generator. All backends return a {obj}`.DataSample` of NumPy arrays with the same structure, so they can be swapped without changing the rest of an analysis."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from tensorwaves.data import (\n",
" NumpyUniformRNG,\n",
" TFPhaseSpaceGenerator,\n",
" TFUniformRealNumberGenerator,\n",
")\n",
"\n",
"initial_state_mass = 3.0969\n",
"final_state_masses = {0: 0.1350, 1: 0.1396, 2: 0.4937}\n",
"generators = {\n",
" \"numpy\": (\n",
" TFPhaseSpaceGenerator(initial_state_mass, final_state_masses, backend=\"numpy\"),\n",
" NumpyUniformRNG(seed=0),\n",
" ),\n",
" \"tensorflow\": (\n",
" TFPhaseSpaceGenerator(\n",
" initial_state_mass, final_state_masses, backend=\"tensorflow\"\n",
" ),\n",
" TFUniformRealNumberGenerator(seed=0),\n",
" ),\n",
" \"jax\": (\n",
" TFPhaseSpaceGenerator(initial_state_mass, final_state_masses, backend=\"jax\"),\n",
" NumpyUniformRNG(seed=0),\n",
" ),\n",
"}\n",
"for generator, _ in generators.values():\n",
" generator.show_progress = False"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"| `backend` | Extra | Use of the {class}`.RealNumberGenerator` |\n",
"| --- | --- | --- |\n",
"| `\"tensorflow\"` (default) | `phsp` | {class}`.TFUniformRealNumberGenerator` is used directly, any other type only provides a seed |\n",
"| `\"numpy\"` | `phsp` | {class}`.NumpyUniformRNG` is used directly, any other type only provides a seed |\n",
"| `\"jax\"` | `phsp,jax` | any type only provides a seed |\n",
"\n",
"The NumPy and JAX backends require `phasespace` 2.0 or higher. The installation of these extras is described on {doc}`/install`."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Every backend is used through the same {meth}`~.TFPhaseSpaceGenerator.generate` method. The events of different backends are not identical, not even with the same seed, but they follow the same distribution: a uniform phase space sample shows up as a flat Dalitz plot within the kinematic boundary."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"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",
"backend_samples = {\n",
" name: generator.generate(100_000, rng)\n",
" for name, (generator, rng) in generators.items()\n",
"}\n",
"fig, axes = plt.subplots(\n",
" ncols=len(backend_samples), figsize=(4 * len(backend_samples), 3.5), sharey=True\n",
")\n",
"for ax, (name, sample) in zip(axes, backend_samples.items(), strict=True):\n",
" s01 = invariant_mass_squared(sample[\"p0\"], sample[\"p1\"])\n",
" s12 = invariant_mass_squared(sample[\"p1\"], sample[\"p2\"])\n",
" ax.hist2d(s01, s12, bins=60, cmin=1, rasterized=True)\n",
" ax.set_title(name)\n",
" ax.set_xlabel(R\"$m_{01}^2$ [GeV$^2$]\")\n",
"axes[0].set_ylabel(R\"$m_{12}^2$ [GeV$^2$]\")\n",
"fig.tight_layout()\n",
"plt.show()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"TensorFlow is the default, because it reproduces the samples of earlier TensorWaves versions, when combined with a {class}`.TFUniformRealNumberGenerator`. NumPy needs no compilation, so it is the fastest choice for a few small samples. TensorFlow and JAX compile functions on the first call, but are several times faster afterwards, so they are worth it when generating large or many samples for the same decay. JAX can be useful if the rest of the analysis already uses it. {doc}`TR-039 <compwa-report:039/index>` benchmarks the backends and compares their distributions for three-body and four-body decays.\n",
"\n",
"There are two things to keep in mind:\n",
"\n",
"- The same seed gives a different sample on each backend. Samples are only reproducible within one backend.\n",
"- `phasespace` selects its backend per process, and a generator activates its backend each time it generates. Each switch makes `phasespace` recompile, so alternating between backends is slow, and generators with different backends should not be used concurrently in threads."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Adaptive 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",
Expand Down Expand Up @@ -83,16 +187,17 @@
},
"outputs": [],
"source": [
"from tensorwaves.data import TFUniformRealNumberGenerator, TFWeightedPhaseSpaceGenerator\n",
"from tensorwaves.data import 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",
" backend=\"numpy\",\n",
" )\n",
" rng = TFUniformRealNumberGenerator(seed=0)\n",
" rng = NumpyUniformRNG(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",
Expand Down Expand Up @@ -126,7 +231,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## Usage\n",
"### 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."
]
Expand All @@ -137,8 +242,6 @@
"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",
Expand Down Expand Up @@ -180,11 +283,6 @@
},
"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",
Expand All @@ -207,7 +305,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## When to use the option\n",
"### When to use it\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."
]
Expand Down
1 change: 1 addition & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -259,6 +259,7 @@ def get_tensorflow_url() -> str:
nb_render_markdown_format = "myst"
nitpick_ignore = [
("std:doc", "compwa-report:038/index"),
("std:doc", "compwa-report:039/index"),
("py:class", "tensorflow.keras.losses.Loss"),
("py:class", "tensorflow.python.keras.losses.Loss"),
("py:obj", "Loss"),
Expand Down
1 change: 1 addition & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,7 @@ style = [
{ include-group = "types" },
]
test = [
"phasespace>=2.0.0",
"pyarrow",
"pytest-benchmark",
"pytest-cov",
Expand Down
85 changes: 66 additions & 19 deletions src/tensorwaves/data/phasespace.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
from __future__ import annotations

import logging
from typing import TYPE_CHECKING
from typing import TYPE_CHECKING, Literal

import numpy as np
from tqdm.auto import tqdm
Expand All @@ -17,17 +17,26 @@
merge_events,
select_events,
)
from .rng import TFUniformRealNumberGenerator
from .rng import NumpyUniformRNG, TFUniformRealNumberGenerator

if TYPE_CHECKING:
from collections.abc import Mapping

import tensorflow as tf

Backend = Literal["numpy", "tensorflow", "jax"]
"""Computational backend used by the phase space generators."""

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

_BACKEND_EXTRAS: dict[str, tuple[str, str]] = {
"numpy": ("numpy", ""),
"tensorflow": ("tensorflow", "tf"),
"jax": ("jax", "jax"),
}


class TFPhaseSpaceGenerator(DataGenerator):
"""Implements a phase space generator using tensorflow.
Expand All @@ -45,6 +54,7 @@ class TFPhaseSpaceGenerator(DataGenerator):
`.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`.
:param backend: Computational backend of `TFWeightedPhaseSpaceGenerator`.
"""

def __init__(
Expand All @@ -54,9 +64,10 @@ def __init__(
bunch_size: int = 50_000,
*,
adaptive_max_weight: bool = False,
backend: Backend = "tensorflow",
) -> None:
self.__phsp_generator = TFWeightedPhaseSpaceGenerator(
initial_state_mass, final_state_masses
initial_state_mass, final_state_masses, backend=backend
)
self.__bunch_size = bunch_size
self.__adaptive_max_weight = adaptive_max_weight
Expand Down Expand Up @@ -122,6 +133,12 @@ class TFWeightedPhaseSpaceGenerator(DataGenerator):

:param initial_state_mass: Mass of the decaying state.
:param final_state_masses: Masses keyed by final-state ID.
:param backend: Computational backend that `phasespace
<https://github.com/zfit/phasespace>`_ uses to generate the sample. The
``"numpy"`` and ``"jax"`` backends require ``phasespace`` 2.0 or higher, and
``"jax"`` also requires the ``jax`` extra. The generated arrays are always NumPy
arrays. A `.RealNumberGenerator` that does not belong to the backend provides a
seed, so samples stay reproducible.

.. seealso::

Expand All @@ -132,11 +149,16 @@ def __init__(
self,
initial_state_mass: float,
final_state_masses: Mapping[int, float],
*,
backend: Backend = "tensorflow",
) -> None:
try:
import phasespace # ruff:ignore[import-outside-top-level]
except ImportError: # pragma: no cover
raise_missing_module_error("phasespace", extras_require="phsp")
if backend not in _BACKEND_EXTRAS:
msg = f'Backend must be one of {sorted(_BACKEND_EXTRAS)}, got "{backend}"'
raise ValueError(msg)
self.__backend = backend
_activate_backend(backend)
import phasespace # ruff:ignore[import-outside-top-level]

sorted_ids = sorted(final_state_masses)
self.__phsp_gen = phasespace.nbody_decay(
mass_top=initial_state_mass,
Expand All @@ -151,23 +173,48 @@ def generate(self, size: int, rng: RealNumberGenerator) -> DataSample:
A `tuple` of a `.DataSample` (**four-momenta**) with an event-wise sequence
of weights. The four-momenta are arrays of shape :math:`n \times 4`.
"""
if not isinstance(rng, TFUniformRealNumberGenerator):
msg = (
f"{type(self).__name__} requires a"
f" {TFUniformRealNumberGenerator.__name__}, but got a"
f" {type(rng).__name__}"
)
raise TypeError(msg)
weights, particles = self.__phsp_gen.generate(n_events=size, seed=rng.generator)
_activate_backend(self.__backend)
weights, particles = self.__phsp_gen.generate(
n_events=size, seed=_get_seed(rng, self.__backend)
)
phsp_momenta = {
f"p{label}": _to_numpy(momenta)[:, [3, 0, 1, 2]]
f"p{label}": np.asarray(momenta)[:, [3, 0, 1, 2]]
for label, momenta in particles.items()
}
return {
"weights": _to_numpy(weights),
"weights": np.asarray(weights),
**phsp_momenta,
}


def _to_numpy(tensor: tf.Tensor) -> np.ndarray:
return tensor.numpy()
def _activate_backend(backend: Backend) -> None:
"""Select the process-wide `phasespace` backend.

The previous backend is deliberately not restored afterwards, because each switch
makes `phasespace` recompile its functions, which would happen for every bunch.
Versions of `phasespace` before 2.0 only support TensorFlow.
"""
try:
import phasespace # ruff:ignore[import-outside-top-level]
except ImportError: # pragma: no cover
raise_missing_module_error("phasespace", extras_require="phsp")
if not hasattr(phasespace, "set_backend"): # pragma: no cover
if backend != "tensorflow":
msg = f'Backend "{backend}" requires phasespace 2.0 or higher'
raise ValueError(msg)
return
try:
phasespace.set_backend(backend)
except ImportError: # pragma: no cover
module_name, extra = _BACKEND_EXTRAS[backend]
raise_missing_module_error(module_name, extras_require=extra)


def _get_seed(
rng: RealNumberGenerator, backend: Backend
) -> int | np.random.Generator | tf.random.Generator:
if backend == "numpy" and isinstance(rng, NumpyUniformRNG):
return rng.generator
if backend == "tensorflow" and isinstance(rng, TFUniformRealNumberGenerator):
return rng.generator
return int(rng(1, min_value=0, max_value=2**31 - 1)[0])
Loading
Loading