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=None, simtel_config_file=None, simtel_telescope_name=None, 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)’ | sed ‘s/^(@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 sim_telarray with schema.

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

extract_value_from_sim_telarray_column(column, dtype=None, n_dim=1, default=None, is_limit=False)

Extract value(s) from sim_telarray configuration file columns.

This function is fine-tuned to the sim_telarray configuration output.

Parameters:

column: list

List of strings to extract value from.

dtype: str

Data type to convert value to.

n_dim: int

Length of array to be returned.

default: object

Default value to extend array to required length.

Returns:

object, int

Values extracted from column. Of object is a list of array, return length of array.

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.simtel_config_reader.get_list_of_simtel_parameters(simtel_config_file)

Return list of sim_telarray parameters found in sim_telarray configuration file.

Parameters:

simtel_config_file: str

File name for sim_telarray configuration

Returns:

list

List of parameters found in sim_telarray configuration file.

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, telescope_design_model=None, label=None, simtel_path=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.

simtel_path: str or Path

Path to the sim_telarray installation directory.

write_array_config_file(config_file_path, telescope_model, site_model, additional_metadata=None)

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.

additional_metadata: dict

Dictionary with additional metadata to include.

write_dummy_telescope_configuration_file(parameters, config_file_path, telescope_name)

Write ‘dummy’ telescope configuration file used as zeroth telescope in sim_telarray.

Replaces key telescope configuration values with dummy values.

Parameters:

parameters: dict

Telescope parameters used as template.

config_file_path: str or Path

Path of the dummy configuration file to write on.

telescope_name: str

Name of the telescope.

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, telescope_name=None, telescope_design_model=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

telescope_name: str

Name of the telescope (use self._telescope_model_name if None)

telescope_design_model: str

Telescope design model.

simtel.simtel_config_writer.sim_telarray_random_seeds(seed, number)

Generate random seeds to be used in sim_telarray.

Parameters:

seed: int

Seed for the random number generator.

number: int

Number of random seeds to generate.

Returns:

list

List of random seeds.

simtel_table_reader

Read tabular data in sim_telarray format and return as astropy table.

simtel.simtel_table_reader.read_simtel_table(parameter_name, file_path)

Read sim_telarray table file for a given parameter.

Parameters:

parameter_name: str

Model parameter name.

file_path: Path

Name (full path) of the sim_telarray table file.

Returns:

Table

Astropy table.

simtel_io_event_reader

Read reduced datasets in form of astropy tables from file.

class simtel.simtel_io_event_reader.ShowerEventData(shower_id: list[~numpy.uint32] = <factory>, event_id: list[~numpy.uint32] = <factory>, file_id: list[~numpy.uint32] = <factory>, simulated_energy: list[~numpy.float64] = <factory>, x_core: list[~numpy.float64] = <factory>, y_core: list[~numpy.float64] = <factory>, shower_azimuth: list[~numpy.float64] = <factory>, shower_altitude: list[~numpy.float64] = <factory>, area_weight: list[~numpy.float64] = <factory>, x_core_shower: list[~numpy.float64] = <factory>, y_core_shower: list[~numpy.float64] = <factory>, core_distance_shower: list[~numpy.float64] = <factory>, angular_distance: list[float] = <factory>)

Container for shower event data.

class simtel.simtel_io_event_reader.SimtelIOEventDataReader(event_data_file, telescope_list=None)

Read reduced MC data set stored in astropy tables.

get_reduced_simulation_file_info(simulation_file_info)

Return reduced simulation file info assuming single-valued parameters.

Applies rounding and uniqueness functions extract representative values for zenith, azimuth, and NSB level. Assumes all files share identical simulation parameters except for file names. Returns particle name instead of ID.

Logs a warning if multiple unique values are found.

Parameters:

simulation_file_infoastropy.table.Table

Dictionary containing simulation file info.

Returns:

dict

Dictionary containing the reduced simulation file info.

read_event_data(event_data_file, table_name_map=None)

Read event data and file info tables from file and apply transformations.

Allows to map tables names to their actual names in the file (e.g., “SHOWER” to “SHOWER_1”).

Parameters:

event_data_filestr

Path to the event data file.

table_name_mapdict, optional

Mapping of table names to their actual names in the file. Defaults to using the standard names “SHOWERS”, “TRIGGERS”, and “FILE_INFO”.

Returns:

tuple

A tuple with file info table, shower, triggered shower, and triggered event data.

read_table_list(event_data_file)

Read available tables from the event data file.

Rearrange dictionary with tables names into a list of dictionaries under the assumption that the file contains the tables “SHOWERS”, “TRIGGERS”, and “FILE_INFO”.

Parameters:

event_data_filestr

Path to the event data file.

Returns:

list

List of dictionaries containing the data from the tables.

scatter_area(core_scatter_min, core_scatter_max)

Calculate the scatter area of the core.

Parameters:

core_scatter_minastropy.units.Quantity

Minimum core scatter radius.

core_scatter_maxastropy.units.Quantity

Maximum core scatter radius.

Returns:

astropy.units.Quantity

Scatter area.

class simtel.simtel_io_event_reader.TriggeredEventData(shower_id: list[~numpy.uint32] = <factory>, event_id: list[~numpy.uint32] = <factory>, file_id: list[~numpy.uint32] = <factory>, array_altitude: list[float] = <factory>, array_azimuth: list[float] = <factory>, telescope_list: list[~numpy.ndarray] = <factory>, angular_distance: list[float] = <factory>)

Container for triggered event data.

simtel_io_event_writer

Generate a reduced dataset from sim_telarray output files using astropy tables.

class simtel.simtel_io_event_writer.SimtelIOEventDataWriter(input_files, max_files=100)

Process sim_telarray events and write tables to file.

Extracts essential information from sim_telarray output files:

• Shower parameters (energy, core location, direction)

• Trigger patterns

• Telescope pointing

Attributes:

input_fileslist

List of input file paths to process.

max_filesint, optional

Maximum number of files to process.

create_tables()

Create astropy tables from collected data.

get_nsb_level_from_sim_telarray_metadata(file)

Return NSB level from sim_telarray metadata.

Falls back to preliminary NSB level if not found.

Parameters:

filePath

Path to the sim_telarray file.

Returns:

float

NSB level.

process_files()

Process input files and return tables.

Returns:

list

List of astropy tables containing processed data.

class simtel.simtel_io_event_writer.TableSchemas

Define schemas for output tables with units.

simtel_io_event_histograms

Histograms for shower and triggered events.

class simtel.simtel_io_event_histograms.SimtelIOEventHistograms(event_data_file, array_name=None, telescope_list=None)

Generate and fill histograms for shower and triggered events.

Event data is read from the reduced MC event data file. Calculate cumulative and relative (efficiency) distributions.

Parameters:

event_data_filestr

Path to the event-data file.

array_namestr, optional

Name of the telescope array configuration (default is None).

telescope_listlist, optional

List of telescope IDs to filter the events (default is None).

calculate_cumulative_data()

Calculate cumulative distributions for triggered histograms.

Returns:

dict

Dictionary containing the cumulative histograms.

calculate_efficiency_data()

Calculate efficiency histograms (triggered divided by simulated).

Assumes that for each histogram with simulated events, there is a corresponding histogram with triggered events.

Returns:

dict

Dictionary containing the efficiency histograms.

property core_distance_bins

Return bins for the core distance histogram.

property energy_bins

Return bins for the energy histogram.

fill()

Fill histograms with event data.

Involves looping over all event data, and therefore is the slowest part of the histogram module. Adds the histograms to the histogram dictionary.

Assume that all event data files are generated with similar configurations (self.file_info contains the file info of the last file).

get_histogram_definition(event_data_column=None, event_data=None, histogram=None, bin_edges=None, title=None, axis_titles=None, suffix=None, is_1d=True, plot_scales=None)

Return a single histogram definition.

print_summary()

Print a summary of the histogram statistics.

Total number of events is retrieved from the ‘energy’ histograms.

static rebin_2d_histogram(hist, x_bins, y_bins, rebin_factor=2)

Rebin a 2D histogram by merging neighboring bins along the energy dimension (y-axis) only.

Parameters:

histnp.ndarray

Original 2D histogram data

x_binsnp.ndarray

Original x-axis bin edges (preserved)

y_binsnp.ndarray

Original y-axis (energy) bin edges

rebin_factorint, optional

Factor by which to reduce the number of bins in the energy dimension Default is 2 (merge every 2 bins)

Returns:

tuple

(re-binned_hist, x_bins, re-binned_y_bins)

property view_cone_bins

Return bins for the viewcone histogram.

simtel_io_metadata

Read metadata from sim_telarray files.

simtel.simtel_io_metadata.get_sim_telarray_telescope_id(telescope_name, file)

Return the telescope ID for a given telescope name in a sim_telarray file.

Translates e.g. ‘LSTN-01’ to the corresponding telescope ID.

Parameters:

telescope_name: str

Name of the telescope.

file: str

Path to the sim_telarray file.

Returns:

int, None

Telescope ID. Returns None if not found.

simtel.simtel_io_metadata.get_sim_telarray_telescope_id_to_telescope_name_mapping(file)

Return a mapping of telescope IDs to telescope names from a sim_telarray file.

Parameters:

file: str

Path to the sim_telarray file.

Returns:

dict

Dictionary mapping telescope IDs to telescope names.

simtel.simtel_io_metadata.read_sim_telarray_metadata(file, encoding='utf8')

Return global and per-telescope metadata from sim_telarray file.

Cached to avoid re-reading the file multiple times.

Parameters:

file: str

Path to the sim_telarray file.

encoding: str

Encoding to use for decoding metadata. Default is ‘utf8’.

Returns:

global_meta: dict

Global metadata dictionary.

telescope_meta: dict

Dictionary of telescope metadata, keyed by telescope ID.

simtel_io_file_info

Read file info and run headers from sim_telarray files.

simtel.simtel_io_file_info.get_corsika_run_header(file)

Return the CORSIKA run header information from a sim_telarray file.

Reads both RunHeader and MCRunHeader object from file and returns a merged dictionary. Adds primary id from the first event.

Parameters:

file: str

Path to the sim_telarray file.

Returns:

dict, None

CORSIKA run header. Returns None if not found.

simtel.simtel_io_file_info.get_corsika_run_number(file)

Return the CORSIKA run number from a sim_telarray file.

Parameters:

file: str

Path to the sim_telarray file.

Returns:

int, None

CORSIKA run number. Returns None if not found.

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, calibration_config=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.

sim_telarray_seeds: dict

Dictionary with configuration for sim_telarray random instrument setup.

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.

make_run_command(run_number=None, input_file=None, weak_pointing=None)

Build and return the command to run sim_telarray.

Parameters:

input_file: str

Full path of the input CORSIKA file

run_number: int (optional)

run number

weak_pointing: bool (optional)

Specify weak pointing option for sim_telarray.

Returns:

str

Command to run sim_telarray.

simulator_camera_efficiency

Simulation runner for camera efficiency calculations.

class simtel.simulator_camera_efficiency.SimulatorCameraEfficiency(telescope_model, site_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: TelescopeModel

Instance of TelescopeModel class.

site_model: SiteModel

Instance of SiteModel 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.

skip_correction_to_nsb_spectrum: bool

If True, skip the correction to the original altitude where the NSB spectrum was derived.

property nsb_spectrum

nsb_spectrum property.

simulator_light_emission

Light emission simulation (e.g. illuminators or flashers).

class simtel.simulator_light_emission.SimulatorLightEmission(light_emission_config, db_config=None, label=None)

Light emission simulation (e.g. illuminators or flashers).

Uses the sim_telarray LightEmission package to simulate the light emission.

Parameters:

light_emission_configdict, optional

Configuration for the light emission (e.g. number of events, model names)

labelstr, optional

Label for the simulation

calculate_distance_focal_plane_calibration_device()

Calculate distance between focal plane and calibration device.

For flasher-type light sources. Flasher position is given in mirror coordinates, with positive z pointing towards the camera, so the distance is focal_length - flasher_z.

Returns:

astropy.units.Quantity

Distance between calibration device and focal plane.

prepare_script()

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

Returns:

Path

Full path of the run script.

simulate()

Simulate light emission.

Returns:

Path

The output simtel file path.

simulator_ray_tracing

Simulation runner for ray tracing simulations.

class simtel.simulator_ray_tracing.SimulatorRayTracing(telescope_model, site_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

site_model: SiteModel

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