toytrack package

Submodules

toytrack.detector_geometry module

class toytrack.detector_geometry.Detector(dimension: int, hole_inefficiency: int | float = 0, layer_safety_guarantee: bool = False)

Bases: object

A class that represents a detector geometry.

Parameters:

• dimension (int) – The dimension of the space in which the detector is located. This can be 2 or 3.

• shape (str) – The shape of the detector. This can be ‘plane’, ‘cylinder’ or ‘sphere’.

• radius (float) – The radius of the detector. This is only used if shape is ‘cylinder’ or ‘sphere’.

• length (float) – The length of the detector. This is only used if shape is ‘cylinder’ or ‘plane’.

• layer_spacing (float) – The spacing between layers of the detector.

• number_of_layers (int) – The number of layers in the detector.

• hole_inefficiency (int, float) – If specified: If a float, then this is the inefficiency of each layer - i.e. the probability that a hit will not be recorded. If an int, then this is the number of holes that will be guaranteed per particle.

• layer_safety_guarantee (bool) – If True, then each particle is guaranteed to have exactly one hit per layer.

add_barrel(min_radius: float, max_radius: float, number_of_layers: int, length: float = None)

Add a barrel detector. Layers are spaced evenly between min_radius and max_radius.

add_endcap(min_radius: float, max_radius: float, min_z, max_z, layer_spacing: float, number_of_layers: int)

Add an endcap detector. This is a series of annuli, evenly spaced in z.

add_from_template(template: str = None, **kwargs)

Add a detector from a template.

generate_hits(particles: DataFrame) → DataFrame

Generate a DataFrame of hits based on the given particles.

generate_noise(hits_df: DataFrame, num_noise: int) → DataFrame

Generate a DataFrame of noise hits.

class toytrack.detector_geometry.Hit(x: float = None, y: float = None, z: float = None, r: float = None, phi: float = None, layer: int = None, module: int = None)

Bases: object

A class that represents a hit.

Parameters:

• x (float) – The x-coordinate of the hit.

• y (float) – The y-coordinate of the hit.

• z (float) – The z-coordinate of the hit.

• r (float) – The radial coordinate of the hit.

• phi (float) – The azimuthal angle of the hit.

• layer (int)

• module (int)

toytrack.event_generator module

class toytrack.event_generator.Event(particles: DataFrame, hits: DataFrame, tracks: ndarray, detector: Detector)

Bases: object

Class to store an event for the tracking micro challenges.

Parameters:

• particles (pd.DataFrame) – A DataFrame of particles

• hits (pd.DataFrame) – A DataFrame of hits

• tracks (np.ndarray) – A 2xN numpy array of the truth tracks.

• detector (Detector) – The detector used to generate the hits.

display(ax=None)

class toytrack.event_generator.EventGenerator(particle_gun: ParticleGun | List[ParticleGun], detector: Detector, noise: float | List[float] | List[float | str] | int | List[int] | List[str | int] = None)

Bases: object

Class to generate events for the tracking micro challenges.

Parameters:

• particle_gun (ParticleGun or List[ParticleGun]) – The particle gun(s) to use to generate particles.

• detector (Detector) – The detector to use to generate hits.

• noise (float, list) – The amount of noise to add to the hits. This can be specified in three ways: - A single float: This will add a fixed fraction of noise hits. - A pair of floats: This will add a random fraction of noise hits with a uniform distribution. - A list of three elements: This will add a random fraction of noise hits. The third entry of the list is the distribution type (uniform, normal or poisson), and the first two entries are the parameters of the distribution. If the values are given as non-zero integers, then the noise is added as a fixed number of hits. If the values are given as floats between 0 and 1, then the noise is added as a fraction of the number of non-noise hits.

generate_event()

Generate an event based on the initialized parameters.

toytrack.particle_gun module

