CORSIKA

Support modules for running CORSIKA.

corsika_config

CORSIKA configuration.

class corsika.corsika_config.CorsikaConfig(array_model, args_dict, db_config=None, label=None, dummy_simulations=False)

Configuration for the CORSIKA air shower simulation software.

Follows closely the CORSIKA definitions and output format (see CORSIKA manual).

The configuration is set as a dict corresponding to the command line configuration groups (especially simulation_software, simulation configuration, simulation parameters).

Parameters:

array_modelArrayModel

Array model.

args_dictdict

Configuration dictionary.

db_configdict

MongoDB configuration.

labelstr

Instance label.

dummy_simulationsbool

If True, the configuration is generated for dummy simulations (e.g., sim_telarray requires for some run modes a valid CORSIKA input file).

assert_corsika_configurations_match(model_versions, db_config=None)

Assert that CORSIKA configurations match across all model versions.

Parameters:

model_versionslist

List of model versions to check.

db_configdict, optional

Database configuration.

Raises:

InvalidCorsikaInputError

If CORSIKA parameters are not identical across all model versions.

fill_corsika_configuration(args_dict, db_config=None)

Fill CORSIKA configuration.

Dictionary keys are CORSIKA parameter names. Values are converted to CORSIKA-consistent units.

Parameters:

args_dictdict

Configuration dictionary.

db_config: dict

Database configuration.

Returns:

dict

Dictionary with CORSIKA parameters.

generate_corsika_input_file(use_multipipe=False, use_test_seeds=False)

Generate a CORSIKA input file.

Parameters:

use_multipipe: bool

Whether to set the CORSIKA Inputs file to pipe the output directly to sim_telarray.

get_config_parameter(par_name)

Get value of CORSIKA configuration parameter.

Parameters:

par_name: str

Name of the parameter as used in the CORSIKA input file (e.g. PRMPAR, THETAP …).

Returns:

list

Value(s) of the parameter.

Raises:

KeyError

When par_name is not a valid parameter name.

get_corsika_config_file_name(file_type, run_number=None)

Get a CORSIKA config style file name for various configuration file types.

Parameters:

file_type: str

The type of file (determines the file suffix). Choices are config_tmp, config or output_generic.

run_number: int

Run number.

Returns:

str

for file_type=”config_tmp”:

Return CORSIKA input file name for one specific run. This is the input file after being pre-processed by sim_telarray (pfp).

for file_type=”config”:

Return generic CORSIKA config input file name.

for file_type=”output_generic”

Return generic file name for the TELFIL option in the CORSIKA inputs file.

for file_type=”multipipe”

Return multipipe “file name” for the TELFIL option in the CORSIKA inputs file.

Raises:

ValueError

If file_type is unknown or if the run number is not given for file_type==config_tmp.

get_corsika_telescope_list()

List of telescope positions in the format required for the CORSIKA input file.

Returns:

str

Piece of text to be added to the CORSIKA input file.

property primary

Primary particle name.

property primary_particle

Primary particle.

property run_number

Set run number.

set_output_file_and_directory(use_multipipe=False)

Set output file names and directories.

Parameters:

use_multipipe: bool

Whether to set the CORSIKA Inputs file to pipe the output directly to sim_telarray. Defines directory names.

Returns:

str

Output file name.

validate_run_number(run_number)

Validate run number and return it. Return run number from configuration if None.

Parameters:

run_number: int

Run number.

Returns:

int

Run number.

Raises:

ValueError

If run_number is not a valid value (< 1 or > 999999).

exception corsika.corsika_config.InvalidCorsikaInputError

Exception for invalid corsika input.

primary_particle

Primary particle definition.

class corsika.primary_particle.PrimaryParticle(particle_id_type=None, particle_id=None)

Primary particle definition using CORSIKA7, eventio, or PDG ID.

Uses a dictionary to map particle common names to CORSIKA7 IDs. Particles not found in the dictionary are searched in the PDG particle database.

Parameters:

particle_id_typestr

Type of the primary particle ID (‘corsika7_id’, ‘common_name’, or ‘pdg_id’).

particle_idint or str

The actual ID of the primary particle.

property corsika7_id

CORSIKA7 ID of the primary particle.

property eventio_id

EventIO ID of the primary particle.

0 (gamma), 1(e-), 2(mu-), 100*A+Z for nucleons and nuclei, negative for antimatter.

property name

