Jetscape

class Jetscape.Jetscape(JETSCAPE_FILE, **kwargs)[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/romove 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 ParticleClass or it can be printed to a file complying with the input format.

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.

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.

 1>>> from Jetscape import Jetscape
 2>>>
 3>>> JETSCAPE_FILE_PATH = [Jetscape_directory]/particle_lists.dat
 4>>>
 5>>> # Jetscape object containing all events
 6>>> jetscape1 = Jetscape(JETSCAPE_FILE_PATH)
 7>>>
 8>>> # Jetscape object containing only the first event
 9>>> jetscape2 = Jetscape(JETSCAPE_FILE_PATH, events=0)
10>>>
11>>> # Jetscape object containing only events 2, 3, 4 and 5
12>>> 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("path_to_file")
>>>
>>> pions = jetscape.multiplicity_cut(500).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')
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)

list_of_all_valid_pdg_ids_list

List of all PDG codes contained in the external particle package as int values

Methods

particle_list:

Returns current Jetscape data as nested list

particle_objects_list:

Returns current Jetscape data as nested list of ParticleClass objects

num_events:

Get number of events

num_output_per_event:

Get number of particles in each event

particle_species:

Keep only particles with given PDG ids

remove_particle_species:

Remove particles with given PDG ids

charged_particles:

Keep charged particles only

uncharged_particles:

Keep uncharged particles only

strange_particles:

Keep strange particles only

particle_status:

Keep only particles with a given status flag

pt_cut:

Apply pT cut to all particles

rapidity_cut:

Apply rapidity cut to all particles

pseudorapidity_cut:

Apply pseudorapidity cut to all particles

multiplicity_cut:

Apply multiplicity cut to all particles

lower_event_energy_cut:

Filters out events with total energy lower than a threshold.

print_particle_lists_to_file:

Print current particle data to file with same format

Jetscape.particle_list()[source]
Jetscape.particle_objects_list()[source]

Returns a nested python list containing all quantities from the current Jetscape 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 Oscar data

Jetscape.num_events()[source]

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

Jetscape.num_output_per_event()[source]

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, numer_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

Jetscape.particle_species(pdg_list)[source]

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:
selfJetscape object

Containing only particle species specified by pdg_list for every event

Jetscape.remove_particle_species(pdg_list)[source]

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:
selfJetscape object

Containing all but the specified particle species in every event

Jetscape.lower_event_energy_cut(minimum_event_energy)[source]

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: Jetscape 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.

Jetscape.charged_particles()[source]

Keep only charged particles in particle_list

Returns:
selfJetscape object

Containing charged particles in every event only

Jetscape.uncharged_particles()[source]

Keep only uncharged particles in particle_list

Returns:
selfJetscape object

Containing uncharged particles in every event only

Jetscape.strange_particles()[source]

Keep only strange particles in particle_list

Returns:
selfJetscape object

Containing strange particles in every event only

Jetscape.pt_cut(cut_value_tuple)[source]

Apply p_t cut to all events by passing an acceptance range by ::code`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:
selfJetscape object

Containing only particles complying with the p_t cut for all events

Jetscape.rapidity_cut(cut_value)[source]

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 applyed 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:
selfJetscape object

Containing only particles complying with the rapidity cut for all events

Jetscape.pseudorapidity_cut(cut_value)[source]

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 applyed symmetrically around 0. For example, if cut_value = 1, only particles with pseudo-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:
selfJetscape object

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

Jetscape.multiplicity_cut(min_multiplicity)[source]

Apply multiplicity cut. Remove all events with a multiplicity lower than min_multiplicity

Parameters:
min_multiplicityfloat

Lower bound for multiplicity. If the multiplicity of an event is lower than min_multiplicity, this event is discarded.

Returns:
selfJetscape object

Containing only events with a multiplicity >= min_multiplicity

Jetscape.print_particle_lists_to_file(output_file)[source]

Prints the current Jetscape data to an output file specified by output_file with the same format as the input file

Parameters:
output_filestr

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