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: 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
- 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 n-body 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 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
- 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 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
- Raise:
- 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.