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)[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)’ | 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()[source]#

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)[source]#

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)[source]#

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, simtel_path=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: 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)[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.
additional_metadata: dict: Dictionary with additional metadata to include.

write_dummy_telescope_configuration_file(parameters, config_file_path, telescope_name)[source]#

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)[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, telescope_name=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
telescope_name: str: Name of the telescope (use self._telescope_model_name if None)

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)[source]#

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>)[source]#: Container for shower event data.

class simtel.simtel_io_event_reader.SimtelIOEventDataReader(event_data_file, telescope_list=None)[source]#

Read reduced MC data set stored in astropy tables.

get_reduced_simulation_file_info(simulation_file_info)[source]#

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)[source]#

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)[source]#

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.

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>)[source]#: 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)[source]#

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()[source]#: Create astropy tables from collected data.

get_nsb_level_from_sim_telarray_metadata(file)[source]#

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()[source]#

Process input files and return tables.

Returns:

list: List of astropy tables containing processed data.

class simtel.simtel_io_event_writer.TableSchemas[source]#: 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)[source]#

Generate and fill histograms for shower and triggered events.

Event data is read from the reduced MC event data file.

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

property core_distance_bins#: Return bins for the core distance histogram.

property energy_bins#: Return bins for the energy histogram.

fill()[source]#

Fill histograms with event data.

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

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

plot_data(output_path=None, limits=None, rebin_factor=2)[source]#

Histogram plotting.

Parameters:

output_path: Path or str, optional: Directory to save plots. If None, plots will be displayed.
limits: dict, optional: Dictionary containing limits for plotting. Keys can include: - “upper_radius_limit”: Upper limit for core distance - “lower_energy_limit”: Lower limit for energy - “viewcone_radius”: Radius for the viewcone
rebin_factor: int, optional: Factor by which to reduce the number of bins in 2D histograms for rebinned plots. Default is 2 (merge every 2 bins). Set to 0 or 1 to disable rebinning.

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)[source]#

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)[source]#

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')[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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.

make_run_command_for_calibration_simulations(run_number=None, input_file=None, calibration_runner_args=None)[source]#

Build and return the command to run sim_telarray for calibration simulations.

Parameters:

calibration_runner_args: dict: Dictionary with calibration runner arguments.
input_file: str: Full path of the input CORSIKA file
run_number: int (optional): run number

Returns:

str: Command to run sim_telarray for pedestal simulations.

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)[source]#

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#

Simulation using the light emission package for calibration devices.

class simtel.simulator_light_emission.SimulatorLightEmission(*, telescope_model, calibration_model=None, flasher_model=None, site_model=None, light_emission_config=None, light_source_setup=None, simtel_path=None, light_source_type=None, label=None, test=False)[source]#

Interface with sim_telarray to perform light emission package simulations.

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

calculate_distance_telescope_calibration_device()[source]#: Calculate distance(s) between telescope and calibration device.

calibration_pointing_direction()[source]#

Calculate the pointing of the calibration device towards the telescope.

Returns:

list: The pointing vector from the calibration device to the telescope.

distance_list(arg)[source]#

Convert distance list to astropy quantities.

Parameters:

arg: list: List of distances.

Returns:

values: list: List of distances as astropy quantities.

static flasher_default_configuration()[source]#

Get default flasher configuration.

Returns:

dict: Default configuration for flasher devices.

static light_emission_default_configuration()[source]#

Get default light emission configuration.

Returns:

dict: Default configuration light emission.

prepare_script()[source]#

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

Returns:

Path: Full path of the run script.

run_simulation() → Path[source]#: Run the light emission simulation and return the output simtel file path.

simulate_layout_positions(args_dict)[source]#: Simulate light emission for layout positions and return output files list.

simulate_variable_distances(args_dict)[source]#: Simulate light emission for variable distances and return output files list.

update_light_emission_config(key: str, value)[source]#

Update the light emission configuration.

Parameters:

keystr: The key in the configuration to update.
valueAny: The new value to set for the key.

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)[source]#

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.

sim_telarray#

simtel_config_reader#

simtel_config_writer#

simtel_table_reader#

simtel_io_event_reader#

simtel_io_event_writer#

simtel_io_event_histograms#

simtel_io_metadata#

simtel_io_file_info#

simulator_array#

simulator_camera_efficiency#

simulator_light_emission#

simulator_ray_tracing#

This Page