Oscar

class Oscar.Oscar(OSCAR_FILE, **kwargs)[source]

Defines an Oscar object.

The Oscar class contains a single .oscar file including all or only chosen events in either the Oscar2013 or Oscar2013Extended format. It’s methods allow to directly act on all contained events as applying acceptance filters (e.g. un/charged particles, spectators/participants) 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 accessed as a

nested list containing all quantities of the Oscar format
list containing Particle objects from the Particle class

or it may be printed to a file complying with the input format.

Note

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

Parameters:

OSCAR_FILEstr: Path to Oscar 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 Oscar file load only a single event by specifying `events=i` where i is event number i.
`events` (tuple)	From the input Oscar 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.

Notes

If the filters keyword with the spacetime_cut is used, then a list specifying the dimension to be cut in the first entry and the tuple with the cut boundaries in the second entry is needed. For all other filters, the dictionary only needs the filter name as key and the filter argument as value. All filter functions without arguments need a True in the dictionary.

Examples

1. Initialization

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

>>> from sparkx.Oscar import Oscar
>>>
>>> OSCAR_FILE_PATH = [Oscar_directory]/particle_lists.oscar
>>>
>>> # Oscar object containing all events
>>> oscar1 = Oscar(OSCAR_FILE_PATH)
>>>
>>> # Oscar object containing only the first event
>>> oscar2 = Oscar(OSCAR_FILE_PATH, events=0)
>>>
>>> # Oscar object containing only events 2, 3, 4 and 5
>>> oscar3 = Oscar(OSCAR_FILE_PATH, events=(2,5))

2. Method Usage

All methods that apply filters to the Oscar data return self. This means that methods can be concatenated. To access the Oscar 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:

>>> oscar = Oscar(OSCAR_FILE_PATH)
>>>
>>> pions = oscar.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 oscar file
>>> pions.print_particle_lists_to_file('./particle_lists.oscar')

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 participant pions in events with a multiplicity > 500:

>>> oscar = Oscar(OSCAR_FILE_PATH, filters={'multiplicity_cut':500, 'participants':True, 'particle_species':(211, -211, 111)})
>>>
>>> # print the pions to an oscar file
>>> oscar.print_particle_lists_to_file('./particle_lists.oscar')

Attributes:

PATH_OSCAR_str: Path to the Oscar file
oscar_format_str: Input Oscar format “Oscar2013” or “Oscar2013Extended” (set automatically)
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 Oscar object (updated when filters are applied)
event_end_lines_list: List containing all comment lines at the end of each event as str. Needed to print the Oscar object to a file.

Methods

particle_list:	Returns current Oscar data as nested list
particle_objects_list:	Returns current Oscar data as nested list of Particle objects
num_events:	Get number of events
num_output_per_event:	Get number of particles in each event
oscar_format:	Get Oscar format of the input file
particle_species:	Keep only particles with given PDG ids
remove_particle_species:	Remove particles with given PDG ids
participants:	Keep participants only
spectators:	Keep spectators only
lower_event_energy_cut:	Filters out events with total energy lower than a threshold.
charged_particles:	Keep charged particles only
uncharged_particles:	Keep uncharged particles only
strange_particles:	Keep strange particles only
spacetime_cut:	Apply spacetime cut to all particles
pt_cut:	Apply pT cut to all particles
rapidity_cut:	Apply rapidity cut to all particles
pseudorapidity_cut:	Apply pseudorapidity cut to all particles
spatial_rapidity_cut:	Apply spatial rapidity (space-time rapidity) cut to all particles
multiplicity_cut:	Apply multiplicity cut to all particles
print_particle_lists_to_file:	Print current particle data to file with same format

Oscar.particle_list()[source]

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

Oscar.particle_objects_list()[source]

Returns a nested python list containing all particles from the Oscar2013/Oscar2013Extended output as particle objects from Particle:

Single Event: [particle_object]

Multiple Events: [event][particle_object]

Returns:

particle_list_list: List of particle objects from Particle

Oscar.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

Oscar.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, 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

Oscar.oscar_format()[source]

Get the Oscar format of the input file.

Returns:

oscar_format_str: Oscar format of the input Oscar file as string (“Oscar2013” or “Oscar2013Extended”)

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

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

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

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

Oscar.participants()[source]

Keep only participants in particle_list

Returns:

selfOscar object: Containing participants in every event only

Oscar.spectators()[source]

Keep only spectators in particle_list

Returns:

selfOscar object: Containing spectators in every event only

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

Oscar.charged_particles()[source]

Keep only charged particles in particle_list

Returns:

selfOscar object: Containing charged particles in every event only

Oscar.uncharged_particles()[source]

Keep only uncharged particles in particle_list

Returns:

selfOscar object: Containing uncharged particles in every event only

Oscar.strange_particles()[source]

Keep only strange particles in particle_list

Returns:

selfOscar object: Containing strange particles in every event only

Oscar.pt_cut(cut_value_tuple)[source]

Apply transverse momentum 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:

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

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

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

Oscar.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 applied 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:

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

Oscar.spatial_rapidity_cut(cut_value)[source]

Apply spatial rapidity (space-time rapidity) cut to all events and remove all particles with spatial 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 spatial rapidity in [-1.0, 1.0] are kept.
cut_valuetuple: To specify an asymmetric acceptance range for the spatial rapidity of particles, pass a tuple (cut_min, cut_max)

Returns:

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

Oscar.multiplicity_cut(min_multiplicity)[source]

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

Parameters:

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

Returns:

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

Oscar.print_particle_lists_to_file(output_file)[source]

Prints the current Oscar 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.oscar