Skip to content

Usage#

GenParticle represents a stable or decaying particle and requires a name and mass. The mass can be an array-like value or a function. A mass function describes a variable mass, such as that of a resonance. It takes four arguments and returns an array-like object of shape (n_events,):

  • The minimum mass allowed by the decay chain, of shape (n_events,).
  • The maximum mass available, of shape (n_events,).
  • The number of events to generate.
  • A JAX PRNG key.

The mass bounds allow the function to account for thresholds and sample kinematically allowed values.

Note

phasespace raises a ValueError if a kinematically forbidden decay is requested.

A simple example#

Use GenParticle.set_children to build a decay chain. For example, the following chain describes \(B^{0}\to K^{*}\gamma\) followed by \(K^*\to K\pi\), with a fixed \(K^*\) mass:

from phasespace import GenParticle
import numpy as np
from particle import literals as lp
import vector

B0_MASS = lp.B_0.mass
KSTARZ_MASS = lp.Kst_892_0.mass
PION_MASS = lp.pi_plus.mass
KAON_MASS = lp.K_plus.mass

pion = GenParticle('pi-', PION_MASS)
kaon = GenParticle('K+', KAON_MASS)
kstar = GenParticle('K*', KSTARZ_MASS).set_children(pion, kaon)
gamma = GenParticle('gamma', 0)
bz = GenParticle('B0', B0_MASS).set_children(kstar, gamma)

Call generate with the desired number of events. It returns:

  • Normalized event weights as an array of shape (n_events,).
  • A dictionary keyed by particle name. Its values are four-momenta represented as arrays of shape (n_events, 4) or as vector.Momentum objects, according to the as_vectors argument.
N_EVENTS = 1000

weights, particles = bz.generate(n_events=N_EVENTS, as_vectors=True)
# or
weights, particles = bz.generate(n_events=N_EVENTS)

Convert JAX arrays to NumPy arrays with np.asarray(obj) when needed.

Boosting the particles#

Particles are generated in the rest frame of the parent at the top of the chain. Pass its four-momentum through boost_to to generate events in another frame. For an example with a distribution of parent momenta, see test_kstargamma_kstarnonresonant_lhc and test_k1gamma_kstarnonresonant_lhc in tests/test_physics.py.

boost_to accepts a four-momentum array with components (px, py, pz, energy) or a vector.Momentum object. An array can have shape (n_events, 4) to specify one momentum per event.

N_EVENTS = 1000

# Generate the top particle with a momentum of 100 GeV
top_momentum = np.array([0, 0, 100, np.sqrt(100**2 + B0_MASS**2)])
# or
top_momentum = vector.array({'px': [0], 'py': [0], 'pz': [100], 'E': [np.sqrt(100**2 + B0_MASS**2)]})
weights, particles = bz.generate(n_events=N_EVENTS, boost_to=top_momentum)

Weights#

Set generate_unnormalized in generate to obtain unnormalized weights. The method then returns the weights, the per-event maximum weight and the particle dictionary.

Repeated generation can use ordinary Python loops:

for i in range(5):
    weights, particles = bz.generate(n_events=100, key=i)
    # ...
    # (do something with weights and particles)
    # ...

Resonances with variable mass#

To sample resonance masses, supply a mass function in place of a fixed value. It receives mass(min_mass, max_mass, n_events, key): per-event lower and upper mass bounds, the number of events and a JAX PRNG key. It must return an array-like object of shape (n_events,) and be compatible with jax.jit, using jax.numpy and jax.random.

Ready-made mass shapes for resonances (Gaussian, Breit-Wigner and relativistic Breit-Wigner) are available in phasespace.fromdecay.mass_functions.

For the preceding example, a Gaussian approximation to the resonance mass gives the following \(B^{0}\to K^{*}\gamma\) chain. See tests/helpers/decays.py for more examples.

import jax
from phasespace import numpy as jnp
from phasespace import GenParticle

KSTARZ_MASS = 895.81
KSTARZ_WIDTH = 47.4

def kstar_mass(min_mass, max_mass, n_events, key):
    # a normal distribution truncated to the kinematically allowed range: jax samples the
    # standard normal within the standardized bounds, which is then scaled back
    standard = jax.random.truncated_normal(key,
                                           lower=(min_mass - KSTARZ_MASS) / KSTARZ_WIDTH,
                                           upper=(max_mass - KSTARZ_MASS) / KSTARZ_WIDTH,
                                           shape=(n_events,),
                                           dtype=jnp.float64)
    return KSTARZ_MASS + KSTARZ_WIDTH * standard

bz = GenParticle('B0', B0_MASS).set_children(GenParticle('K*0', mass=kstar_mass)
                                             .set_children(GenParticle('K+', mass=KAON_MASS),
                                                           GenParticle('pi-', mass=PION_MASS)),
                                             GenParticle('gamma', mass=0.0))

bz.generate(n_events=500)

Shortcut for simple decays#

