phasespace package¶
phasespace.phasespace module¶
Implementation of the Raubold and Lynch method to generate n-body events.
The code is based on the GENBOD function (W515 from CERNLIB), documented in:
James, Monte Carlo Phase Space, CERN 68-15 (1968)
- class phasespace.phasespace.GenParticle(name: str, mass: Union[Callable, int, float])[source]¶
Bases:
object
Representation of a particle.
Instances of this class can be combined with each other to build decay chains, which can then be used to generate phase space events through the generate or generate_tensor method.
- A GenParticle must have
- a name, which is ensured not to clash with any others in
the decay chain.
- a mass, which can be either a number or a function to generate it according to
a certain distribution. The returned ~`tf.Tensor` needs to have shape (nevents,). In this case, the particle is not considered as having a fixed mass and the has_fixed_mass method will return False.
It may also have:
Children, ie, decay products, which are also GenParticle instances.
- Parameters
name (str) – Name of the particle.
mass (float, Tensor`, callable) – Mass of the particle. If it’s a float, it get converted to a tf.constant.
- generate(n_events: Union[int, tensorflow.python.framework.ops.Tensor, tensorflow.python.ops.variables.Variable], boost_to: Optional[tensorflow.python.framework.ops.Tensor] = None, normalize_weights: bool = True, seed: Optional[Union[int, tensorflow.python.ops.stateful_random_ops.Generator]] = None) → Tuple[tensorflow.python.framework.ops.Tensor, Dict[str, tensorflow.python.framework.ops.Tensor]][source]¶
Generate normalized n-body phase space as tensorflow tensors.
Any TensorFlow tensor can always be converted to a numpy array with the method numpy().
Events are generated in the rest frame of the particle, unless boost_to is given.
Note
In this method, the event weights are returned normalized to their maximum.
- Parameters
n_events (int) – Number of events to generate.
boost_to (optional) – Momentum vector of shape (x, 4), where x is optional, to where the resulting events will be boosted. If not specified, events are generated in the rest frame of the particle.
normalize_weights (bool, optional) – Normalize the event weight to its max?
seed (SeedLike) – The seed can be a number or a tf.random.Generator that are used as a seed to create a random number generator inside the function or directly as the random number generator instance, respectively.
- Returns
Result of the generation, which varies with the value of normalize_weights:
If True, the tuple elements are the normalized event weights as a tensor of shape (n_events, ), and the momenta generated particles as a dictionary of tensors of shape (4, n_events) with particle names as keys.
If False, the tuple weights are the unnormalized event weights as a tensor of shape (n_events, ), the maximum per-event weights as a tensor of shape (n_events, ) and the momenta generated particles as a dictionary of tensors of shape (4, n_events) with particle names as keys.
- Return type
tuple
- Raises
tf.errors.InvalidArgumentError – If the the decay is kinematically forbidden.
ValueError – If n_events and the size of boost_to don’t match.
See GenParticle.generate_unnormalized. –
- generate_tensor(n_events: int, boost_to=None, normalize_weights: bool = True)[source]¶
Generate normalized n-body phase space as numpy arrays.
Events are generated in the rest frame of the particle, unless boost_to is given.
Note
In this method, the event weights are returned normalized to their maximum.
- Parameters
n_events (int) – Number of events to generate.
boost_to (optional) – Momentum vector of shape (x, 4), where x is optional, to where the resulting events will be boosted. If not specified, events are generated in the rest frame of the particle.
normalize_weights (bool, optional) – Normalize the event weight to its max
- Returns
Result of the generation, which varies with the value of normalize_weights:
If True, the tuple elements are the normalized event weights as an array of shape (n_events, ), and the momenta generated particles as a dictionary of arrays of shape (4, n_events) with particle names as keys.
If False, the tuple weights are the unnormalized event weights as an array of shape (n_events, ), the maximum per-event weights as an array of shape (n_events, ) and the momenta generated particles as a dictionary of arrays of shape (4, n_events) with particle names as keys.
- Return type
tuple
- Raises
tf.errors.InvalidArgumentError – If the the decay is kinematically forbidden.
ValueError – If n_events and the size of boost_to don’t match.
See GenParticle.generate_unnormalized. –
- get_mass(min_mass: tensorflow.python.framework.ops.Tensor = None, max_mass: tensorflow.python.framework.ops.Tensor = None, n_events: Union[tensorflow.python.framework.ops.Tensor, tensorflow.python.ops.variables.Variable] = None, seed: Optional[Union[int, tensorflow.python.ops.stateful_random_ops.Generator]] = None) → tensorflow.python.framework.ops.Tensor[source]¶
Get the particle mass.
If the particle is resonant, the mass function will be called with the min_mass, max_mass, n_events and optionally a seed parameter.
- Parameters
min_mass (tensor) – Lower mass range. Defaults to None, which is only valid in the case of fixed mass.
max_mass (tensor) – Upper mass range. Defaults to None, which is only valid in the case of fixed mass.
() (n_events) – Number of events to produce. Has to be specified if the particle is resonant.
seed (SeedLike) – The seed can be a number or a tf.random.Generator that are used as a seed to create a random number generator inside the function or directly as the random number generator instance, respectively.
- Returns
Mass of the particles, either a scalar or shape (nevents,)
- Return type
Tensor`
- Raises
ValueError – If the mass is requested and has not been set.
- property has_children¶
Does the particle have children?
- Type
bool
- property has_fixed_mass¶
Is the mass a callable function?
- Type
bool
- property has_grandchildren¶
Does the particle have grandchildren?
- Type
bool
- set_children(*children)[source]¶
Assign children.
- Parameters
children (GenParticle) – Two or more children to assign to the current particle.
- Returns
self
- Raises
ValueError – If there is an inconsistency in the parent/children relationship, ie,
if children were already set, if their parent was or if less than two children were given. –
KeyError – If there is a particle name clash.
RuntimeError – If generate was already called before.
- class phasespace.phasespace.Particle[source]¶
Bases:
object
Deprecated Particle class.
Renamed to GenParticle.
- phasespace.phasespace.nbody_decay(mass_top: float, masses: list, top_name: str = '', names: Optional[list] = None)[source]¶
Shortcut to build an n-body decay of a GenParticle.
If the particle names are not given, the top particle is called ‘top’ and the children ‘p_{i}’, where i corresponds to their position in the masses sequence.
- Parameters
mass_top (tensor, list) – Mass of the top particle. Can be a list of 4-vectors.
masses (list) – Masses of the child particles.
name_top (str, optional) – Name of the top particle. If not given, the top particle is named top.
names (list, optional) – Names of the child particles. If not given, they are build as ‘p_{i}’, where i is given by their ordering in the masses list.
- Returns
Particle decay.
- Return type
GenParticle
- Raises
ValueError – If the length of masses and names doesn’t match.
- phasespace.phasespace.pdk(a, b, c)[source]¶
Calculate the PDK (2-body phase space) function.
Based on Eq. (9.17) in CERN 68-15 (1968).
- Parameters
a (Tensor`) – \(M_{i+1}\) in Eq. (9.17).
b (Tensor`) – \(M_{i}\) in Eq. (9.17).
c (Tensor`) – \(m_{i+1}\) in Eq. (9.17).
- Returns
~`tf.Tensor`
- phasespace.phasespace.process_list_to_tensor(lst)[source]¶
Convert a list to a tensor.
The list is converted to a tensor and transposed to get the proper shape.
Note
If lst is a tensor, nothing is done to it other than convert it to tf.float64.
- Parameters
lst (list) – List to convert.
- Returns
~`tf.Tensor`
phasespace.kinematics module¶
Basic kinematics.
- phasespace.kinematics.beta(vector)[source]¶
Calculate beta of a given 4-vector.
- Parameters
vector – Input Lorentz momentum vector.
- phasespace.kinematics.boost_components(vector)[source]¶
Get the boost components of a given 4-vector.
- Parameters
vector – Input Lorentz momentum vector.
- phasespace.kinematics.lorentz_boost(vector, boostvector)[source]¶
Perform Lorentz boost.
- Parameters
vector – 4-vector to be boosted
boostvector – Boost vector. Can be either 3-vector or 4-vector, since only spatial components are used.
- phasespace.kinematics.lorentz_vector(space, time)[source]¶
Make a Lorentz vector from spatial and time components.
- Parameters
space – 3-vector of spatial components.
time – Time component.
- phasespace.kinematics.mass(vector)[source]¶
Calculate mass scalar for Lorentz 4-momentum.
- Parameters
vector – Input Lorentz momentum vector.
- phasespace.kinematics.scalar_product(vec1, vec2)[source]¶
Calculate scalar product of two 3-vectors.
- Parameters
vec1 – First vector.
vec2 – Second vector.
- phasespace.kinematics.spatial_component(vector)[source]¶
Extract spatial components of the input Lorentz vector.
- Parameters
vector – Input Lorentz vector (where indexes 0-2 are space, index 3 is time).
- phasespace.kinematics.time_component(vector)[source]¶
Extract time component of the input Lorentz vector.
- Parameters
vector – Input Lorentz vector (where indexes 0-2 are space, index 3 is time).
- phasespace.kinematics.x_component(vector)[source]¶
Extract spatial X component of the input Lorentz or 3-vector.
- Parameters
vector – Input vector.