phasespace-jax
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.