sim_telarray

Support modules for running sim_telarray.

simtel_config_reader

Read model parameters and configuration from sim_telarray configuration files.

class simtel.simtel_config_reader.SimtelConfigReader(schema_file, simtel_config_file, simtel_telescope_name, parameter_name=None, camera_pixels=None)

Reads model parameters from configuration files and converts to the simtools representation.

The output format are simtool-db-style json dicts. Model parameters are read from sim_telarray configuration files. The sim_telarray configuration can be generated using e.g., the following sim_telarray command:

… code-block:: console

sim_telarray/bin/sim_telarray -c sim_telarray/cfg/CTA/CTA-PROD6-LaPalma.cfg -C limits=no-internal -C initlist=no-internal -C list=no-internal -C typelist=no-internal -C maximum_telescopes=30 -DNSB_AUTOSCALE -DNECTARCAM -DHYPER_LAYOUT -DNUM_TELESCOPES=30 /dev/null 2>|/dev/null | grep ‘(@cfg)’

Parameters:

schema_file: str

Schema file describing the model parameter.

simtel_config_file: str or Path

Path of the file to read from.

simtel_telescope_name: str

Telescope name (sim_telarray convention)

parameter_name: str

Parameter name (default: read from schema file)

camera_pixels: int

Number of camera pixels

compare_simtel_config_with_schema()

Compare limits and defaults reported by simtel_array with schema.

This is mostly for debugging purposes and includes simple printing. Check for differences in ‘default’ and ‘limits’ entries.

read_simtel_config_file(simtel_config_file, simtel_telescope_name)

Read sim_telarray configuration file and return a dictionary with the parameter values.

Parameters:

simtel_config_file: str or Path

Path of the file to read from.

simtel_telescope_name: str

Telescope name (sim_telarray convention)

Returns:

dict

Dictionary with the parameter values.

simtel_config_writer

Configuration file writer for sim_telarray.

class simtel.simtel_config_writer.SimtelConfigWriter(site, model_version, layout_name=None, telescope_model_name=None, label=None)

SimtelConfigWriter writes sim_telarray configuration files.

It is designed to be used by model classes (TelescopeModel and ArrayModel) only.

Parameters:

site: str

South or North.

model_version: str

Model version.

telescope_model_name: str

Telescope model name.

layout_name: str

Layout name.

label: str

Instance label. Important for output file naming.

write_array_config_file(config_file_path, telescope_model, site_model)

Write the sim_telarray config file for an array of telescopes.

Parameters:

config_file_path: str or Path

Path of the file to write on.

telescope_model: dict of TelescopeModel

Dictionary of TelescopeModel’s instances as used by the ArrayModel instance.

site_model: Site model

Site model.

write_single_mirror_list_file(mirror_number, mirrors, single_mirror_list_file, set_focal_length_to_zero=False)

Write the sim_telarray mirror list file for a single mirror.

Parameters:

mirror_number: int

Mirror number.

mirrors: Mirrors

Instance of Mirrors.

single_mirror_list_file: str or Path

Path of the file to write on.

set_focal_length_to_zero: bool

Flag to set the focal length to zero.

write_telescope_config_file(config_file_path, parameters, config_parameters=None)

Write the sim_telarray config file for a single telescope.

Parameters:

config_file_path: str or Path

Path of the file to write on.

parameters: dict

Model parameters

config_parameters: dict

Simulation software configuration parameters

simtel_io_events

Read sim_telarray events from file.

exception simtel.simtel_io_events.InconsistentInputFileError

Exception for inconsistent input file.

class simtel.simtel_io_events.SimtelIOEvents(input_files=None)

Read sim_telarray events from file.

sim_telarray files are read with eventio package.

Parameters:

input_files: list

List of sim_telarray output files (str of Path).

count_simulated_events(energy_range=None, core_max=None)

Determine number of simulated events within a certain energy range and core radius.

Use the simulated power law. This calculation assumes the simulated spectrum is given by a single power law.

