Phase space generators#

Amplitude analysis needs samples of four-momenta that are distributed uniformly over the phase space of a decay. In TensorWaves, such a sample comes from a DataGenerator. The recommended generator is EvtGenPhaseSpaceGenerator, which uses EvtGen through pyevtgen and which all examples in this documentation use. Phase space samples can also be generated with PhaseSpaceGenerator, which uses phasespace with NumPy, JAX, or TensorFlow as computational backend. This page compares the performance and the distributions of these generators. All of them take the same masses and return a DataSample of NumPy arrays with the same structure, so they can be swapped without changing the rest of an analysis.

Hide code cell content

import os
import time

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
from matplotlib_inline.backend_inline import set_matplotlib_formats

os.environ["TF_CPP_MIN_LOG_LEVEL"] = "3"
set_matplotlib_formats("svg")

Available generators#

PhaseSpaceGenerator uses NumPy by default and does not require TensorFlow. Its backend is selected with the backend argument. Each generator below gets a RealNumberGenerator that it can use directly where possible. The function below is the single place that defines which generators this page compares. All tables and figures on this page loop over the generators it returns.

from typing import Literal

from tensorwaves.data import (
    EvtGenPhaseSpaceGenerator,
    NumpyUniformRNG,
    PhaseSpaceGenerator,
    TFUniformRealNumberGenerator,
    WeightedPhaseSpaceGenerator,
)

Backend = Literal["numpy", "jax", "tensorflow"]
backends: dict[str, Backend] = {
    "NumPy": "numpy",
    "JAX": "jax",
    "TensorFlow": "tensorflow",
}


def create_rng(backend: Backend) -> NumpyUniformRNG | TFUniformRealNumberGenerator:
    if backend == "tensorflow":
        return TFUniformRealNumberGenerator(seed=0)
    return NumpyUniformRNG(seed=0)


def create_generators(
    initial_state_mass: float,
    final_state_masses: dict[int, float],
    *,
    weighted: bool = False,
) -> dict:
    masses = initial_state_mass, final_state_masses
    if weighted:
        return {
            f"phasespace ({label}, weighted)": (
                WeightedPhaseSpaceGenerator(*masses, backend=backend),
                create_rng(backend),
            )
            for label, backend in backends.items()
        }
    generators = {
        "EvtGen": (EvtGenPhaseSpaceGenerator(*masses), NumpyUniformRNG(seed=0))
    }
    for label, backend in backends.items():
        generator = PhaseSpaceGenerator(*masses, backend=backend)
        generator.show_progress = False
        generators[f"phasespace ({label})"] = generator, create_rng(backend)
    return generators

Generator

Package

Extra

Events

Use of the RealNumberGenerator

EvtGenPhaseSpaceGenerator

pyevtgen

evtgen

unweighted

any type only provides a seed

PhaseSpaceGenerator with backend="numpy" (default)

phasespace

phsp

unweighted through hit-and-miss

NumpyUniformRNG is used directly, any other type only provides a seed

PhaseSpaceGenerator with backend="jax"

phasespace

phsp,jax

unweighted through hit-and-miss

any type only provides a seed

PhaseSpaceGenerator with backend="tensorflow"

phasespace

phsp,tf

unweighted through hit-and-miss

TFUniformRealNumberGenerator is used directly, any other type only provides a seed

WeightedPhaseSpaceGenerator takes the same backend argument and returns weighted events instead. The installation of these extras is described on Installation.

Comparing distributions#

We generate a sample for a three-body decay with each generator. The events of different generators are not identical, not even with the same seed, but they should follow the same distribution.

generators = create_generators(
    initial_state_mass=3.0969,
    final_state_masses={0: 0.1350, 1: 0.1396, 2: 0.4937},
)
n_events = 500_000
samples = {
    name: generator.generate(n_events, rng)
    for name, (generator, rng) in generators.items()
}

Hide code cell source

