Changelog#
Entries through version 1.10.0 document the history of the upstream zfit/phasespace project.
Develop#
Major Features and Improvements#
- Fixed Lorentz boosts for batches containing both stationary and moving parents. Internal boosts
use momentum and invariant mass directly, preserving conservation accuracy for light or
massless daughters. Corrected
kinematics.betato return speed divided by the speed of light. - Rotation coefficients are computed once per stage, avoiding repeated transcendental evaluations in compiled CPU kernels. Paired CPU and GPU benchmarks show faster generation for large batches. Precision and random key splitting are unchanged.
- Relativistic Breit-Wigner sampling uses bounded rejection sampling when the requested interval falls outside the CDF table or the table cannot resolve it. Sampling within the table remains unchanged.
- Physics validation now checks four-momentum conservation, mass shells, massless energies, angular distributions and resonance tails. Reference comparisons preserve histogram bin positions and account for weighted statistical uncertainties.
- Generation runs on a GPU without code changes when a CUDA-enabled
jaxlibis installed (pip install "jax[cuda12]"for Maxwell to Volta,"jax[cuda13]"from Turing on). Speedup depends on event count and device. CPU and GPU results agree within a few units in the last place (ULPs), although arithmetic is not bit-identical. The PRNG is backend independent. generateacceptschunk_sizeto generate events in batches and limit peak memory use. Each chunk receives a separate split ofkey, so a chunked run draws a different but equally reproducible sample.- Replaced
jnp.sortwith an explicit compare-exchange network for the short axis ofn_particles - 2entries. XLA previously used a general sort for this axis. Generated events remain bit-identical. - Ported the computational backend from TensorFlow to JAX. Compilation with
jax.jitmakesgenerateroughly four to five times faster on CPU for one millionB -> 3pievents. - The
phasespace.fromdecaymass functions (gauss,bw,relbw) now sample directly with JAX using inverse transform sampling. This removes the zfit and zfit-physics dependencies.
Behavioral changes#
- Decays at the exact threshold raise
ValueErrorbecause their normalized weights are undefined. Numerical boost corrections can change the last bits of generated momenta. Generation remains reproducible for a fixed key; phase-space key splitting and weight formulas are unchanged. generateacceptskeyin place ofseed. The value can be an integer, a JAX PRNG key orNone. JAX random generation is functional: reusing a key produces identical events, whereastf.random.Generatoradvances its state between calls.n_eventsmust be a Python integer and is a static argument of the compiled function. A new value triggers compilation.tf.Variableis no longer accepted.- Resonance mass functions receive
mass(min_mass, max_mass, n_events, key)and must be compatible withjax.jit. Signature inspection that conditionally passedseedhas been removed. - Kinematically forbidden decays raise
ValueErrorinstead oftf.errors.InvalidArgumentError. generateenables JAX double precision for the duration of the call and returnsfloat64arrays, regardless of the caller's setting. Single precision is numerically unstable for this computation. Importingphasespaceleaves global JAX settings unchanged. With x64 mode disabled, later JAX operations can downcast the arrays tofloat32and issue a warning; conversion to NumPy preserves their precision. The helpers inphasespace.kinematicsfollow the caller's precision to remain compatible withjax.jit.GenMultiDecay.generateaccepts akeyargument. Previously, decay mode selection used the global TensorFlow seed and ignored the supplied seed.- Removed the
generate_tensor,Particleandgenerate_decaystubs, which only raised. phasespace.numpyis nowjax.numpyinstead oftensorflow.experimental.numpy.
Bug fixes and small changes#
- Resonance masses are now drawn from the key passed to
generate. Previously, they were drawn from the global TensorFlow generator, so seeded decays with resonances were not reproducible. PHASESPACE_EAGER=0now leaves eager mode disabled. Previously, it was interpreted as a non-empty string and enabled eager mode.- The
fromdecayimport error no longer passes an invalidfilekeyword toModuleNotFoundError. That keyword previously caused aTypeErrorand obscured the intended message.
Requirement changes#
- Requires
jax >= 0.11.0.tensorflowandtensorflow_probabilityare no longer required, and thetf/tensorflowextras were removed. - Requires Python >= 3.12, the minimum supported by JAX 0.11. Support for 3.10 and 3.11 is dropped.
- The
fromdecayextra no longer requireszfitandzfit-physics.
1.10.0 (16 Apr 2024)#
Add support for Python 3.12, drop support for 3.8
Major Features and Improvements#
- integrating vector support for
generate:boost_tocan be a Momentum Lorentz vector and return the boosted particles as a vector usingas_vectors=True.
Requirement changes#
Upgrade to TensorFlow > 0.16
1.9.0 (20 Jul 2023)#
Add support for Python 3.11, drop support for 3.7
1.8.0 (27 Jan 2023)#
Requirement changes#
- upgrade to zfit >= 0.10.0 and zfit-physics >= 0.3.0
- pinning uproot and awkward to ~4 and ~1, respectively
1.7.0 (1. Sep 2022)#
Upgraded Python and TensorFlow version.
Added tf and tensorflow extra to requirements. If you intend to use
phasespace with TensorFlow in the future (and not another backend like numpy or JAX),
make sure to always install with phasespace[tf].
Requirement changes#
- upgrade to TensorFlow >= 2.7
- Python from 3.7 to 3.10 is now supported
1.6.0 (14 Apr 2022)#
Major Features and Improvements#
- Improved GenMultiDecay to have better control on the decay mass of non-stable particles.
- Added a
particle_model_mapargument to theGenMultiDecayclass. This is a dict where the key is a particle name and the value is a mass function name. The feature can be seen in the GenMultiDecay Tutorial.
1.5.0 (27 Nov 2021)#
Major Features and Improvements#
- add support to generate from a DecayChain using
the decaylanguage package from Scikit-HEP.
This is in the new subpackage "fromdecay" and can be used by installing the extra with
pip install phasespace[fromdecay].
Requirement changes#
- drop Python 3.6 support
Thanks#
- to Simon Thor for contributing the
fromdecaysubpackage.
1.4.2 (5.11.2021)#
Requirement changes#
- Losen restriction on TensorFlow, allow version 2.7 (and 2.5, 2.6)
1.4.1 (27.08.2021)#
Requirement changes#
- Losen restriction on TensorFlow, allow version 2.6 (and 2.5)
1.4.0 (11.06.2021)#
Requirement changes#
- require TensorFlow 2.5 as 2.4 breaks some functionality
1.3.0 (28.05.2021)#
Major Features and Improvements#
- Support Python 3.9
- Support TensorFlow 2.5
- improved compilation in tf.functions, use of XLA where applicable
- developer: modernization of setup, CI and more
Thanks#
- Remco de Boer for many commits and cleanups
1.2.0 (17.12.20)#
Major Features and Improvements#
- Python 3.8 support
- Allow eager execution by setting with
tf.config.run_functions_eagerly(True)or the environment variable "PHASESPACE_EAGER" - Deterministic random number generation via seed
or
tf.random.Generatorinstance
Behavioral changes#
Bug fixes and small changes#
Requirement changes#
- tighten TensorFlow to 2.3/2.4
- tighten TensorFlow Probability to 0.11/0.12
Thanks#
- Remco de Boer and Stefan Pflüger for discussions on random number genration
1.1.0 (27.1.2020)#
This release switched to TensorFlow 2.0 eager mode. Please upgrade your TensorFlow installation if possible and change your code (minimal changes) as described under "Behavioral changes". In case this is currently impossible to do, please downgrade to < 1.1.0.
Major Features and Improvements#
- full TF2 compatibility
Behavioral changes#
generatenow returns an eager Tensor. This is basically a numpy array wrapped by TensorFlow. To explicitly convert it to a numpy array, use thenumpy()method of the eager Tensor.generate_tensoris now depreceated,generatecan directly be used instead.
Bug fixes and small changes#
Requirement changes#
- requires now TensorFlow >= 2.0.0
1.0.4 (13-10-2019)#
Major Features and Improvements#
Release to conda-forge, thanks to Chris Burr