Jetscape

class Jetscape.Jetscape(JETSCAPE_FILE: str, **kwargs: Dict[str, int | Tuple[int, int] | Dict[str, int | Tuple[int, int]]])[source]

Defines a Jetscape object.

The Jetscape class contains a single Jetscape hadron output file including all or only chosen events. It’s methods allow to directly act on all contained events as applying acceptance filters (e.g. un-/charged particles) to keep/remove particles by their PDG codes or to apply cuts (e.g. multiplicity, pseudo-/rapidity, pT). Once these filters are applied, the new data set can be saved 1) as a nested list containing all quantities of the Jetscape format 2) as a list containing Particle objects from the Particle or it can be printed to a file complying with the input format.

Note

If filters are applied, be aware that not all cuts commute.

Parameters:

JETSCAPE_FILEstr: Path to Jetscape file

Other Parameters:

**kwargsproperties, optional

kwargs are used to specify optional properties like a chunk reading and must be used like 'property'='value' where the possible properties are specified below.

Property	Description
`events` (int)	From the input Jetscape file load only a single event by specifying `events=i` where i is event number i.
`events` (tuple)	From the input Jetscape file load only a range of events given by the tuple `(first_event, last_event)` by specifying `events=(first_event, last_event)` where last_event is included.
`filters` (dict)	Apply filters on an event-by-event basis to directly filter the particles after the read in of one event. This method saves memory. The names of the filters are the same as the names of the filter methods. All filters are applied in the order in which they appear in the dictionary.
`particletype` (str)	This parameter allows to switch from the standard hadron file to the parton output of JETSCAPE. The parameter can be set to `particletype='hadron'` (default) or `particletype='parton'`. Quark charges are multiplied by 3 to make them integer values.

Notes

All filters with the keyword argument filters need the usual parameters for the filter functions in the dictionary. All filter functions without arguments need a True in the dictionary.

Examples

1. Initialization

To create a Jetscape object, the path to the Jetscape file has to be passed. By default the Jetscape object will contain all events of the input file. If the Jetscape object should only contain certain events, the keyword argument “events” must be used.

>>> from sparkx.Jetscape import Jetscape
>>>
>>> JETSCAPE_FILE_PATH = [Jetscape_directory]/particle_lists.dat
>>>
>>> # Jetscape object containing all events
>>> jetscape1 = Jetscape(JETSCAPE_FILE_PATH)
>>>
>>> # Jetscape object containing only the first event
>>> jetscape2 = Jetscape(JETSCAPE_FILE_PATH, events=0)
>>>
>>> # Jetscape object containing only events 2, 3, 4 and 5
>>> jetscape3 = Jetscape(JETSCAPE_FILE_PATH, events=(2,5))

2. Method Usage

All methods that apply filters to the Jetscape data return self. This means that methods can be concatenated. To access the Jetscape data as list to store it into a variable, the method particle_list() or particle_objects_list must be called in the end. Let’s assume we only want to keep participant pions in events with a multiplicity > 500:

>>> jetscape = Jetscape(JETSCAPE_FILE_PATH)
>>>
>>> pions = jetscape.multiplicity_cut(500, None).participants().particle_species((211, -211, 111))
>>>
>>> # save the pions of all events as nested list
>>> pions_list = pions.particle_list()
>>>
>>> # save the pions as list of Particle objects
>>> pions_particle_objects = pions.particle_objects_list()
>>>
>>> # print the pions to an Jetscape file
>>> pions.print_particle_lists_to_file('./particle_lists.dat')

3. Constructor cuts

Cuts can be performed directly in the constructor by passing a dictionary. This has the advantage that memory is saved because the cuts are applied after reading each single event. This is achieved by the keyword argument filters, which contains the filter dictionary. Filters are applied in the order in which they appear. Let’s assume we only want to keep pions in events with a multiplicity > 500:

>>> jetscape = Jetscape(JETSCAPE_FILE_PATH, filters={'multiplicity_cut':(500,None), 'particle_species':(211, -211, 111)}})
>>>
>>> # print the pions to a jetscape file
>>> jetscape.print_particle_lists_to_file('./particle_lists.dat')

Attributes:

PATH_JETSCAPE_str: Path to the Jetscape file
num_output_per_event_numpy.array: Array containing the event number and the number of particles in this event as num_output_per_event_[event i][num_output in event i] (updated when filters are applied)
num_events_int: Number of events contained in the Jetscape object (updated when filters are applied)
particle_type_str: The type of particles in the Jetscape file (e.g. ‘hadron’ or ‘parton’)
sigmaGen_Tuple[float, float]: The value of sigmaGen and the uncertainty
last_line_: str: The last line of the Jetscape file

Methods

particle_status:	Keep only particles with a given status flag
print_particle_lists_to_file:	Print current particle data to file with same format

charged_particles() → BaseStorer

Keep only charged particles in particle_list.