Parameters:

energy_range: Tuple len 2

Max and min energy of energy range, e.g. energy_range=(100 * u.GeV, 10 * u.TeV).

core_max: astropy.Quantity distance

Maximum core radius for selecting showers, e.g. core_max=1000 * u.m.

Returns:

int

Number of simulated events.

count_triggered_events(energy_range=None, core_max=None)

Count number of triggered events within a certain energy range and core radius.

Parameters:

energy_range: Tuple with len 2

Max and min energy of energy range, e.g. energy_range=(100 * u.GeV, 10 * u.TeV).

core_max: astropy.Quantity distance

Maximum core radius for selecting showers, e.g. core_max=1000 * u.m.

Returns:

int

Number of triggered events.

load_header_and_summary()

Read MC header from sim_telarray files and store it into _mc_header.

Also fills summary_events with energy and core radius of triggered events.

load_input_files(files=None)

Store list of input files into input_files attribute.

Parameters:

files: list

List of sim_telarray files (str or Path).

property number_of_files

Return number of files loaded.

Returns:

int

Number of files loaded.

select_events(energy_range=None, core_max=None)

Select sim_telarray events within a certain energy range and core radius.

Parameters:

energy_range: Tuple len 2

Max and min energy of energy range, e.g. energy_range=(100 * u.GeV, 10 * u.TeV).

core_max: astropy.Quantity distance

Maximum core radius for selecting showers, e.g. core_max=1000 * u.m.

Returns:

list

List of events.

simtel_io_histogram

Reads the content of either a single histogram (.hdata) or a single simtel_array output (.simtel).

Files can be zst compressed.

exception simtel.simtel_io_histogram.HistogramIdNotFoundError

Exception for histogram ID not found.

exception simtel.simtel_io_histogram.InconsistentHistogramFormatError

Exception for bad histogram format.

class simtel.simtel_io_histogram.SimtelIOHistogram(histogram_file, area_from_distribution=False, energy_range=None, view_cone=None)

Reads and generates histograms from sim_telarray output.

Read the content of either a single histogram (.hdata, or .hdata.zst) or a single simtel_array output file (.simtel or .simtel.zst).

Parameters:

histogram_file: str

The histogram (.hdata.zst) or simtel_array (.simtel.zst) file.

area_from_distribution: bool

If true, the area thrown (the area in which the simulated events are distributed) in the trigger rate calculation is estimated based on the event distribution. The expected shape of the distribution of events as function of the core distance is triangular up to the maximum distance. The weighted mean radius of the triangular distribution is 2/3 times the upper edge. Therefore, when using the area_from_distribution flag, the mean distance times 3/2, returns just the position of the upper edge in the triangle distribution with little impact of the binning and little dependence on the scatter area defined in the simulation. This is special useful when calculating trigger rate for individual telescopes. If false, the area thrown is estimated based on the maximum distance as given in the simulation configuration.

energy_range: list

The energy range used in the simulation. It must be passed as a list of floats and the energy must be in TeV. This argument is only needed and used if histogram_file is a .hdata file, in which case the energy range cannot be retrieved directly from the file.

view_cone: list

The view cone used in the simulation. It must be passed as a list of floats and the view cone must be in deg. This argument is only needed and used if histogram_file is a .hdata file, in which case the view cone cannot be retrieved directly from the file.

compute_system_trigger_rate(events_histogram=None, triggered_events_histogram=None)

Compute the system trigger rate and its uncertainty, which are saved as class attributes.

If events_histogram and triggered_events_histogram are passed, they are used to calculate the trigger rate and trigger rate uncertainty, instead of the histograms from the file. This is specially useful when calculating the trigger rate for stacked files, in which case one can pass the histograms resulted from stacking the files to this function. Default is filling from the file.

Parameters:

events_histogram:

A dictionary with “data” corresponding to a 2D histogram (core distance x energy) for the simulated events.

triggered_events_histogram:

A dictionary with “data” corresponding to a 2D histogram (core distance x energy) for the triggered events.