Common name of the primary particle.

static particle_names()

Primary particles including common names, CORSIKA7 IDs, and PDG IDs.

Returns:

dict

Dictionary of particle names, CORSIKA7 IDs, and PDG IDs.

property pdg_id

PDG ID of the primary particle.

property pdg_name

PDG name of the primary particle.

corsika_histograms

Extract Cherenkov photons information from a CORSIKA IACT file.

class corsika.corsika_histograms.CorsikaHistograms(input_file, label=None, output_path=None, hdf5_file_name=None)

Extracts the Cherenkov photons information from a CORSIKA IACT file.

Parameters:

input_file: str or Path

CORSIKA IACT file provided by the CORSIKA simulation.

label: str

Instance label.

output_path: str

Path where to save the output of the class methods.

hdf5_file_name: str

HDF5 file name for histogram storage.

Raises:

FileNotFoundError:

if the input file given does not exist.

property corsika_version

Get the version of the CORSIKA IACT file.

Returns:

float:

The version of CORSIKA used to produce the CORSIKA IACT file given by self.input_file.

property dict_1d_distributions

Dictionary to label the 1D distributions according to the class methods.

Returns:

dict:

The dictionary with information about the 1D distributions.

property dict_2d_distributions

Dictionary to label the 2D distributions according to the class methods.

Returns:

dict:

The dictionary with information about the 2D distributions.

event_1d_histogram(key, bins=50, hist_range=None)

Create a histogram for the all events using key as parameter.

Valid keys are stored in self.all_event_keys (CORSIKA defined).

Parameters:

key: str

The information from which to build the histogram, e.g. total_energy, zenith or first_interaction_height.

bins: float

Number of bins for the histogram.

hist_range: 2-tuple

Tuple to define the range of the histogram.

Returns:

numpy.ndarray

The counts of the histogram.

numpy.array

Edges of the histogram.

Raises:

KeyError:

If key is not valid.

event_2d_histogram(key_1, key_2, bins=50, hist_range=None)

Create a 2D histogram for the all events using key_1 and key_2 as parameters.

Valid keys are stored in self.all_event_keys (CORSIKA defined).

Parameters:

key_1: str

The information from which to build the histogram, e.g. total_energy, zenith or first_interaction_height.

key_2: str

The information from which to build the histogram, e.g. total_energy, zenith or first_interaction_height.

bins: float

Number of bins for the histogram.

hist_range: 2-tuple

Tuple to define the range of the histogram.

Returns:

numpy.ndarray

The counts of the histogram.

numpy.array

x Edges of the histogram.

numpy.array

y Edges of the histogram.

Raises:

KeyError:

If at least one of the keys is not valid.

property event_azimuth_angles

Get the azimuth angles of the simulated events in astropy units of degrees.

Returns:

astropy.Quantity

The azimuth angles for each event, usually in degrees.

property event_energies

Get the energy of the simulated events in astropy units of TeV.

Returns:

astropy.Quantity

The total energies of the incoming particles for each event, usually in TeV.

property event_first_interaction_heights

Get the height of the first interaction in astropy units of km.

If negative, tracking starts at margin of atmosphere, see TSTART in the CORSIKA 7 user guide.

Returns:

astropy.Quantity

The first interaction height for each event, usually in km.

property event_zenith_angles

Get the zenith angles of the simulated events in astropy units of degrees.

Returns:

astropy.Quantity

The zenith angles for each event.

export_event_header_1d_histogram(event_header_element, bins=50, hist_range=None, overwrite=False)

Export ‘event_header_element’ from CORSIKA to hd5 for a 1D histogram.

Parameters:

event_header_element: str

The key to the CORSIKA event header element. Possible choices are stored in ‘self.all_event_keys’.

bins: float

Number of bins for the histogram.

hist_range: 2-tuple

Tuple to define the range of the histogram.

overwrite: bool

If True overwrites the histograms already saved in the hdf5 file.

export_event_header_2d_histogram(event_header_element_1, event_header_element_2, bins=50, hist_range=None, overwrite=False)

Export event_header of a 2D histogram to a hdf5 file.

Searches the 2D histogram for the key ‘event_header_element_1’ and ‘event_header_element_2’from the CORSIKA event header.

Parameters:

event_header_element_1: str

The key to the CORSIKA event header element.

event_header_element_2: str

