phasespace package¶
phasespace.phasespace module¶
Implementation of the Raubold and Lynch method to generate nbody events.
 The code is based on the GENBOD function (W515 from CERNLIB), documented in
 James, Monte Carlo Phase Space, CERN 6815 (1968)

class
phasespace.phasespace.
Particle
(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 Particle must have a name, which is ensured not to clash with any others in the decay chain. It may also have:
 Mass, which can be either a number or a function to generate it according to
 a certain distribution. In this case, the particle is not considered as having a fixed mass and the has_fixed_mass method will return False.
 Children, ie, decay products, which are also Particle 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: int, boost_to=None, normalize_weights: bool = True)[source]¶ Generate normalized nbody 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 perevent 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
 Raise:
 tf.errors.InvalidArgumentError: If the the decay is kinematically forbidden. ValueError: If n_events and the size of boost_to don’t match. See Particle.generate_unnormalized.

generate_tensor
(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) → Tuple[tensorflow.python.framework.ops.Tensor, Dict[str, tensorflow.python.framework.ops.Tensor]][source]¶ Generate normalized nbody phase space as tensorflow tensors.
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 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 perevent 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
 Raise:
 tf.errors.InvalidArgumentError: If the the decay is kinematically forbidden. ValueError: If n_events and the size of boost_to don’t match. See Particle.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) → 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 and n_events parameters.
Parameters:  min_mass (tf.Tensor) – Lower mass range. Defaults to None, which is only valid in the case of fixed mass.
 max_mass (tf.Tensor) – Upper mass range. Defaults to None, which is only valid in the case of fixed mass.
 n_events (tf.Tensor) – Number of events to produce. Has to be specified if the particle is resonant.
Returns: Mass.
Return type: tf.Tensor
 Raise:
 ValueError: If the mass is requested and has not been set.

has_children
¶ Does the particle have children?
Type: bool

has_fixed_mass
¶ Is the mass a callable function?
Type: bool

has_grandchildren
¶ Does the particle have grandchildren?
Type: bool

set_children
(*children)[source]¶ Assign children.
Parameters: children (list[Particle]) – Children to assign to the current particle. Returns: self  Raise:
 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.

phasespace.phasespace.
generate_decay
(mass_top: float, masses: list, n_events: Union[int, tensorflow.python.ops.variables.Variable], boost_to=None, as_numpy: bool = True)[source]¶ Generate an nbody phasespace.
Internally, this function uses Particle with a single generation of children.
Note
This function doesn’t cache so it may be slower on repeated calls. In that case it’s better to use
Particle
directly.Parameters:  mass_top (tf.Tensor, list) – Mass of the top particle. Can be a list of 4vectors.
 masses (list) – Masses of the child particles.
 n_events (int) – Number of samples to generate.
 boost_to (tf.Tensor or array, optional) – Momenta to boost the generated events to. If not specified, events are generated in the rest frame of the top particle.
 as_numpy (bool, optional) – Return numpy arrays instead of tensorflow tensors? Defaults to True.
Returns: 4momenta of the generated particles, with shape (4xn_particles, n_events). ValueError: If nor n_events nor boost_to are given.
Return type: Tensor

phasespace.phasespace.
pdk
(a, b, c)[source]¶ Calculate the PDK (2body phase space) function.
Based on Eq. (9.17) in CERN 6815 (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: 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: Tensor.
phasespace.kinematics module¶
Basic kinematics.

phasespace.kinematics.
beta
(vector)[source]¶ Calculate beta of a given 4vector.
Parameters: vector – Input Lorentz momentum vector.

phasespace.kinematics.
boost_components
(vector)[source]¶ Get the boost components of a given 4vector.
Parameters: vector – Input Lorentz momentum vector.

phasespace.kinematics.
lorentz_boost
(vector, boostvector)[source]¶ Perform Lorentz boost.
Parameters:  vector – 4vector to be boosted
 boostvector – Boost vector. Can be either 3vector or 4vector, since only spatial components are used.

phasespace.kinematics.
lorentz_vector
(space, time)[source]¶ Make a Lorentz vector from spatial and time components.
Parameters:  space – 3vector of spatial components.
 time – Time component.

phasespace.kinematics.
mass
(vector)[source]¶ Calculate mass scalar for Lorentz 4momentum.
Parameters: vector – Input Lorentz momentum vector.

phasespace.kinematics.
scalar_product
(vec1, vec2)[source]¶ Calculate scalar product of two 3vectors.
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 02 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 02 are space, index 3 is time).

phasespace.kinematics.
x_component
(vector)[source]¶ Extract spatial X component of the input Lorentz or 3vector.
Parameters: vector – Input vector.