# 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
1. 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? 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. 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? 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. 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. Mass of the particles, either a scalar or shape (nevents,) 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. 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.generate_decay(*args, **kwargs)[source]

Deprecated.

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. Particle decay. 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). ~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. ~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.metric_tensor()[source]

Metric tensor for Lorentz space (constant).

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.
phasespace.kinematics.y_component(vector)[source]

Extract spatial Y component of the input Lorentz or 3-vector.

Parameters: vector – Input vector.
phasespace.kinematics.z_component`(vector)[source]

Extract spatial Z component of the input Lorentz or 3-vector.

Parameters: vector – Input vector.