property config

Return information about the input parameters for the simulation.

Returns:

dict:

dictionary with information about the simulation (pyeventio MCRunHeader object).

estimate_observation_time(stacked_num_simulated_events=None)

Estimates the observation time corresponding to the simulated number of events.

It uses the CTAO reference cosmic-ray spectra, the total number of particles simulated, and other information from the simulation configuration self.config. If stacked_num_simulated_events is given, the observation time is estimated from it instead of from the simulation configuration (useful for the stacked trigger rate estimate).

Parameters:

stacked_num_simulated_events: int

total number of simulated events for the stacked dataset.

Returns:

astropy.Quantity[time]

Estimated observation time based on the total number of particles simulated.

estimate_trigger_rate_uncertainty(trigger_rate_estimate, num_simulated_events, num_triggered_events)

Estimate the trigger rate uncertainty.

The calculation is based on the number of simulated and triggered events. Poisson statistics are assumed. The uncertainty is calculated based on propagation of the individual uncertainties. If stacked_num_simulated_events is passed, the uncertainty is estimated based on it instead of based on the total number of trigger events from the simulation configuration (useful for the stacked trigger rate estimate).

Parameters:

trigger_rate_estimate: astropy.Quantity[1/time]

The already estimated the trigger rate.

num_simulated_events: int

Total number of simulated events.

num_triggered_events: int

Total number of triggered events.

Returns:

astropy.Quantity[1/time]

Uncertainty in the trigger rate estimate.

fill_event_histogram_dicts()

Get data from the total simulated event and the triggered event histograms.

Returns:

dict:

Information about the histograms with simulated events.

dict:

Information about the histograms with triggered events.

Raises:

HistogramIdNotFoundError:

if histogram ids not found. Problem with the file.

get_histogram_type_title(histogram_index)

Return the title of the histogram with index histogram_index.

Parameters:

histogram_index: int

Histogram index.

Returns:

str

Histogram title.

get_particle_distribution_function(label='reference')

Get the particle distribution function.

This depends on whether one wants the reference CR distribution or the distribution used in the simulation. This is controlled by label. By using label=”reference”, one gets the distribution function according to a pre-defined CR distribution, while by using label=”simulation”, the spectral index of the distribution function from the simulation is used. Naturally, label=”simulation” only works when the input file is a .simtel file and not a .hdata file.

Parameters:

label: str

label defining which distribution function. Possible values are: “reference”, or “simulation”.

Returns:

ctao_cr_spectra.spectral.PowerLaw

The function describing the spectral distribution.

property number_of_histogram_types

Return number of histograms.

print_info(mode=None)

Print information on the geometry and input parameters.

Returns:

dict:

Dictionary with the information, e.g., view angle, energy range, etc.

produce_trigger_meta_data()

Produce the meta data to include in the tabulated form of the trigger rate per energy bin.

It shows some information from the input file (simtel_array file) and the final estimate system trigger rate.

Returns:

dict:

dictionary with the metadata.

property solid_angle

Solid angle corresponding to the view cone.

Returns:

astropy.Quantity[u.sr]:

Solid angle corresponding to the view cone.

property total_area

Total area covered by the simulated events (original CORSIKA CSCAT), i.e., area thrown.

Returns:

astropy.Quantity[area]:

Total area covered on the ground covered by the simulation.

property total_num_simulated_events

Return the total number of simulated events the histograms.

Returns:

int:

total number of simulated events.

property total_num_triggered_events

Returns the total number of triggered events.

Please note that this value is not supposed to match the trigger rate x estimated observation time, as the simulation is optimized for computational time and the energy distribution assumed is not necessarily the reference cosmic-ray spectra.

Returns:

int:

total number of simulated events.

trigger_info_in_table()

Provide the trigger rate per energy bin in tabulated form.

Returns:

astropy.QTable:

The QTable instance with the trigger rate per energy bin.

simtel_io_histograms

Reads the content of multiples files from sim_telarray.