pd.DataFrame(
    {
        "Array type": [type(sample["p0"]).__name__ for sample in samples.values()],
        "Final state": [sorted(sample) for sample in samples.values()],
        "Shape": [sample["p0"].shape for sample in samples.values()],
    },
    index=list(samples),
)
Array type Final state Shape
EvtGen ndarray [p0, p1, p2] (500000, 4)
phasespace (NumPy) ndarray [p0, p1, p2] (500000, 4)
phasespace (JAX) ndarray [p0, p1, p2] (500000, 4)
phasespace (TensorFlow) ndarray [p0, p1, p2] (500000, 4)

A uniform phase space sample shows up as a flat Dalitz plot within the kinematic boundary.

Hide code cell source

def invariant_mass_squared(p: np.ndarray) -> np.ndarray:
    return p[:, 0] ** 2 - np.sum(p[:, 1:] ** 2, axis=1)


fig, axes = plt.subplots(
    ncols=len(samples), figsize=(3 * len(samples), 3), sharex=True, sharey=True
)
for ax, (name, sample) in zip(np.atleast_1d(axes), samples.items(), strict=True):
    s01 = invariant_mass_squared(sample["p0"] + sample["p1"])
    s12 = invariant_mass_squared(sample["p1"] + sample["p2"])
    ax.hist2d(s01, s12, bins=60, cmin=1, rasterized=True)
    ax.set_title(name, fontsize="small")
    ax.set_xlabel("$m_{01}^2$ [GeV$^2$]")
np.atleast_1d(axes)[0].set_ylabel("$m_{12}^2$ [GeV$^2$]")
fig.tight_layout()
plt.show()
../_images/a9a3bcf414e8dfe52019d7beaa0dc41251aeb30b68d9b441ae70a752255b5b7d.svg

The invariant mass projections should agree between generators. The lower panels show the ratio of each generator to EvtGen, with the statistical uncertainty of the EvtGen sample as a band.

Hide code cell source

pairs = {"m_{01}": ("p0", "p1"), "m_{02}": ("p0", "p2"), "m_{12}": ("p1", "p2")}
reference = next(iter(samples))
histograms = {}
fig, axes = plt.subplots(
    nrows=2,
    ncols=len(pairs),
    figsize=(4 * len(pairs), 4.5),
    height_ratios=[3, 1],
    sharex="col",
)
for (top, bottom), (label, (a, b)) in zip(axes.T, pairs.items(), strict=True):
    masses = {
        name: np.sqrt(invariant_mass_squared(sample[a] + sample[b]))
        for name, sample in samples.items()
    }
    edges = np.histogram_bin_edges(masses[reference], bins=60)
    counts = {name: np.histogram(m, bins=edges)[0] for name, m in masses.items()}
    histograms[label] = counts
    reference_counts = np.where(counts[reference] > 0, counts[reference], np.nan)
    for name, n in counts.items():
        top.stairs(n, edges, label=name)
        if name != reference:
            bottom.stairs(n / reference_counts, edges, label=name)
    bottom.stairs(
        1 + 1 / np.sqrt(reference_counts),
        edges,
        baseline=1 - 1 / np.sqrt(reference_counts),
        fill=True,
        color="lightgray",
        zorder=0,
    )
    bottom.set_ylim(0.9, 1.1)
    bottom.set_xlabel(f"${label}$ [GeV]")
axes[0, 0].set_ylabel("Events")
axes[1, 0].set_ylabel("Ratio")
axes[0, 0].legend(fontsize="small")
fig.tight_layout()
plt.show()
../_images/39da7232fd9d7b96f5640a579216461c1bb690f6745d66473ecea9cb5f1f95ad.svg

To quantify the agreement, we compute a two-sample \(\chi^2\) per degree of freedom between each generator and EvtGen, using bins with sufficient statistics. Values around one mean that the samples are statistically compatible.

def chi2_per_dof(n1: np.ndarray, n2: np.ndarray) -> float:
    mask = n1 + n2 > 50
    return np.sum((n1 - n2)[mask] ** 2 / (n1 + n2)[mask]) / np.count_nonzero(mask)