class toytrack.particle_gun.ParticleGun(num_particles: float | List[float] | List[float | str], pt: float | List[float] | List[float | str], pphi: float | List[float] | List[float | str], vx: float | List[float] | List[float | str], vy: float | List[float] | List[float | str], vz: float | List[float] | List[float | str] | None = None, dimension: int = 2)

Bases: object

A class that generates particles with a given kinematic distribution.

Parameters:

• num_particles (float, list) – The number of particles to generate. This can be specified in three ways: - A single float: This will generate a fixed number of particles. - A pair of floats: This will generate a random number of particles with a uniform distribution. - A list of three floats: This will generate a random number of particles. The third entry of the list is the distribution type (uniform, normal or poisson), and the first two entries are the parameters of the distribution. For example, if the third entry is ‘uniform’, then the first two entries are the minimum and maximum of the uniform distribution. If the third entry is ‘normal’, then the first two entries are the mean and standard deviation of the normal distribution. If the third entry is ‘poisson’, then the first entry is lambda and the second is omitted.

• pt (float, list) – The transverse momentum of the particles to be generated. This can be specified in three ways: 1. A float: All particles will be generated with this transverse momentum. 2. A list [min, max]: Particles will be generated uniform-random with a transverse momentum in this range. 3. A list [float, float, dist_type]: Particles will be generated with a transverse momentum in the range specified by the first two elements. The third element, dist_type, specifies the distribution type and can be either ‘uniform’ or ‘normal’. If uniform, then particles will be generated uniform-random in the range. If normal, then the first entry is the mean, the second entry is the standard deviation, and particles will be generated with a normal distribution.

• pphi (float, list) – The local phi momentum of the particles to be generated. This can be specified in the same ways as pt.

• vx (float, list) – The creation vertex x-coordinate of the particles to be generated. This can be specified in the same ways as pt.

• vy (float, list) – The creation vertex y-coordinate of the particles to be generated. This can be specified in the same ways as pt.

• vz (float, list) – The creation vertex z-coordinate of the particles to be generated. This can be specified in the same ways as pt.

• dimension (int) – The dimension of the space in which the particles are generated. This can be 2 or 3.

calculate_track_parameters(particles: DataFrame) → DataFrame

Calculate track parameters for a DataFrame of particles.

calculate_track_parameters_2d(particles: DataFrame) → List[Series]

generate_particles() → DataFrame

Generate a DataFrame of particles based on the initialized parameters.

toytrack.dataloaders module

toytrack.transforms module

Module contents

class toytrack.Detector(dimension: int, hole_inefficiency: int | float = 0, layer_safety_guarantee: bool = False)

Bases: object

A class that represents a detector geometry.

Parameters:

• dimension (int) – The dimension of the space in which the detector is located. This can be 2 or 3.

• shape (str) – The shape of the detector. This can be ‘plane’, ‘cylinder’ or ‘sphere’.

• radius (float) – The radius of the detector. This is only used if shape is ‘cylinder’ or ‘sphere’.

• length (float) – The length of the detector. This is only used if shape is ‘cylinder’ or ‘plane’.

• layer_spacing (float) – The spacing between layers of the detector.

• number_of_layers (int) – The number of layers in the detector.

• hole_inefficiency (int, float) – If specified: If a float, then this is the inefficiency of each layer - i.e. the probability that a hit will not be recorded. If an int, then this is the number of holes that will be guaranteed per particle.

• layer_safety_guarantee (bool) – If True, then each particle is guaranteed to have exactly one hit per layer.

add_barrel(min_radius: float, max_radius: float, number_of_layers: int, length: float = None)

Add a barrel detector. Layers are spaced evenly between min_radius and max_radius.

add_endcap(min_radius: float, max_radius: float, min_z, max_z, layer_spacing: float, number_of_layers: int)

Add an endcap detector. This is a series of annuli, evenly spaced in z.

add_from_template(template: str = None, **kwargs)

Add a detector from a template.

generate_hits(particles: DataFrame) → DataFrame

Generate a DataFrame of hits based on the given particles.

generate_noise(hits_df: DataFrame, num_noise: int) → DataFrame