Reads the content of either multiple histogram (.hdata, or .hdata.zst) or simtel_array output files (.simtel or .simtel.zst). The module is built on top of the simtel_io_histogram module and uses its class (SimtelIOHistogram) to read the individual files.

class simtel.simtel_io_histograms.SimtelIOHistograms(histogram_files, test=False, area_from_distribution=False, energy_range=None, view_cone=None)

Read the content of either multiple histogram (.hdata, or .hdata.zst) or simtel_array files.

Allow both the .hdata.zst histogram and the .simtel.zst output file type. It uses the SimtelIOHistogram class to deal with individual files. Histogram files are ultimately handled by using eventio library.

Parameters:

histogram_files: list

List of sim_telarray histogram files (str of Path).

test: bool

If True, only a fraction of the histograms will be processed, leading to a much shorter runtime.

area_from_distribution: bool

If true, the area thrown (the area in which the simulated events are distributed) in the trigger rate calculation is estimated based on the event distribution. The expected shape of the distribution of events as function of the core distance is triangular up to the maximum distance. The weighted mean radius of the triangular distribution is 2/3 times the upper edge. Therefore, when using the area_from_distribution flag, the mean distance times 3/2, returns just the position of the upper edge in the triangle distribution with little impact of the binning and little dependence on the scatter area defined in the simulation. This is special useful when calculating trigger rate for individual telescopes. If false, the area thrown is estimated based on the maximum distance as given in the simulation configuration.

energy_range: list

The energy range used in the simulation. It must be passed as a list of floats and the energy must be in TeV (as in the CORSIKA configuration). This argument is only needed and used if histogram_file is a .hdata file, in which case the energy range cannot be retrieved directly from the file.

view_cone: list

The view cone used in the simulation. It must be passed as a list of floats and the view cone must be in deg (as in the CORSIKA configuration). This argument is only needed and used if histogram_file is a .hdata file, in which case the view cone cannot be retrieved directly from the file.

calculate_trigger_rates(print_info=False, stack_files=False)

Calculate the triggered and simulated event rate considering the histograms in each file.

It returns also a list with the tables where the energy dependent trigger rate for each file can be found.

Parameters:

print_info: bool

if True, prints out the information about the histograms such as energy range, area, etc.

stack_files: bool

if True, stack the histograms from the different files into single histograms. Useful to increase event statistics when calculating the trigger rate.

Returns:

sim_event_rates: list of astropy.Quantity[1/time]

The simulated event rates.

triggered_event_rates: list of astropy.Quantity[1/time]

The triggered event rates.

triggered_event_rate_uncertainties: list of astropy.Quantity[1/time]

The uncertainties in the triggered event rates.

trigger_rate_in_tables: list of astropy.QTable

The energy dependent trigger rates. Only filled if stack_files is False.

property combined_hists

Combine histograms of same type of histogram.

Histograms are read from various lists into a single histogram list.

export_histograms(hdf5_file_name, overwrite=False)

Export the histograms to hdf5 files.

Parameters:

hdf5_file_name: str

Name of the file to be saved with the hdf5 tables.

overwrite: bool

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

get_stacked_num_events()

Return stacked number of simulated events and triggered events.

Returns:

int:

total number of simulated events for the stacked dataset.

int:

total number of triggered events for the stacked dataset.

property list_of_histograms

Returns a list with the histograms for each file.

Returns:

list:

List of histograms.

property number_of_files

Returns number of histograms.

plot_one_histogram(histogram_index, ax)

Plot a single histogram referent to the index histogram_index.

Parameters:

histogram_index: int

Index of the histogram to be plotted.

ax: matplotlib.axes.Axes

Instance of matplotlib.axes.Axes in which to plot the histogram.

simulator_array

Simulation runner for array simulations.

class simtel.simulator_array.SimulatorArray(corsika_config, simtel_path, label=None, use_multipipe=False, sim_telarray_seeds=None)

SimulatorArray is the interface with sim_telarray to perform array simulations.

