Phase space generators#
Amplitude analysis needs samples of four-momenta that are distributed uniformly over the phase space of a decay. PhaseSpaceGenerator produces such samples with phasespace, which can run on NumPy, TensorFlow, or JAX. phasespace generates weighted events, so PhaseSpaceGenerator turns them into unweighted events with a hit-and-miss step: an event is kept if a uniform random number is below its weight. WeightedPhaseSpaceGenerator 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.
Backends#
The backend is selected with the backend argument of the generator. All backends return a DataSample of NumPy arrays with the same structure, so they can be swapped without changing the rest of an analysis.
from tensorwaves.data import (
NumpyUniformRNG,
PhaseSpaceGenerator,
TFUniformRealNumberGenerator,
)
initial_state_mass = 3.0969
final_state_masses = {0: 0.1350, 1: 0.1396, 2: 0.4937}
generators = {
"numpy": (
PhaseSpaceGenerator(initial_state_mass, final_state_masses, backend="numpy"),
NumpyUniformRNG(seed=0),
),
"tensorflow": (
PhaseSpaceGenerator(
initial_state_mass, final_state_masses, backend="tensorflow"
),
TFUniformRealNumberGenerator(seed=0),
),
"jax": (
PhaseSpaceGenerator(initial_state_mass, final_state_masses, backend="jax"),
NumpyUniformRNG(seed=0),
),
}
for generator, _ in generators.values():
generator.show_progress = False
|
Extra |
Use of the |
|---|---|---|
|
|
|
|
|
|
|
|
any type only provides a seed |
The installation of these extras is described on Installation.
Every backend is used through the same 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.
NumPy is the default choice, because it needs no additional dependencies and no compilation. 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. 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. TR-039 benchmarks the backends and compares their distributions for three-body and four-body decays.
There are two things to keep in mind:
The same seed gives a different sample on each backend. Samples are only reproducible within one backend.
phasespaceselects its backend per process, and a generator activates its backend each time it generates. Each switch makesphasespacerecompile, so alternating between backends is slow, and generators with different backends should not be used concurrently in threads.
Adaptive maximum weight#
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.
The option is keyword-only and is off by default, so existing code keeps producing the same events for the same seed.
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.
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. TR-038 benchmarks this and confirms with statistical tests that both settings produce the same distributions.
Usage#
The option is a keyword argument of PhaseSpaceGenerator. 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.
initial_state_mass = 3.0969
final_state_masses = {0: 0.1350, 1: 0.1396, 2: 0.4937}
default_generator = PhaseSpaceGenerator(initial_state_mass, final_state_masses)
adaptive_generator = PhaseSpaceGenerator(
initial_state_mass, final_state_masses, adaptive_max_weight=True
)
size = 500_000
default_generator.show_progress = False
adaptive_generator.show_progress = False
samples = {
"Default": default_generator.generate(size, NumpyUniformRNG(seed=0)),
"adaptive_max_weight=True": adaptive_generator.generate(
size, NumpyUniformRNG(seed=0)
),
}
When to use it#
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.