Skip to main content

phasespace-jax

tests docs PyPI License: BSD-3-Clause

This repository is a fork of zfit/phasespace. For background information and citations in scientific publications, consult the original project. See also License and attribution and Citing.

Differences from the upstream package

This fork replaces TensorFlow with JAX and supports compilation with jax.jit. It retains the GENBOD (Raubold–Lynch) algorithm described in CERN-68-15 (see Physics validation). However, TensorFlow and JAX use different random streams, so the same integer seed does not produce bit-identical events across the two packages. The API, return values and DecayLanguage integration remain largely compatible with the upstream package. See the documentation for details.

Aspect zfit/phasespace this fork
Backend TensorFlow JAX
Compilation tf.function jax.jit, with n_events as a static argument
Random numbers seed=, stateful tf.random.Generator key=, functional JAX PRNG key
n_events int, tf.Tensor or tf.Variable Python int; a new value triggers compilation
Mass functions f(min_mass, max_mass, n_events[, seed]), TFP or zfit PDFs f(min_mass, max_mass, n_events, key); must be compatible with jax.jit
Resonance shapes in fromdecay zfit / zfit-physics PDFs sampled directly in JAX, no zfit dependency
Forbidden decays tf.errors.InvalidArgumentError ValueError
phasespace.numpy tensorflow.experimental.numpy jax.numpy
Distribution name phasespace phasespace-jax, imported as phasespace
Speed reference ≈4-5x faster for 1M B -> 3pi events on CPU

Event generation requires double precision; see JAX treats and traps.

Installing

To install with pip:

$ pip install phasespace-jax

To install the dependencies for DecayLanguage, use:

$ pip install "phasespace-jax[fromdecay]"

For GPU use, install a JAX build compatible with your CUDA version, for example:

$ pip install "jax[cuda13]"   # SM 7.5 and newer, Turing onwards (driver >= 580)

How to use

The DecayChain tutorial shows how to generate events from a DecayChain using DecayLanguage.

For a simple $n$-body decay, nbody_decay constructs the decay chain from the parent mass and a list of daughter masses. Particle names are optional. Then, generate produces the event sample. For example, to generate $B^0\to K\pi$:

import phasespace

B0_MASS = 5279.65
PION_MASS = 139.57018
KAON_MASS = 493.677

weights, particles = phasespace.nbody_decay(
    B0_MASS, [PION_MASS, KAON_MASS]
).generate(n_events=1000)

Here, weights is a jax.Array with 1000 entries. The particles dictionary contains one (1000, 4) array per particle; each row is a four-momentum. Use np.asarray(...) to convert JAX arrays to NumPy arrays. Events are generated in the parent rest frame. To generate them with a specified parent momentum, pass it through boost_to.

For sequential decays, use GenParticle and its set_children method. For example, the following chain describes $B^{0}\to K^{}\gamma$ followed by $K^\to K\pi$:

from phasespace import GenParticle

B0_MASS = 5279.65
KSTARZ_MASS = 895.55
PION_MASS = 139.57018
KAON_MASS = 493.677

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

weights, particles = bz.generate(n_events=1000)

Because set_children returns the parent particle, the calls can be chained. Here, particles is a dictionary keyed by particle name:

>>> particles
{'K*': array([[2047.68762461, 1541.15862236,  -72.4256177 , 2715.77793272],
              [1469.35084777, -400.29068127, 2062.57495234, 2715.77793272],
              ...]),
 'K+': array([[1726.88981662,  960.17876701,  -50.47103598, 2037.24225589],
              [ 934.90807089, -454.07101908, 1033.69378006, 1546.7622321 ],
              ...]),
 'gamma': array([[-2047.68762461, -1541.15862236,    72.4256177 ,  2563.87206728],
                 [-1469.35084777,   400.29068127, -2062.57495234,  2563.87206728],
                 ...]),
 'pi-': array([[ 320.79780799,  580.97985535,  -21.95458172,  678.53567684],
               [ 534.44277688,   53.78033781, 1028.88117228, 1169.01570063],
               ...])}

Reproducibility