Parameters:

corsika_config_data: CorsikaConfig

CORSIKA configuration.

simtel_path: str or Path

Location of source of the sim_telarray/CORSIKA package.

label: str

Instance label.

use_multipipe: bool

Use multipipe to run CORSIKA and sim_telarray.

static get_power_law_for_sim_telarray_histograms(primary)

Get the power law index for sim_telarray.

Events will be histogrammed in sim_telarray with a weight according to the difference between this exponent and the one used for the shower simulations.

Parameters:

primary: str

Primary particle.

Returns:

float

Power law index.

simulator_camera_efficiency

Simulation runner for camera efficiency calculations.

class simtel.simulator_camera_efficiency.SimulatorCameraEfficiency(telescope_model, label=None, simtel_path=None, file_simtel=None, file_log=None, zenith_angle=None, nsb_spectrum=None, skip_correction_to_nsb_spectrum=False)

Interface with the testeff tool of sim_telarray to perform camera efficiency simulations.

Parameters:

telescope_model: str

Instance of TelescopeModel class.

label: str

Instance label. Important for output file naming.

simtel_path: str or Path

Location of sim_telarray installation.

file_simtel: str or Path

Location of the sim_telarray testeff tool output file.

zenith_angle: float

Zenith angle given in the config to CameraEfficiency.

nsb_spectrum: str or Path

Path to the nsb spectrum file.

property nsb_spectrum

nsb_spectrum property.

simulator_light_emission

Simulation using the light emission package for calibration.

class simtel.simulator_light_emission.SimulatorLightEmission(telescope_model, calibration_model, site_model, default_le_config, le_application, simtel_path, light_source_type, label=None, test=False)

Interface with sim_telarray to perform light emission package simulations.

The light emission package is used to simulate a artificial light source, used for calibration.

The angle and pointing vector calculations use the convention north (x) towards east (-y).

Parameters:

telescope_model:

Instance of the TelescopeModel class.

calibration_model:

CalibrationModel instance to define calibration device.

site_model:

SiteModel instance to define the site specific parameters.

default_le_config: dict

defines parameters for running the sim_telarray light emission application.

le_application: str

Name of the application. Default sim_telarray application running the sim_telarray LightEmission package is xyzls.

simtel_path: str or Path

Location of sim_telarray installation.

light_source_type: str

The light source type.

label: str

Label for output directory.

config_data: dict

Dict containing the configurable parameters.

config_file: str or Path

Path of the yaml file containing the configurable parameters.

test: bool

Test flag.

calibration_pointing_direction()

Calculate the pointing of the calibration device towards the telescope.

Returns:

list

The pointing vector from the calibration device to the telescope.

static light_emission_default_configuration()

Get default light emission configuration.

Returns:

dict

Default configuration light emission.

prepare_script(generate_postscript=False, **kwargs)

Build and return bash run script containing the light-emission command.

Parameters:

plot: bool

If output should be plotted.

generate_postscript: bool

If postscript should be generated with read_cta.

Returns:

Path

Full path of the run script.

telescope_calibration_device_distance()

Calculate the distance between the telescope and the calibration device.

Returns:

astropy Quantity

The distance between the telescope and the calibration device.

simulator_ray_tracing

Simulation runner for ray tracing simulations.

class simtel.simulator_ray_tracing.SimulatorRayTracing(telescope_model, label=None, simtel_path=None, config_data=None, force_simulate=False, test=False)

Perform ray tracing simulations with sim_telarray.

Parameters:

telescope_model: TelescopeModel

telescope model

label: str

label used for output file naming.

simtel_path: str or Path

Location of sim_telarray installation.

config_data: namedtuple

namedtuple containing the configurable parameters as values (expected units in brackets): zenith_angle (deg), off_axis_angle (deg), source_distance (km), single_mirror_mode, use_random_focal_length, mirror_numbers.

force_simulate: bool

Remove existing files and force re-running of the ray-tracing simulation.