Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions benchmarks/ampform.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@
import tensorwaves as tw
from tensorwaves.data import (
IntensityDistributionGenerator,
PhaseSpaceGenerator,
SympyDataTransformer,
TFPhaseSpaceGenerator,
TFUniformRealNumberGenerator,
TFWeightedPhaseSpaceGenerator,
WeightedPhaseSpaceGenerator,
)
from tensorwaves.function.sympy import create_parametrized_function

Expand Down Expand Up @@ -85,13 +85,15 @@ def generate_data(

initial_state_mass = reaction.initial_state[-1].mass
final_state_masses = {i: p.mass for i, p in final_state.items()}
phsp_generator = TFPhaseSpaceGenerator(initial_state_mass, final_state_masses)
phsp_generator = PhaseSpaceGenerator(
initial_state_mass, final_state_masses, backend="tensorflow"
)
phsp = phsp_generator.generate(
phsp_sample_size, rng=TFUniformRealNumberGenerator(seed=0)
)

weighted_phsp_generator = TFWeightedPhaseSpaceGenerator(
initial_state_mass, final_state_masses
weighted_phsp_generator = WeightedPhaseSpaceGenerator(
initial_state_mass, final_state_masses, backend="tensorflow"
)
data_generator = IntensityDistributionGenerator(
weighted_phsp_generator, function, domain_transformer=converter
Expand Down
23 changes: 10 additions & 13 deletions docs/amplitude-analysis.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -333,9 +333,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"The {class}`~qrules.transition.ReactionInfo` class defines the constraints of the phase space. As such, we have enough information to generate a **phase-space sample** for this particle reaction. We do this with a {class}`.TFPhaseSpaceGenerator` class, which is a {class}`.DataGenerator` for a {obj}`.DataSample` of **four-momenta** arrays (using {obj}`tensorflow <tf.Tensor>` and the [`phasespace`](https://phasespace.readthedocs.io) package as a back-end). We also need to construct a {class}`.RealNumberGenerator` that can generate random numbers. {class}`.TFUniformRealNumberGenerator` is the natural choice here.\n",
"The {class}`~qrules.transition.ReactionInfo` class defines the constraints of the phase space. As such, we have enough information to generate a **phase-space sample** for this particle reaction. We do this with a {class}`.PhaseSpaceGenerator` class, which is a {class}`.DataGenerator` for a {obj}`.DataSample` of **four-momenta** arrays (using {obj}`tensorflow <tf.Tensor>` and the [`phasespace`](https://phasespace.readthedocs.io) package as a back-end). We also need to construct a {class}`.RealNumberGenerator` that can generate random numbers. {class}`.TFUniformRealNumberGenerator` is the natural choice here.\n",
"\n",
"As opposed to the main [](compwa-step-2) of the main usage example page, we will generate a **deterministic** data sample. This can be done by feeding a {class}`.RealNumberGenerator` with a specific {attr}`~.RealNumberGenerator.seed` and giving that generator to the {meth}`.TFPhaseSpaceGenerator.generate` method:"
"As opposed to the main [](compwa-step-2) of the main usage example page, we will generate a **deterministic** data sample. This can be done by feeding a {class}`.RealNumberGenerator` with a specific {attr}`~.RealNumberGenerator.seed` and giving that generator to the {meth}`.PhaseSpaceGenerator.generate` method:"
]
},
{
Expand Down Expand Up @@ -366,10 +366,10 @@
},
"outputs": [],
"source": [
"from tensorwaves.data import TFPhaseSpaceGenerator, TFUniformRealNumberGenerator\n",
"from tensorwaves.data import NumpyUniformRNG, PhaseSpaceGenerator\n",
"\n",
"rng = TFUniformRealNumberGenerator(seed=0)\n",
"phsp_generator = TFPhaseSpaceGenerator(\n",
"rng = NumpyUniformRNG(seed=0)\n",
"phsp_generator = PhaseSpaceGenerator(\n",
" initial_state_mass=reaction.initial_state[-1].mass,\n",
" final_state_masses={i: p.mass for i, p in reaction.final_state.items()},\n",
")\n",
Expand Down Expand Up @@ -407,7 +407,7 @@
},
"source": [
":::{tip}\n",
"For decays into many final state particles, `adaptive_max_weight=True` makes {class}`.TFPhaseSpaceGenerator` much faster. See {doc}`/amplitude-analysis/phase-space`.\n",
"For decays into many final state particles, `adaptive_max_weight=True` makes {class}`.PhaseSpaceGenerator` much faster. See {doc}`/amplitude-analysis/phase-space`.\n",
":::\n",
"\n",
"The resulting phase space sample is a {obj}`dict` of final state IDs to an {obj}`~numpy.array` of four-momenta. In the last step, we converted this sample in such a way that it is rendered as an understandable {class}`pandas.DataFrame`.\n",
Expand Down Expand Up @@ -456,7 +456,7 @@
"source": [
"'Data samples' are more complicated than phase space samples in that they represent the intensity profile resulting from a reaction. You therefore need a {class}`.Function` object that expresses an intensity distribution as well as a phase space over which to generate that distribution. We call such a data sample an **intensity-based sample**.\n",
"\n",
"An intensity-based sample is generated over a phase space sample using the {class}`.IntensityDistributionGenerator`. Its usage is similar to {class}`.TFPhaseSpaceGenerator`, but now you have to provide a {obj}`.Function` as well as a {obj}`.DataTransformer` that is used to transform the four-momentum phase space sample to a data sample that can be understood by the {obj}`.Function`.\n",
"An intensity-based sample is generated over a phase space sample using the {class}`.IntensityDistributionGenerator`. Its usage is similar to {class}`.PhaseSpaceGenerator`, but now you have to provide a {obj}`.Function` as well as a {obj}`.DataTransformer` that is used to transform the four-momentum phase space sample to a data sample that can be understood by the {obj}`.Function`.\n",
"\n",
"Now, recall that in [](compwa-step-1), we used the helicity formalism to mathematically express the reaction in terms of an amplitude model. TensorWaves needs to convert this {obj}`~ampform.helicity.HelicityModel` to a {obj}`.Function` object that can perform fast computations. This can be done with {func}`.create_parametrized_function`:"
]
Expand Down Expand Up @@ -545,12 +545,9 @@
},
"outputs": [],
"source": [
"from tensorwaves.data import (\n",
" IntensityDistributionGenerator,\n",
" TFWeightedPhaseSpaceGenerator,\n",
")\n",
"from tensorwaves.data import IntensityDistributionGenerator, WeightedPhaseSpaceGenerator\n",
"\n",
"weighted_phsp_generator = TFWeightedPhaseSpaceGenerator(\n",
"weighted_phsp_generator = WeightedPhaseSpaceGenerator(\n",
" initial_state_mass=reaction.initial_state[-1].mass,\n",
" final_state_masses={i: p.mass for i, p in reaction.final_state.items()},\n",
")\n",
Expand All @@ -574,7 +571,7 @@
"As before, we use a {class}`.RealNumberGenerator` with a specific {attr}`~.RealNumberGenerator.seed` to ensure we get a **deterministic** data sample.\n",
"\n",
"> [!NOTE]\n",
"> Instead of constructing a {class}`.TFWeightedPhaseSpaceGenerator`, it's also possible to just reuse the **unweighted** {class}`.TFPhaseSpaceGenerator` that we constructed previously. This is, however, a bit slower, because the {class}`.TFPhaseSpaceGenerator` also uses a hit-and-miss strategy."
"> Instead of constructing a {class}`.WeightedPhaseSpaceGenerator`, it's also possible to just reuse the **unweighted** {class}`.PhaseSpaceGenerator` that we constructed previously. This is, however, a bit slower, because the {class}`.PhaseSpaceGenerator` also uses a hit-and-miss strategy."
]
},
{
Expand Down
12 changes: 4 additions & 8 deletions docs/amplitude-analysis/analytic-continuation.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,7 @@
"import qrules\n",
"from IPython.display import Markdown, Math\n",
"\n",
"from tensorwaves.data import (\n",
" SympyDataTransformer,\n",
" TFPhaseSpaceGenerator,\n",
" TFUniformRealNumberGenerator,\n",
")\n",
"from tensorwaves.data import NumpyUniformRNG, PhaseSpaceGenerator, SympyDataTransformer\n",
"from tensorwaves.function.sympy import create_parametrized_function\n",
"\n",
"logging.getLogger(\"tensorwaves.data\").setLevel(logging.ERROR) # hide progress bars\n",
Expand Down Expand Up @@ -167,8 +163,8 @@
"helicity_transformer = SympyDataTransformer.from_sympy(\n",
" model.kinematic_variables, backend=\"numpy\"\n",
")\n",
"rng = TFUniformRealNumberGenerator(seed=0)\n",
"phsp_generator = TFPhaseSpaceGenerator(\n",
"rng = NumpyUniformRNG(seed=0)\n",
"phsp_generator = PhaseSpaceGenerator(\n",
" initial_state_mass=reaction.initial_state[-1].mass,\n",
" final_state_masses={i: p.mass for i, p in reaction.final_state.items()},\n",
")\n",
Expand Down Expand Up @@ -232,7 +228,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.13.16"
"version": "3.13.18"
}
},
"nbformat": 4,
Expand Down
35 changes: 17 additions & 18 deletions docs/amplitude-analysis/phase-space.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Amplitude analysis needs samples of four-momenta that are distributed uniformly over the phase space of a decay. {class}`.TFPhaseSpaceGenerator` produces such samples with [`phasespace`](https://phasespace.readthedocs.io), which can run on TensorFlow, NumPy, or JAX. `phasespace` generates *weighted* events, so {class}`.TFPhaseSpaceGenerator` turns them into unweighted events with a hit-and-miss step: an event is kept if a uniform random number is below its weight. {class}`.TFWeightedPhaseSpaceGenerator` 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."
"Amplitude analysis needs samples of four-momenta that are distributed uniformly over the phase space of a decay. {class}`.PhaseSpaceGenerator` produces such samples with [`phasespace`](https://phasespace.readthedocs.io), which can run on NumPy, TensorFlow, or JAX. `phasespace` generates *weighted* events, so {class}`.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. {class}`.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."
]
},
{
Expand Down Expand Up @@ -62,25 +62,25 @@
"source": [
"from tensorwaves.data import (\n",
" NumpyUniformRNG,\n",
" TFPhaseSpaceGenerator,\n",
" PhaseSpaceGenerator,\n",
" TFUniformRealNumberGenerator,\n",
")\n",
"\n",
"initial_state_mass = 3.0969\n",
"final_state_masses = {0: 0.1350, 1: 0.1396, 2: 0.4937}\n",
"generators = {\n",
" \"numpy\": (\n",
" TFPhaseSpaceGenerator(initial_state_mass, final_state_masses, backend=\"numpy\"),\n",
" PhaseSpaceGenerator(initial_state_mass, final_state_masses, backend=\"numpy\"),\n",
" NumpyUniformRNG(seed=0),\n",
" ),\n",
" \"tensorflow\": (\n",
" TFPhaseSpaceGenerator(\n",
" PhaseSpaceGenerator(\n",
" initial_state_mass, final_state_masses, backend=\"tensorflow\"\n",
" ),\n",
" TFUniformRealNumberGenerator(seed=0),\n",
" ),\n",
" \"jax\": (\n",
" TFPhaseSpaceGenerator(initial_state_mass, final_state_masses, backend=\"jax\"),\n",
" PhaseSpaceGenerator(initial_state_mass, final_state_masses, backend=\"jax\"),\n",
" NumpyUniformRNG(seed=0),\n",
" ),\n",
"}\n",
Expand All @@ -94,18 +94,18 @@
"source": [
"| `backend` | Extra | Use of the {class}`.RealNumberGenerator` |\n",
"| --- | --- | --- |\n",
"| `\"tensorflow\"` (default) | `phsp` | {class}`.TFUniformRealNumberGenerator` is used directly, any other type only provides a seed |\n",
"| `\"numpy\"` | `phsp` | {class}`.NumpyUniformRNG` is used directly, any other type only provides a seed |\n",
"| `\"numpy\"` (default) | `phsp` | {class}`.NumpyUniformRNG` is used directly, any other type only provides a seed |\n",
"| `\"tensorflow\"` | `phsp,tf` | {class}`.TFUniformRealNumberGenerator` is used directly, any other type only provides a seed |\n",
"| `\"jax\"` | `phsp,jax` | any type only provides a seed |\n",
"\n",
"The NumPy and JAX backends require `phasespace` 2.0 or higher. The installation of these extras is described on {doc}`/install`."
"The installation of these extras is described on {doc}`/install`."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Every backend is used through the same {meth}`~.TFPhaseSpaceGenerator.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."
"Every backend is used through the same {meth}`~.PhaseSpaceGenerator.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."
]
},
{
Expand Down Expand Up @@ -145,7 +145,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"TensorFlow is the default, because it reproduces the samples of earlier TensorWaves versions, when combined with a {class}`.TFUniformRealNumberGenerator`. NumPy needs no compilation, so it is the fastest choice for a few small samples. 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. JAX can be useful if the rest of the analysis already uses it. {doc}`TR-039 <compwa-report:039/index>` benchmarks the backends and compares their distributions for three-body and four-body decays.\n",
"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 {class}`.TFUniformRealNumberGenerator`. JAX can be useful if the rest of the analysis already uses it. {doc}`TR-039 <compwa-report:039/index>` benchmarks the backends and compares their distributions for three-body and four-body decays.\n",
"\n",
"There are two things to keep in mind:\n",
"\n",
Expand Down Expand Up @@ -187,15 +187,14 @@
},
"outputs": [],
"source": [
"from tensorwaves.data import TFWeightedPhaseSpaceGenerator\n",
"from tensorwaves.data import WeightedPhaseSpaceGenerator\n",
"\n",
"n_particles = list(range(3, 9))\n",
"weights = {}\n",
"for n in n_particles:\n",
" weighted_generator = TFWeightedPhaseSpaceGenerator(\n",
" weighted_generator = WeightedPhaseSpaceGenerator(\n",
" initial_state_mass=5.0,\n",
" final_state_masses=dict.fromkeys(range(n), 0.13957),\n",
" backend=\"numpy\",\n",
" )\n",
" rng = NumpyUniformRNG(seed=0)\n",
" weights[n] = weighted_generator.generate(100_000, rng)[\"weights\"]\n",
Expand Down Expand Up @@ -233,7 +232,7 @@
"source": [
"### Usage\n",
"\n",
"The option is a keyword argument of {class}`.TFPhaseSpaceGenerator`. 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."
"The option is a keyword argument of {class}`.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."
]
},
{
Expand All @@ -244,8 +243,8 @@
"source": [
"initial_state_mass = 3.0969\n",
"final_state_masses = {0: 0.1350, 1: 0.1396, 2: 0.4937}\n",
"default_generator = TFPhaseSpaceGenerator(initial_state_mass, final_state_masses)\n",
"adaptive_generator = TFPhaseSpaceGenerator(\n",
"default_generator = PhaseSpaceGenerator(initial_state_mass, final_state_masses)\n",
"adaptive_generator = PhaseSpaceGenerator(\n",
" initial_state_mass, final_state_masses, adaptive_max_weight=True\n",
")"
]
Expand All @@ -260,9 +259,9 @@
"default_generator.show_progress = False\n",
"adaptive_generator.show_progress = False\n",
"samples = {\n",
" \"Default\": default_generator.generate(size, TFUniformRealNumberGenerator(seed=0)),\n",
" \"Default\": default_generator.generate(size, NumpyUniformRNG(seed=0)),\n",
" \"adaptive_max_weight=True\": adaptive_generator.generate(\n",
" size, TFUniformRealNumberGenerator(seed=0)\n",
" size, NumpyUniformRNG(seed=0)\n",
" ),\n",
"}"
]
Expand Down
4 changes: 4 additions & 0 deletions docs/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,10 @@ pip install tensorwaves[jax,scipy,tf]
pip install tensorwaves[all] # all runtime dependencies
```

The `phsp` and `pwa` extras generate phase space samples with NumPy and do not install TensorFlow. To generate them with TensorFlow or JAX, install the `tf` or `jax` extra as well and select it with the `backend` argument of {class}`.PhaseSpaceGenerator` or {class}`.WeightedPhaseSpaceGenerator`.

TensorFlow does not support Python 3.14 and higher yet ([tensorflow/tensorflow#102890](https://github.com/tensorflow/tensorflow/issues/102890)), so on those versions the `tf` extra installs nothing and the TensorFlow backend is unavailable. Use NumPy, JAX, or Numba instead.

## Backend precision

TensorWaves uses 64-bit precision for JAX and TensorFlow by default. Configure 32-bit precision before creating backend arrays or TensorWaves functions with:
Expand Down
2 changes: 1 addition & 1 deletion docs/usage/basics.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -513,7 +513,7 @@
"metadata": {},
"source": [
"> [!NOTE]\n",
"> In PWA, the sample on which we perform hit-and-miss is not uniform, because the available space is limited by the masses of the initial and final state (phase space). See {class}`.TFPhaseSpaceGenerator`, {doc}`/amplitude-analysis/phase-space`, and {ref}`amplitude-analysis:Step 2: Generate data`."
"> In PWA, the sample on which we perform hit-and-miss is not uniform, because the available space is limited by the masses of the initial and final state (phase space). See {class}`.PhaseSpaceGenerator`, {doc}`/amplitude-analysis/phase-space`, and {ref}`amplitude-analysis:Step 2: Generate data`."
]
},
{
Expand Down
Loading
Loading