Returns:

selfBaseStorer object: Containing charged particles in every event only

create_loader(JETSCAPE_FILE: str | List[List[Particle]]) → None[source]

Creates a new JetscapeLoader object.

This method initializes a new JetscapeLoader object with the specified JETSCAPE file and assigns it to the loader attribute.

Parameters:

JETSCAPE_FILEUnion[str, List[List[Particle]]]: The path to the JETSCAPE file to be loaded. Must be a string.

Returns:

None

Raises:

TypeError: If JETSCAPE_FILE is not a string.

get_sigmaGen() → Tuple[float, float][source]

Returns the value of sigmaGen and the uncertainty in a tuple.

Returns:

float: The value of sigmaGen.

keep_baryons() → BaseStorer

Keep only baryons in particle_list.

Returns:

selfBaseStorer object: Containing baryons in every event only

keep_bottom() → BaseStorer

Keep only hadrons containing bottom quarks in particle_list.

Returns:

selfBaseStorer object: Containing hadrons containing bottom quarks in every event only

keep_charm() → BaseStorer

Keep only hadrons containing charm quarks in particle_list.

Returns:

selfBaseStorer object: Containing hadrons containing charm quarks in every event only

keep_down() → BaseStorer

Keep only hadrons containing down quarks in particle_list.

Returns:

selfBaseStorer object: Containing hadrons containing down quarks in every event only

keep_hadrons() → BaseStorer

Keep only hadrons in particle_list.

Returns:

selfBaseStorer object: Containing hadrons in every event only

keep_leptons() → BaseStorer

Keep only leptons in particle_list.

Returns:

selfBaseStorer object: Containing leptons in every event only

keep_mesons() → BaseStorer

Keep only mesons in particle_list.

Returns:

selfBaseStorer object: Containing mesons in every event only

keep_quarks() → BaseStorer

Keep only quarks in the particle_list.

Returns:

selfBaseStorer object: Containing quarks in every event only

keep_strange() → BaseStorer

Keep only hadrons containing strange quarks in particle_list.

Returns:

selfBaseStorer object: Containing hadrons containing strange quarks in every event only

keep_top() → BaseStorer

Keep only hadrons containing top quarks in particle_list.

Returns:

selfBaseStorer object: Containing hadrons containing top quarks in every event only

keep_up() → BaseStorer

Keep only hadrons containing up quarks in particle_list.

Returns:

selfBaseStorer object: Containing hadrons containing up quarks in every event only

lower_event_energy_cut(minimum_event_energy: int | float) → BaseStorer

Filters out events with total energy lower than a threshold.

Parameters:

minimum_event_energyint or float: The minimum event energy threshold. Should be a positive integer or float.

Returns:

self: BaseStorer object: The updated instance of the class contains only events above the energy threshold.

Raises:

TypeError: If the minimum_event_energy parameter is not an integer or float.
ValueError: If the minimum_event_energy parameter is less than or equal to 0.

mT_cut(cut_value_tuple: Tuple[float | None, float | None]) → BaseStorer

Apply transverse mass cut to all events by passing an acceptance range by cut_value_tuple. All particles outside this range will be removed.

Parameters:

cut_value_tupletuple: Tuple with the upper and lower limits of the mT acceptance range (cut_min, cut_max). If one of the limits is not required, set it to None, i.e. (None, cut_max) or (cut_min, None).

Returns:

selfBaseStorer object: Containing only particles complying with the transverse mass cut for all events

multiplicity_cut(cut_value_tuple: Tuple[float | None, float | None]) → BaseStorer

Apply multiplicity cut. Remove all events with a multiplicity not complying with cut_value.

Parameters:

cut_value_tupletuple: Upper and lower bound for multiplicity. If the multiplicity of an event is not in this range, the event is discarded. The range is inclusive on the lower bound and exclusive on the upper bound.

Returns:

selfBaseStorer object: Containing only events with a multiplicity >= min_multiplicity

num_events() → int | None

Returns the number of events in particle_list.

num_events is updated with every manipulation e.g. after applying cuts.

Returns:

num_events_int: Number of events in particle_list

num_output_per_event() → ndarray | None

Returns a numpy array containing the event number (starting with 1) and the corresponding number of particles created in this event as

num_output_per_event[event_n, number_of_particles_in_event_n]

num_output_per_event is updated with every manipulation e.g. after applying cuts.

Returns:

num_output_per_event_numpy.ndarray: Array containing the event number and the corresponding number of particles

pT_cut(cut_value_tuple: Tuple[float | None, float | None]) → BaseStorer

Apply transverse momentum cut to all events by passing an acceptance range by cut_value_tuple. All particles outside this range will be removed.

Parameters:

cut_value_tupletuple: Tuple with the upper and lower limits of the pT acceptance range (cut_min, cut_max). If one of the limits is not required, set it to None, i.e. (None, cut_max) or (cut_min, None).