Generate a DataFrame of noise hits.

class toytrack.Event(particles: DataFrame, hits: DataFrame, tracks: ndarray, detector: Detector)

Bases: object

Class to store an event for the tracking micro challenges.

Parameters:

• particles (pd.DataFrame) – A DataFrame of particles

• hits (pd.DataFrame) – A DataFrame of hits

• tracks (np.ndarray) – A 2xN numpy array of the truth tracks.

• detector (Detector) – The detector used to generate the hits.

display(ax=None)

class toytrack.EventGenerator(particle_gun: ParticleGun | List[ParticleGun], detector: Detector, noise: float | List[float] | List[float | str] | int | List[int] | List[str | int] = None)

Bases: object

Class to generate events for the tracking micro challenges.

Parameters:

• particle_gun (ParticleGun or List[ParticleGun]) – The particle gun(s) to use to generate particles.

• detector (Detector) – The detector to use to generate hits.

• noise (float, list) – The amount of noise to add to the hits. This can be specified in three ways: - A single float: This will add a fixed fraction of noise hits. - A pair of floats: This will add a random fraction of noise hits with a uniform distribution. - A list of three elements: This will add a random fraction of noise hits. The third entry of the list is the distribution type (uniform, normal or poisson), and the first two entries are the parameters of the distribution. If the values are given as non-zero integers, then the noise is added as a fixed number of hits. If the values are given as floats between 0 and 1, then the noise is added as a fraction of the number of non-noise hits.

generate_event()

Generate an event based on the initialized parameters.

class toytrack.ParticleGun(num_particles: float | List[float] | List[float | str], pt: float | List[float] | List[float | str], pphi: float | List[float] | List[float | str], vx: float | List[float] | List[float | str], vy: float | List[float] | List[float | str], vz: float | List[float] | List[float | str] | None = None, dimension: int = 2)

Bases: object

A class that generates particles with a given kinematic distribution.

Parameters:

• num_particles (float, list) – The number of particles to generate. This can be specified in three ways: - A single float: This will generate a fixed number of particles. - A pair of floats: This will generate a random number of particles with a uniform distribution. - A list of three floats: This will generate a random number of particles. The third entry of the list is the distribution type (uniform, normal or poisson), and the first two entries are the parameters of the distribution. For example, if the third entry is ‘uniform’, then the first two entries are the minimum and maximum of the uniform distribution. If the third entry is ‘normal’, then the first two entries are the mean and standard deviation of the normal distribution. If the third entry is ‘poisson’, then the first entry is lambda and the second is omitted.

• pt (float, list) – The transverse momentum of the particles to be generated. This can be specified in three ways: 1. A float: All particles will be generated with this transverse momentum. 2. A list [min, max]: Particles will be generated uniform-random with a transverse momentum in this range. 3. A list [float, float, dist_type]: Particles will be generated with a transverse momentum in the range specified by the first two elements. The third element, dist_type, specifies the distribution type and can be either ‘uniform’ or ‘normal’. If uniform, then particles will be generated uniform-random in the range. If normal, then the first entry is the mean, the second entry is the standard deviation, and particles will be generated with a normal distribution.

• pphi (float, list) – The local phi momentum of the particles to be generated. This can be specified in the same ways as pt.

• vx (float, list) – The creation vertex x-coordinate of the particles to be generated. This can be specified in the same ways as pt.

• vy (float, list) – The creation vertex y-coordinate of the particles to be generated. This can be specified in the same ways as pt.

• vz (float, list) – The creation vertex z-coordinate of the particles to be generated. This can be specified in the same ways as pt.

• dimension (int) – The dimension of the space in which the particles are generated. This can be 2 or 3.

calculate_track_parameters(particles: DataFrame) → DataFrame

Calculate track parameters for a DataFrame of particles.

calculate_track_parameters_2d(particles: DataFrame) → List[Series]

generate_particles() → DataFrame

Generate a DataFrame of particles based on the initialized parameters.