JAX random number generation is purely functional: instead of a global generator state, an explicit key is passed in. generate accepts an integer seed, a jax.random key, or None:

import jax

weights, particles = bz.generate(n_events=1000, key=42)          # reproducible
weights, particles = bz.generate(n_events=1000, key=jax.random.key(42))  # the same
weights, particles = bz.generate(n_events=1000)                  # fresh key, not reproducible

Passing the same key twice returns the same events.

JAX Treats and Traps

Event generation is compiled with jax.jit. 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:

for i in range(10):
    weights, particles = bz.generate(n_events=1000, key=i)

Set PHASESPACE_EAGER=1 or use jax.disable_jit() to run eagerly when debugging.

Phase space generation requires double precision for numerical stability. generate enables JAX's double precision mode for the duration of the call and returns float64 arrays. Importing phasespace does not change the global JAX setting. To retain 64-bit precision in subsequent JAX operations, enable it for your program:

import jax
jax.config.update("jax_enable_x64", True)

With x64 mode disabled, subsequent JAX operations may downcast the arrays to float32 and issue a warning. Conversion with np.asarray(...) preserves their precision.

Running on a GPU

Assuming proper installation, you can run directly on a GPU via:

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)

Generation uses float64 throughout (see JAX treats and traps). GPU double precision performance varies by device and event count. Memory use can also be limiting; chunk_size divides generation into smaller batches:

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

See the GPU documentation for details.

More examples can be found in the tests folder and in the documentation.

Physics validation

The included physics tests (tests/test_physics.py) run through GitHub Actions. They compare:

  • Simple $n$-body decays with TGenPhaseSpace.
  • Sequential decays with RapidSim, a "fast Monte Carlo generator for simulation of heavy-quark hadron decays". Resonance comparisons can differ because these tests do not include the full mass-shape model used by the reference generator. The comparison plots allow visual inspection.

The tests write their comparison plots to tests/plots.

Citing

The underlying algorithm comes from the upstream package; please cite the original work:

A. Puig Navarro and J. Eschle, phasespace: n-body phase space generation in Python, Journal of Open Source Software 4(42), 1570 (2019), doi:10.21105/joss.01570.

The underlying algorithm is described in F. James, Monte Carlo Phase Space, CERN-68-15 (1968). To reference this fork specifically, see CITATION.cff.

License and attribution

phasespace-jax is a derivative work of zfit/phasespace, copyright (c) 2019 zfit, and is distributed under the same BSD-3-Clause license. The original copyright notice is retained in full. See AUTHORS.md for the original authors.

This fork is not affiliated with or endorsed by the zfit project.

Metadata

Release files for phasespace-jax 2.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for phasespace-jax 2.0.1
File Size Uploaded Provenance Actions
phasespace_jax-2.0.1.tar.gz 232.7 kB With provenance Details for phasespace_jax-2.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for phasespace-jax 2.0.1
File Interpreter ABI Platform Actions
phasespace_jax-2.0.1-py3-none-any.whl Python 3 none any Details for phasespace_jax-2.0.1-py3-none-any.whl

Total release size: 260.9 kB

Release files / phasespace_jax-2.0.1.tar.gz

Download URL phasespace_jax-2.0.1.tar.gz
Size 232.7 kB
Tags Source
SHA-256 checksum
How to use checksums
fa128bf294f7fce145cc748379083cc2f03e667278326faf9e266ca3371ec4bb
BLAKE2b-256 checksum
How to use checksums
3a5e43b34b68dc1a22afee3483262ac6238f523fe644ba21e102e12d7dfe6e46
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release files / phasespace_jax-2.0.1-py3-none-any.whl

Download URL phasespace_jax-2.0.1-py3-none-any.whl
Size 28.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c532fa6734401ec4076e1604123bfe09abc2a303cf5c94962260e7f398933c92
BLAKE2b-256 checksum
How to use checksums
4dcc1658d8dae77ecb5ca3e6f9868d1a46c0330f8c198a2101137ab5c3288c54
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Security for phasespace-jax 2.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for phasespace_jax-2.0.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.0.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page