pd.DataFrame({
    f"${label}$": {
        name: chi2_per_dof(n, counts[reference])
        for name, n in counts.items()
        if name != reference
    }
    for label, counts in histograms.items()
}).round(2)
$m_{01}$ $m_{02}$ $m_{12}$
phasespace (NumPy) 1.08 0.83 1.08
phasespace (JAX) 1.27 1.03 0.98
phasespace (TensorFlow) 1.31 1.04 0.87

Four-body decays#

A three-body decay has two independent kinematic variables, so its phase space fits in a single Dalitz plot. A four-body decay has five, and no single plot shows them all. A common choice is the set of Cabibbo–Maksymowicz variables, which split the decay into two pairs of particles:

  • the invariant masses \(m_{01}\) and \(m_{23}\) of the two pairs,

  • the helicity angles \(\theta_{01}\) and \(\theta_{23}\) of particles \(0\) and \(2\) in the rest frames of their pairs,

  • the angle \(\phi\) between the two decay planes.

For a uniform phase space sample, \(\cos\theta_{01}\), \(\cos\theta_{23}\) and \(\phi\) are distributed uniformly, while the two masses are not. As an example, we generate \(D^0 \to K^-\pi^+\pi^+\pi^-\) with each generator.

four_body_masses = {0: 0.4937, 1: 0.1396, 2: 0.1396, 3: 0.1396}
four_body_samples = {
    name: generator.generate(100_000, rng)
    for name, (generator, rng) in create_generators(1.8648, four_body_masses).items()
}

Hide code cell source

def boost_to_rest_frame(p: np.ndarray, frame: np.ndarray) -> np.ndarray:
    beta = frame[:, 1:] / frame[:, :1]
    beta_squared = np.sum(beta**2, axis=1, keepdims=True)
    gamma = 1 / np.sqrt(1 - beta_squared)
    beta_dot_p = np.sum(beta * p[:, 1:], axis=1, keepdims=True)
    energy = gamma * (p[:, :1] - beta_dot_p)
    momentum = (
        p[:, 1:] + ((gamma - 1) * beta_dot_p / beta_squared - gamma * p[:, :1]) * beta
    )
    return np.concatenate([energy, momentum], axis=1)


def unit(v: np.ndarray) -> np.ndarray:
    return v / np.linalg.norm(v, axis=1, keepdims=True)


def cabibbo_maksymowicz(sample: dict[str, np.ndarray]) -> dict[str, np.ndarray]:
    p0, p1, p2, p3 = (sample[f"p{i}"] for i in range(4))
    p01 = p0 + p1
    p23 = p2 + p3
    z = unit(p01[:, 1:])
    n01 = unit(np.cross(p0[:, 1:], p1[:, 1:]))
    n23 = unit(np.cross(p2[:, 1:], p3[:, 1:]))
    sin_phi = np.sum(np.cross(n01, n23) * z, axis=1)
    cos_phi = np.sum(n01 * n23, axis=1)
    return {
        "$m_{01}$ [GeV]": np.sqrt(invariant_mass_squared(p01)),
        "$m_{23}$ [GeV]": np.sqrt(invariant_mass_squared(p23)),
        R"$\cos\theta_{01}$": np.sum(
            unit(boost_to_rest_frame(p0, p01)[:, 1:]) * z, axis=1
        ),
        R"$\cos\theta_{23}$": np.sum(
            unit(boost_to_rest_frame(p2, p23)[:, 1:]) * -z, axis=1
        ),
        R"$\phi$": np.arctan2(sin_phi, cos_phi),
    }


variables = {name: cabibbo_maksymowicz(s) for name, s in four_body_samples.items()}
labels = list(next(iter(variables.values())))
fig, axes = plt.subplots(ncols=len(labels), figsize=(3 * len(labels), 3), sharey=True)
for ax, label in zip(axes, labels, strict=True):
    for name, values in variables.items():
        ax.hist(values[label], bins=50, histtype="step", label=name)
    ax.set_xlabel(label)