The key to the CORSIKA event header element. Possible choices for ‘event_header_element_1’ and ‘event_header_element_2’ are stored in ‘self.all_event_keys’.

bins: float

Number of bins for the histogram.

hist_range: 2-tuple

Tuple to define the range of the histogram.

overwrite: bool

If True overwrites the histograms already saved in the hdf5 file.

export_histograms(overwrite=False)

Export the histograms to hdf5 files.

Parameters:

overwrite: bool

If True overwrites the histograms already saved in the hdf5 file.

get_2d_num_photons_distr()

Get the distribution of Cherenkov photons per event per telescope.

It returns the 2D array accounting for the events from the telescopes given by self.telescope_indices.

Returns:

numpy.ndarray

The counts of the histogram.

numpy.array

An array that counts the telescopes in self.telescope_indices

numpy.array

Number of photons per event per telescope in self.telescope_indices.

get_2d_photon_density_distr()

Get 2D histograms of position of the Cherenkov photons on the ground.

It returns the photon density per square meter.

Returns:

numpy.ndarray

The values of the histogram, usually in $m^{-2}$

numpy.array

The x bin edges of the density/count histograms in x, usually in meters.

numpy.array

The y bin edges of the density/count histograms in y, usually in meters.

get_2d_photon_direction_distr()

Get 2D histograms of incoming direction of the Cherenkov photons on the ground.

Returns:

numpy.ndarray

The counts of the histogram.

numpy.array

The x bin edges of the direction histograms in cos(x).

numpy.array

The y bin edges of the direction histograms in cos(y)

get_2d_photon_position_distr()

Get 2D histograms of position of the Cherenkov photons on the ground.

Returns:

numpy.ndarray

The counts of the histogram.

numpy.array

The x bin edges of the count histograms in x, usually in meters.

numpy.array

The y bin edges of the count histograms in y, usually in meters.

get_2d_photon_time_altitude_distr()

Get 2D histograms of the time and altitude of the photon production.

Returns:

numpy.ndarray

The counts of the histogram.

numpy.array

The x bin edges of the time_altitude histograms, usually in ns.

numpy.array

The y bin edges of the time_altitude histograms, usually in km.

get_event_parameter_info(parameter)

Get specific information (i.e. any parameter) of the events.

The parameter is passed through the key word parameter. Available options are to be found under self.all_event_keys. The unit of the parameter, if any, is given according to the CORSIKA version (please see user guide in this case).

Parameters:

parameter: str

The parameter of interest. Available options are to be found under self.all_event_keys.

Returns:

astropy.Quantity

The array with the event information as required by the parameter.

Raises:

KeyError:

If parameter is not valid.

get_num_photons_per_event_distr(bins=50, hist_range=None)

Get the distribution of photons per event.

Parameters:

bins: float

Number of bins for the histogram.

hist_range: 2-tuple

Tuple to define the range of the histogram.

Returns:

numpy.ndarray

The counts of the histogram.

numpy.array

Number of photons per event.

get_num_photons_per_telescope_distr(bins=50, hist_range=None)

Get the distribution of photons per telescope.

Parameters:

bins: float

Number of bins for the histogram.

hist_range: 2-tuple

Tuple to define the range of the histogram.

Returns:

numpy.ndarray

The counts of the histogram.

numpy.array

Number of photons per telescope.

get_photon_altitude_distr()

Get the emission altitude of the Cherenkov photons.

Returns:

numpy.ndarray

The counts of the histogram.

numpy.array

The bin edges of the photon altitude histograms in km.

get_photon_density_distr(bins=None, max_dist=None)

Get the photon density distribution on the ground in relation to the center of the array.

Parameters:

bins: float

Number of bins of the radial distribution.

max_dist: float

Maximum distance to consider in the 1D histogram (in meters).

Returns:

np.array

The density distribution of the 1D histogram with size = int(max_dist/bin_size), usually in $m^{-2}$.

np.array

The bin edges of the 1D histogram in meters with size = int(max_dist/bin_size) + 1, usually in meter.

get_photon_radial_distr(bins=None, max_dist=None)

Get the phton radial distribution on the ground in relation to the center of the array.

Parameters:

bins: float

Number of bins of the radial distribution.

max_dist: float

Maximum distance to consider in the 1D histogram (in meters).

Returns:

np.array

The counts of the 1D histogram with size = int(max_dist/bin_size).

np.array

