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.
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: 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 GenParticle.generate_unnormalized.

generate_tensor
(n_events: Union[int, tensorflow.python.framework.ops.Tensor, tensorflow.python.ops.variables.VariableV1], 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 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.VariableV1] = 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 (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.
Returns: Mass of the particles, either a scalar or shape (nevents,)
Return type: 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 (GenParticle) – Two or more 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.

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: list = None)[source]¶ Shortcut to build an nbody 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 4vectors.
 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
 Raise:
 ValueError: If the length of masses and names doesn’t match.

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: ~`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 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.