axes[0].set_ylabel("Events")
axes[-1].legend()
fig.tight_layout()
plt.show()
../_images/5a089866ed81a3e5e68b437923b2b781d993323ab0d993bcead279915d1eca00.svg

The variables are not independent in their ranges: the sum of the two pair masses cannot exceed the mass of the decaying particle. A two-dimensional histogram of \(m_{01}\) against \(m_{23}\) shows this kinematic boundary, which plays a role similar to the boundary of the Dalitz plot.

Hide code cell source

fig, axes = plt.subplots(
    ncols=len(variables), figsize=(4 * len(variables), 3.5), sharex=True, sharey=True
)
for ax, (name, values) in zip(np.atleast_1d(axes), variables.items(), strict=True):
    ax.hist2d(values[labels[0]], values[labels[1]], bins=60, cmin=1, rasterized=True)
    ax.set_title(name)
    ax.set_xlabel(labels[0])
np.atleast_1d(axes)[0].set_ylabel(labels[1])
fig.tight_layout()
plt.show()
../_images/43f05a0ab46ffcf661527e5ed096b882cd82d899461c6836fd20e8b0bea67268.svg

Benchmark#

We measure how long each generator takes as a function of the sample size and of the number of final state particles, for a particle with a mass of \(5\,\mathrm{GeV}\) that decays into pions. Besides the unweighted generators, we also time WeightedPhaseSpaceGenerator, which skips the hit-and-miss step of PhaseSpaceGenerator. TensorFlow and JAX compile functions the first time they are called and phasespace compiles them again after each change of backend, so each measurement is preceded by a small call that is not timed. The fastest of three repetitions is shown, which limits the influence of other processes on the machine. These timings only give an impression for these decays on the machine that builds this page.

def measure(generator, rng, size: int) -> float:
    generator.generate(1_000, rng)
    durations = []
    for _ in range(3):
        start = time.perf_counter()
        generator.generate(size, rng)
        durations.append(time.perf_counter() - start)
    return min(durations)


def create_all_generators(n_particles: int) -> dict:
    pions = dict.fromkeys(range(n_particles), pion_mass)
    return {
        **create_generators(parent_mass, pions),
        **create_generators(parent_mass, pions, weighted=True),
    }


parent_mass = 5.0
pion_mass = 0.1396
sample_sizes = [10_000, 30_000, 100_000, 300_000]
timings_by_size = {
    name: [measure(generator, rng, size) for size in sample_sizes]
    for name, (generator, rng) in create_all_generators(3).items()
}

particle_counts = [3, 4, 5, 6, 7, 8]
max_hit_and_miss_particles = 6
timings_by_particles: dict[str, dict[int, float]] = {}
for n_particles in particle_counts:
    for name, (generator, rng) in create_all_generators(n_particles).items():
        is_hit_and_miss = isinstance(generator, PhaseSpaceGenerator)
        if is_hit_and_miss and n_particles > max_hit_and_miss_particles:
            continue
        timings = timings_by_particles.setdefault(name, {})
        timings[n_particles] = measure(generator, rng, 10_000)

Hide code cell source

fig, (ax1, ax2) = plt.subplots(ncols=2, figsize=(11, 4))
for name, timings in timings_by_size.items():
    linestyle = "--" if "weighted" in name else "-"
    ax1.plot(sample_sizes, timings, marker="o", linestyle=linestyle, label=name)
for name, timings in timings_by_particles.items():
    linestyle = "--" if "weighted" in name else "-"
    ax2.plot(list(timings), list(timings.values()), marker="o", linestyle=linestyle)
ax1.set_xscale("log")
ax1.set_xlabel("Number of events")
ax1.set_title("Three-body decay")
ax2.set_xlabel("Number of final state particles")
ax2.set_title("10,000 events")
for ax in (ax1, ax2):
    ax.set_yscale("log")
    ax.set_ylabel("Time [s]")