The bin edges of the 1D histogram in meters with size = int(max_dist/bin_size) + 1, usually in meter.

get_photon_time_of_emission_distr()

Get the distribution of the emitted time of the Cherenkov photons.

The clock starts when the particle crosses the top of the atmosphere (CORSIKA-defined) if self.event_first_interaction_heights is positive or at first interaction if otherwise.

Returns:

numpy.ndarray

The counts of the histogram.

numpy.array

The bin edges of the time histograms in ns.

get_photon_wavelength_distr()

Get histograms with the wavelengths of the photon bunches.

Returns:

np.array

The counts of the wavelength histogram.

np.array

The bin edges of the wavelength histogram in nanometers.

get_run_info(parameter)

Get specific information (i.e. any parameter) of the run.

The parameter is passed through the key word parameter. Available options are to be found under self.all_run_keys. The unit of the parameter, if any, is given according to the CORSIKA version (please see user guide in this case).

Parameters:

parameter: str

The parameter of interest. Available options are to be found under self.all_run_keys.

Raises:

KeyError:

If parameter is not valid.

property hdf5_file_name

Property for the hdf5 file name.

The idea of this property is to allow setting (or changing) the name of the hdf5 file even after creating the class instance.

property header

Get the run header.

Returns:

dict:

The run header.

property hist_config

The configuration of the histograms.

Returns:

dict:

the dictionary with the histogram configuration.

hist_config_to_yaml(file_name=None)

Save the histogram configuration dictionary to a yaml file.

Parameters:

file_name: str

Name of the output file, in which to save the histogram configuration.

property individual_telescopes

Return the individual telescopes as property.

property magnetic_field

Get the Earth magnetic field from the events header in astropy units of microT.

A tuple with Earth’s magnetic field in the x and z directions are returned.

Returns:

astropy.Quantity

The Earth magnetic field in the x direction used for each event.

astropy.Quantity

The Earth magnetic field in the z direction used for each event.

property num_photons_per_event

Get the the number of photons per events.

Includes the telescopes indicated by self.telescope_indices.

Returns:

numpy.array

Number of photons per event.

property num_photons_per_event_per_telescope

The number of photons per event per telescope.

property num_photons_per_telescope

The number of photons per event, considering the telescopes given by self.telescope_indices.

Returns:

numpy.array

Number of photons per telescope.

parse_telescope_indices(indices_arg)

Return telescope indices as ndarray[int] or None.

Accepts None, a sequence of strings/ints. Raises ValueError on invalid input.

read_event_information()

Read the information about the events from their headers and save as a class instance.

The main information can also be fetched individually through the functions below. For the remaining information (such as px, py, pz), use this function.

run_export_pipeline(*, individual_telescopes: bool, hist_config, indices_arg, write_pdf: bool, write_hdf5: bool, event1d: list | None, event2d: list | None, test: bool = False) → dict

Run the full histogram export pipeline and return output artifact paths.

Returns a dict with optional keys: pdf_photons, pdf_event1d, pdf_event2d.

set_histograms(telescope_indices=None, individual_telescopes=None, hist_config=None)

Create and fill Cherenkov photons histograms using information from the CORSIKA IACT file.

Parameters:

telescope_indices: int or list of int

The indices of the specific telescopes to be inspected.

individual_telescopes: bool

if False, the histograms are supposed to be filled for all telescopes. Default is False. if True, one histogram is set for each telescope separately.

hist_config:

yaml file with the configuration parameters to create the histograms. For the correct format, please look at the docstring of _create_histogram_default_config. Alternatively, it can be a dictionary with the configuration parameters to create the histograms.

Returns:

list: list of boost_histogram.Histogram instances.

Raises:

AttributeError:

if event has not photon saved.

should_overwrite(write_hdf5: bool, event1d: list | None, event2d: list | None) → bool

Return True if output HDF5 exists and any writing flag is requested.

property telescope_indices

The telescope index (or indices), which are considered for the production of the histograms.

Returns:

list:

The indices of the telescopes of interest.

property telescope_positions

The telescope positions found in the CORSIKA output file.

It does not depend on the telescope_indices attribute.

Returns:

numpy.ndarray

x, y and z positions of the telescopes and their radius according to the CORSIKA spherical representation of the telescopes.

property total_num_photons

The total number of photons.

Returns:

float

Total number photons.

exception corsika.corsika_histograms.HistogramNotCreatedError

Exception for histogram not created.