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)[source]#
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()[source]#
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.
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)[source]#
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
Version of the model (ex. prod5).
- 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)[source]#
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)[source]#
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)[source]#
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[source]#
Exception for inconsistent input file.
- class simtel.simtel_io_events.SimtelIOEvents(input_files=None)[source]#
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)[source]#
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)[source]#
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()[source]#
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)[source]#
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)[source]#
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#
This module reads the content of either a single histogram (.hdata, or .hdata.zst) or a single simtel_array output file (.simtel or .simtel.zst).
- exception simtel.simtel_io_histogram.HistogramIdNotFoundError[source]#
Exception for histogram ID not found.
- exception simtel.simtel_io_histogram.InconsistentHistogramFormatError[source]#
Exception for bad histogram format.
- class simtel.simtel_io_histogram.SimtelIOHistogram(histogram_file, area_from_distribution=False)[source]#
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_distributionflag, 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.
- compute_system_trigger_rate(events_histogram=None, triggered_events_histogram=None)[source]#
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).
- property energy_range#
Energy range used in the simulation.
- Returns:
- list:
Energy range used in the simulation [min, max]
- estimate_observation_time(stacked_num_simulated_events=None)[source]#
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)[source]#
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()[source]#
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)[source]#
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')[source]#
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.
- 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)[source]#
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()[source]#
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()[source]#
Provide the trigger rate per energy bin in tabulated form.
- Returns:
- astropy.QTable:
The QTable instance with the trigger rate per energy bin.
- property view_cone#
View cone used in the simulation.
- Returns:
- list:
view cone used in the simulation [min, max]
simtel_io_histograms#
This module 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)[source]#
Read the content of either multiple histogram (.hdata, or .hdata.zst) or simtel_array output 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_distributionflag, 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.
- calculate_trigger_rates(print_info=False, stack_files=False)[source]#
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)[source]#
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()[source]#
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.
simtel_runner#
Base class for running sim_telarray simulations.
- exception simtel.simtel_runner.SimtelExecutionError[source]#
Exception for simtel_array execution error.
- class simtel.simtel_runner.SimtelRunner(simtel_source_path, label=None)[source]#
SimtelRunner is the base class of the sim_telarray interfaces.
- Parameters:
- simtel_source_path: str or Path
Location of sim_telarray installation.
- label: str
Instance label. Important for output file naming.
- prepare_run_script(test=False, input_file=None, run_number=None, extra_commands=None)[source]#
Build and return the full path of the bash run script containing the sim_telarray command.
- Parameters:
- test: bool
Test flag for faster execution.
- input_file: str or Path
Full path of the input CORSIKA file.
- run_number: int
Run number.
- extra_commands: str
Additional commands for running simulations given in config.yml.
- Returns:
- Path
Full path of the run script.
- run(test=False, force=False, input_file=None, run_number=None)[source]#
Make run command and run sim_telarray.
- Parameters:
- test: bool
If True, make simulations faster.
- force: bool
If True, remove possible existing output files and run again.
- input_file: str or Path
Full path of the input CORSIKA file.
- run_number: int
Run number.
simulator_array#
Simulation runner for array simulations.
- class simtel.simulator_array.SimulatorArray(array_model, label=None, simtel_source_path=None, config_data=None, config_file=None)[source]#
SimulatorArray is the interface with sim_telarray to perform array simulations.
- Configurable parameters:
- simtel_data_directory:
len: 1 default: null unit: null
- primary:
len: 1 unit: null
- zenith_angle:
len: 1 unit: deg default: 20 deg
- azimuth_angle:
len: 1 unit: deg default: 0 deg
- Parameters:
- array_model: str
Instance of ArrayModel class.
- label: str
Instance label. Important for output file naming.
- simtel_source_path: str or Path
Location of sim_telarray installation.
- config_data: dict
Dict containing the configurable parameters.
- config_file: str or Path
Path of the yaml file containing the configurable parameters.
- get_file_name(file_type, **kwargs)[source]#
Get a sim_telarray style file name for various file types.
- Parameters:
- file_type: str
The type of file (determines the file suffix). Choices are log, histogram, output or sub_log.
- kwargs: dict
- The dictionary must include the following parameters (unless listed as optional):
- run: int
Run number.
- primary: str
Primary particle (e.g gamma, proton etc).
- zenith: float
Zenith angle (deg).
- azimuth: float
Azimuth angle (deg).
- site: str
Site name (usually North/South or Paranal/LaPalma).
- array_name: str
Array name.
- label: str
Instance label (optional).
- mode: str
out or err (optional, relevant only for sub_log).
- Returns:
- str
File name with full path.
- Raises:
- ValueError
If file_type is unknown.
- get_info_for_file_name(run_number)[source]#
Get a dictionary with the info necessary for building the sim_telarray file names.
- Returns:
- dict
Dictionary with the keys necessary for building the sim_telarray file names.
simulator_camera_efficiency#
Simulation runner for camera efficiency calculations.
- class simtel.simulator_camera_efficiency.SimulatorCameraEfficiency(telescope_model, label=None, simtel_source_path=None, file_simtel=None, file_log=None, zenith_angle=None, nsb_spectrum=None)[source]#
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_source_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_ray_tracing#
Simulation runner for ray tracing simulations.
- class simtel.simulator_ray_tracing.SimulatorRayTracing(telescope_model, label=None, simtel_source_path=None, config_data=None, config_file=None, force_simulate=False, test=False)[source]#
SimulatorRayTracing is the interface with sim_telarray to perform ray tracing simulations.
- Configurable parameters:
- zenith_angle:
len: 1 unit: deg default: 20 deg
- off_axis_angle:
len: 1 unit: deg default: 0 deg
- source_distance:
len: 1 unit: km default: 10 km
- single_mirror_mode:
len: 1 default: False
- use_random_focal_length:
len: 1 default: False
- mirror_numbers:
len: 1 default: 1
- Parameters:
- telescope_model: str
Instance of TelescopeModel class.
- label: str
Instance label. Important for output file naming.
- simtel_source_path: str or Path
Location of sim_telarray installation.
- config_data: dict
Dict containing the configurable parameters.
- config_file: str or Path
Path of the yaml file containing the configurable parameters.
- force_simulate: bool
Remove existing files and force re-running of the ray-tracing simulation.