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.
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 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 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 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 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 n-body 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 4-vectors.
- 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: 4-momenta 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 (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: 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 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.