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

6. James, Monte Carlo Phase Space, CERN 68-15 (1968)

class phasespace.phasespace.Particle(name: str, mass: Union[Callable, int, float])

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.

• a mass, which can be either a number or a function to generate it according to

  a certain distribution. The returned 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 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)

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]]

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

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 of the particles, either a scalar or shape (nevents,)

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)

Assign children.

Parameters:children (Particle) – 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.

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)

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)

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)

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)

Calculate beta of a given 4-vector.

Parameters:vector – Input Lorentz momentum vector.

phasespace.kinematics.boost_components(vector)

Get the boost components of a given 4-vector.

Parameters:vector – Input Lorentz momentum vector.

phasespace.kinematics.lorentz_boost(vector, boostvector)

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)

Make a Lorentz vector from spatial and time components.

Parameters:

• space – 3-vector of spatial components.
• time – Time component.

phasespace.kinematics.mass(vector)

Calculate mass scalar for Lorentz 4-momentum.

Parameters:vector – Input Lorentz momentum vector.

phasespace.kinematics.metric_tensor()

Metric tensor for Lorentz space (constant).

phasespace.kinematics.scalar_product(vec1, vec2)

Calculate scalar product of two 3-vectors.

Parameters:

• vec1 – First vector.
• vec2 – Second vector.

phasespace.kinematics.spatial_component(vector)

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)

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)

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

Parameters:vector – Input vector.

phasespace.kinematics.y_component(vector)

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

Parameters:vector – Input vector.

phasespace.kinematics.z_component(vector)

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

Parameters:vector – Input vector.