fig.legend(loc="outside right center", fontsize="small")
fig.tight_layout(rect=(0, 0, 0.75, 1))
plt.show()
../_images/3b0045917cb7d615f20b572f6f1bdc340b290b0c6043bafc3b6f02b1eecb40de.svg

Hide code cell source

df_benchmark = pd.DataFrame(timings_by_particles).T
df_benchmark.columns = [f"{n} particles [s]" for n in df_benchmark.columns]
df_benchmark.round(4)
3 particles [s] 4 particles [s] 5 particles [s] 6 particles [s] 7 particles [s] 8 particles [s]
EvtGen 0.0029 0.0057 0.0123 0.0908 0.9894 12.2655
phasespace (NumPy) 0.0348 0.2313 2.2190 23.1430 NaN NaN
phasespace (JAX) 0.0282 0.1945 1.8317 19.5646 NaN NaN
phasespace (TensorFlow) 0.0255 0.1645 1.5383 17.4776 NaN NaN
phasespace (NumPy, weighted) 0.0078 0.0123 0.0184 0.0257 0.0333 0.0420
phasespace (JAX, weighted) 0.0107 0.0150 0.0214 0.0273 0.0353 0.0434
phasespace (TensorFlow, weighted) 0.0057 0.0092 0.0128 0.0178 0.0223 0.0293

EvtGen is the fastest unweighted generator, and its advantage grows with the number of final state particles. The reason is the hit-and-miss step of PhaseSpaceGenerator: phasespace normalizes its weights to an upper bound that is much larger than the actual maximum weight, so an event is only accepted with a probability that equals its weight. The fraction of accepted events, which is the mean weight, drops quickly with the number of particles:

Hide code cell source

pd.DataFrame({
    "Mean weight": {
        n: WeightedPhaseSpaceGenerator(parent_mass, dict.fromkeys(range(n), pion_mass))
        .generate(100_000, NumpyUniformRNG(seed=0))["weights"]
        .mean()
        for n in particle_counts
    }
}).rename_axis("Final state particles").map("{:.1e}".format)
Mean weight
Final state particles
3 2.7e-01
4 5.2e-02
5 7.9e-03
6 9.9e-04
7 1.1e-04
8 1.0e-05

This is why the hit-and-miss PhaseSpaceGenerator is left out beyond six particles. The weighted generators themselves are fast. TensorFlow and JAX pay for compilation on the first call, but are faster than NumPy afterwards, especially for many final state particles.

Which generator to choose#

EvtGenPhaseSpaceGenerator is the default choice: it is the fastest generator of unweighted events and needs neither TensorFlow nor JAX. It works with any RealNumberGenerator, which only provides a seed for the random engine of EvtGen. There are two limitations:

  • It provides no weights, because EvtGen applies accept-reject sampling internally. The IntensityDistributionGenerator does not need them, as the Amplitude analysis page shows.

  • Its accept-reject efficiency depends on the masses of the final state. Generation can become impractically slow for many final state particles, and a running call cannot be interrupted.

PhaseSpaceGenerator and WeightedPhaseSpaceGenerator are useful where pyevtgen is not available. With the NumPy backend, phasespace only depends on NumPy, so these generators may also work where neither pyevtgen, TensorFlow, nor JAX can be installed, for instance in the browser through Pyodide. This has not been tested. Prefer WeightedPhaseSpaceGenerator as domain generator of an IntensityDistributionGenerator, because that avoids the inefficient hit-and-miss step that the benchmark shows. TensorFlow and JAX are worth it when generating large or many samples for the same decay. TensorFlow reproduces samples from earlier TensorWaves versions, when combined with a TFUniformRealNumberGenerator. JAX can be useful if the rest of the analysis already uses it. There are two things to keep in mind with these backends:

  • The same seed gives a different sample on each backend. Samples are only reproducible within one backend.

  • 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 slower than the timings above suggest, and generators with different backends should not be used concurrently in threads.