Returns:

selfBaseStorer object: Containing only particles complying with the transverse momentum cut for all events

participants() → Jetscape[source]

Raises an error because participants are not defined for Jetscape events.

Returns:

NotImplementedError: Always, because participants are not defined for Jetscape events.

particle_list() → List

Returns a nested python list containing all quantities from the current data as numerical values with the following shape:

Single Event: [[output_line][particle_quantity]]

Multiple Events: [event][output_line][particle_quantity]

Returns:

list: Nested list containing the current data

particle_objects_list() → List | None

Returns a nested python list containing all particles from the data as particle objects from Particle:

Single Event: [particle_object]

Multiple Events: [event][particle_object]

Returns:

particle_list_list: List of particle objects from Particle

particle_species(pdg_list: int | Tuple[int] | List[int] | ndarray) → BaseStorer

Keep only particle species given by their PDG ID in every event.

Parameters:

pdg_listint: To keep a single particle species only, pass a single PDG ID
pdg_listtuple/list/array: To keep multiple particle species, pass a tuple or list or array of PDG IDs

Returns:

selfBaseStorer object: Containing only particle species specified by pdg_list for every event

particle_status(status_list: int | Tuple[int, ...] | List[int] | ndarray) → BaseStorer

Keep only particles with a given particle status.

Parameters:

status_listint: To keep a particles with a single status only, pass a single status
status_listtuple/list/array: To keep hadrons with different hadron status, pass a tuple or list or array

Returns:

selfBaseStorer object: Containing only hadrons with status specified by status_list for every event

print_particle_lists_to_file(output_file: str) → None[source]

Prints the current Jetscape data to an output file specified by output_file with the same format as the input file. For empty events, only the event header is printed.

Parameters:

output_filestr: Path to the output file like [output_directory]/particle_lists.dat

pseudorapidity_cut(cut_value: float | Tuple[float, float]) → BaseStorer

Apply pseudo-rapidity cut to all events and remove all particles with pseudo-rapidity not complying with cut_value.

Parameters:

cut_valuefloat: If a single value is passed, the cut is applied symmetrically around 0. For example, if cut_value = 1, only particles with rapidity in [-1.0, 1.0] are kept.
cut_valuetuple: To specify an asymmetric acceptance range for the pseudo-rapidity of particles, pass a tuple (cut_min, cut_max)

Returns:

selfBaseStorer object: Containing only particles complying with the pseudo-rapidity cut for all events

rapidity_cut(cut_value: float | Tuple[float, float]) → BaseStorer

Apply rapidity cut to all events and remove all particles with rapidity not complying with cut_value.

Parameters:

cut_valuefloat: If a single value is passed, the cut is applied symmetrically around 0. For example, if cut_value = 1, only particles with rapidity in [-1.0, 1.0] are kept.
cut_valuetuple: To specify an asymmetric acceptance range for the rapidity of particles, pass a tuple (cut_min, cut_max)

Returns:

selfBaseStorer object: Containing only particles complying with the rapidity cut for all events

remove_particle_species(pdg_list: int | Tuple[int] | List[int] | ndarray) → BaseStorer

Remove particle species from particle_list by their PDG ID in every event.

Parameters:

pdg_listint: To remove a single particle species only, pass a single PDG ID
pdg_listtuple/list/array: To remove multiple particle species, pass a tuple or list or array of PDG IDs

Returns:

selfBaseStorer object: Containing all but the specified particle species in every event

remove_photons() → BaseStorer

Remove photons from particle_list.

Returns:

selfBaseStorer object: Containing all but photons in every event

spacetime_cut(dim: str, cut_value_tuple: Tuple[float, float]) → Jetscape[source]

Raises an error because spacetime cuts are not possible for Jetscape events.

Parameters:

dimstr: The dimension to apply the cut.
cut_value_tupletuple: The values to apply the cut.

Raises:

NotImplementedError: Always, because spacetime cuts are not possible for Jetscape events.

spacetime_rapidity_cut(cut_value: float | Tuple[float, float]) → Jetscape[source]

Raises an error because spacetime rapidity cuts are not possible for Jetscape events.

Parameters:

cut_valuefloat: If a single value is passed, the cut is applied symmetrically around 0. For example, if cut_value = 1, only particles with spacetime rapidity in [-1.0, 1.0] are kept.
cut_valuetuple: To specify an asymmetric acceptance range for the spacetime rapidity of particles, pass a tuple (cut_min, cut_max)

Raises:

NotImplementedError: Always, because spacetime rapidity cuts are not possible for Jetscape events.

spectators() → Jetscape[source]

Raises an error because spectators are not defined for Jetscape events.

Returns:

NotImplementedError: Always, because spectators are not defined for Jetscape events.

uncharged_particles() → BaseStorer

Keep only uncharged particles in particle_list.

Returns:

selfBaseStorer object: Containing uncharged particles in every event only