For a simple \(n\)-body decay, phasespace.nbody_decay takes:

  • The mass of the top particle.
  • A list of daughter masses.
  • The name of the top particle (optional).
  • The names of the daughter particles (optional).

If names are omitted, the function assigns top to the parent and p_{i} to the daughters. For example, to generate \(B^0\to K\pi\):

import phasespace
from particle import literals as lp

N_EVENTS = 1000

B0_MASS = lp.B_0.mass
PION_MASS = lp.pi_plus.mass
KAON_MASS = lp.K_plus.mass

decay = phasespace.nbody_decay(B0_MASS, [PION_MASS, KAON_MASS],
                               top_name="B0", names=["pi", "K"])
weights, particles = decay.generate(n_events=N_EVENTS)

Here, decay is a GenParticle with the specified daughters.

Eager execution#

By default, phasespace compiles generation with jax.jit. On the first call, JAX traces the computation with abstract arrays and compiles it. This incurs an initial cost, while later calls can reuse the compiled computation. Traced values are unavailable to ordinary Python debugging code inside the function.

The number of events is a static argument: a new n_events value triggers compilation, whereas repeated calls with the same value reuse the compiled function. Reusing event counts therefore avoids additional compilation.

For debugging, use jax.disable_jit() or set PHASESPACE_EAGER=1 to run eagerly.

Double precision#

Phase space generation requires double precision for numerical stability. Near threshold, catastrophic cancellation in pdk degrades relative energy-momentum conservation from about 1e-15 to 1e-6 in single precision. Therefore, generate enables JAX's double precision mode for the duration of the call and returns float64 arrays. Importing phasespace leaves the global JAX setting unchanged.

When x64 mode is disabled, subsequent JAX operations may downcast the returned arrays to float32 and issue a warning. Conversion with np.asarray preserves their precision. For subsequent JAX calculations, enable x64 with jax.config.update("jax_enable_x64", True).

The helpers in phasespace.kinematics follow the caller's precision so they remain compatible with jax.jit. Use them with x64 enabled for double precision.

Decays require positive available phase space. At the exact threshold, the phase-space volume and maximum weight are zero, so generation raises ValueError. Boosts support batches containing both stationary and moving parents. Internal boosts use the known invariant mass directly to preserve precision for light intermediate systems.

Rotation coefficients are shared across particles through a JAX optimization barrier. This avoids repeated transcendental evaluations in compiled CPU kernels. The performance benefit depends on event count, hardware and compiler; random draws and precision are unchanged.

Running on a GPU#

Install a JAX build compatible with your CUDA version, for example:

pip install "jax[cuda13]"

JAX provides device selection for phasespace:

import jax

print(jax.devices())  # [CudaDevice(id=0)] once a CUDA-enabled jaxlib is installed

with jax.default_device(jax.devices("gpu")[0]):
    weights, particles = bz.generate(n_events=10_000, key=42)

Alternatively, JAX_PLATFORMS=cuda or JAX_PLATFORMS=cpu selects a backend for the whole run. This setting restricts JAX to the selected backend: for example, jax.devices("cpu") raises RuntimeError under JAX_PLATFORMS=cuda. Leave it unset to access both backends in one process.

The computation is primarily limited by memory bandwidth. Measure performance on your device with benchmark/bench_phasespace.py.

CPU and GPU results can differ by a few units in the last place (ULPs) because their arithmetic differs. The PRNG produces the same draws on both backends.

Memory#

Each event requires 32 bytes per particle for four float64 components, plus 8 bytes for its weight. Generating 10 million B -> 3pi events returns 0.97 GiB of data and peaks at 3.2 GiB of device memory. Budget approximately three times the result size. If generation exceeds available memory, use chunk_size to divide it into batches:

weights, particles = bz.generate(n_events=10_000_000, key=42, chunk_size=1_000_000)

For the same 10 million events, peak memory falls to 2.1 GiB. Chunking bounds the memory used during generation, but the chunks and concatenated result coexist at the end. Consequently, peak memory remains at least about twice the result size, regardless of chunk size. If the result itself does not fit, consume chunks separately.

Each chunk receives a separate split of key. Thus, chunked and unchunked runs with the same key draw different samples, although both remain reproducible. Within one call, generation uses at most two event-count specializations: the full chunk and the remainder. Across calls with different totals, each distinct remainder size can require another compilation.

XLA preallocates 75% of GPU memory on the first computation. On a shared GPU, set XLA_PYTHON_CLIENT_PREALLOCATE=false or XLA_PYTHON_CLIENT_MEM_FRACTION=.5 to limit allocation.

PHASESPACE_EAGER=1 disables JIT compilation and dispatches operations individually. It is useful for CPU debugging but very slow on a GPU.

Random numbers#

JAX random number generation is functional: an explicit key passes through the computation. Functions that generate random numbers therefore take a key argument. It can be:

  • None: create a new key from OS entropy, so the generation is not reproducible.
  • An integer: create a key from that value; reusing the value reproduces the output.
  • A JAX PRNG key created by jax.random.key: use that key directly.

Passing the same key twice returns the same events.