MC Model

MC Model#

The array of imaging atmospheric Cherenkov telescopes is abstracted in the simulation model and divided into the following components:

[telescope_model] representing a telescope. Defined by its telescope name, allowing to read model parameters from the databases using this name.
sub-elements of the telescope represented by the modules [mirrors] and [camera]
an array of telescopes (especially the telescope arrangement) represented by [array_model].

array_model#

Definition of the ArrayModel class.

class model.array_model.ArrayModel(mongo_db_config, model_version, label=None, site=None, layout_name=None, array_elements=None)[source]#

Representation of an observatory consisting of site, telescopes, and further devices.

Parameters:

mongo_db_config: dict: MongoDB configuration.
model_version: str: Model version.
label: str: Instance label. Used for output file naming.
site: str: Site name.
layout_name: str: Layout name.
array_elements: str, Path, list: Array element definitions (list of array element or path to file with the array element positions).

export_all_simtel_config_files()[source]#

Export sim_telarray config file for the array and for each individual telescope.

Config files are exported into the output model directory.

export_array_elements_as_table(coordinate_system='ground')[source]#

Export array elements positions to astropy table.

Parameters:

coordinate_system: str: Positions are exported in this coordinate system.

Returns:

astropy.table.QTable: Astropy table with the telescope layout information.

export_simtel_array_config_file()[source]#: Export sim_telarray configuration file for the array into the model directory.

export_simtel_telescope_config_files()[source]#: Export sim_telarray configuration files for all telescopes into the model directory.

get_config_directory()[source]#

Get the path of the array config directory for sim_telarray.

Returns:

Path: Path of the config directory path for sim_telarray.

get_config_file()[source]#

Return the path of the array config file for sim_telarray.

A new config file is produced if the file is not updated.

Returns:

Path: Path of the exported config file for sim_telarray.

property number_of_telescopes#

Return the number of telescopes.

Returns:

int: Number of telescopes.

print_telescope_list()[source]#: Print list of telescopes.

property site#

Return site.

Returns:

str: Site name.

calibration_model#

Definition and modeling of a calibration device.

class model.calibration_model.CalibrationModel(site, calibration_device_model_name, mongo_db_config, model_version, label=None)[source]#

CalibrationModel represents the MC model of an individual calibration device.

It provides functionality to read the required parameters from the DB.

Parameters:

site: str: Site name (e.g., South or North).
calibration_device_model_name: str: Calibration device model name (ex. ILLS-01, ILLN-01, …).
mongo_db_config: dict: MongoDB configuration.
model_version: str: Model version.
label: str: Instance label. Important for output file naming.

camera#

Definition and modeling of camera.

class model.camera.Camera(telescope_model_name, camera_config_file, focal_length)[source]#

Camera class, defining pixel layout.

This includes rotation, finding neighbor pixels, calculating FoV and plotting the camera.

Parameters:

telescope_model_name: string: As provided by the telescope model method TelescopeModel (e.g., LSTN-01)
camera_config_file: string: The sim_telarray file name.
focal_length: float: The focal length of the camera in (preferably the effective focal length), assumed to be in the same unit as the pixel positions in the camera_config_file, usually cm.

calc_fov()[source]#

Calculate the FOV of the camera in degrees, taking into account the focal length.

Returns:

fov: float: The FOV of the camera in the degrees.
average_edge_distance: float: The average edge distance of the camera.

Notes

The x,y pixel positions and focal length are assumed to have the same unit (usually cm)

get_camera_fill_factor()[source]#

Calculate the fill factor of the camera, defined as (pixel_diameter/pixel_spacing)**2.

Returns:

float: The camera fill factor.

get_edge_pixels(pixels=None, neighbours=None)[source]#

Get the indices of the edge pixels of the camera.

Parameters:

pixels: dict: The dictionary produced by the read_pixel_list method of this class.
neighbours: numpy.array_like: Array of neighbour indices in a list for each pixel.

Returns:

edge_pixel_indices: numpy.array_like: Array of edge pixel indices.

get_lightguide_efficiency_angle_file_name()[source]#

Get the file name of the light guide efficiency as a function of incidence angle.

Returns:

str: File name of the light guide efficiency as a function of incidence angle.

get_lightguide_efficiency_wavelength_file_name()[source]#

Get the file name of the light guide efficiency as a function of wavelength.

Returns:

str: File name of the light guide efficiency as a function of wavelength.

get_neighbour_pixels(pixels=None)[source]#

Get a list of neighbour pixels by calling calc_neighbour_pixels() when necessary.

The purpose of this function is to ensure the calculation occurs only once and only when necessary.

Parameters:

pixels: dict: The dictionary produced by the read_pixel_list method of this class.

Returns:

neighbours: numpy.array_like: Array of neighbour indices in a list for each pixel.

get_number_of_pixels()[source]#

Get the number of pixels in the camera (all pixels, including those defined as “off”.

Returns:

int: number of pixels.

get_pixel_active_solid_angle()[source]#

Get the active solid angle of a pixel in sr.

Returns:

float: active solid angle of a pixel in sr.

get_pixel_diameter()[source]#

Get pixel diameter contained in _pixels.

Returns:

float: Pixel diameter (usually in cm).

get_pixel_shape()[source]#

Get pixel shape code 1, 2 or 3.

Where 1 and 3 are hexagonal pixels, where one is rotated by 30 degrees with respect to the other. A square pixel is denoted as 2.

Returns:

int (1, 2 or 3): Pixel shape.

static initialize_pixel_dict()[source]#

Initialize the pixel dictionary with default values.

Returns:

dict: A dictionary with default pixel properties.

static process_line(line, pixels)[source]#

Process a line from the camera config file and update the pixel dictionary.

Parameters:

line: string: A line from the camera config file.
pixels: dict: The pixel dictionary to update.

static read_pixel_list(camera_config_file)[source]#

Read the pixel layout from the camera config file, assumed to be in a sim_telarray format.

Parameters:

camera_config_file: string: The sim_telarray file name.

Returns:

dict: pixels: A dictionary with the pixel positions, the camera rotation angle, the pixel shape, the pixel diameter, the pixel IDs and their “on” status.

Notes

The pixel shape can be hexagonal (denoted as 1 or 3) or a square (denoted as 2). The hexagonal shapes differ in their orientation, where those denoted as 3 are rotated clockwise by 30 degrees with respect to those denoted as 1.

static validate_pixels(pixels, camera_config_file)[source]#

Validate the pixel dictionary to ensure it has correct values.

Parameters:

pixels: dict: The pixel dictionary to validate.
camera_config_file: string: The sim_telarray file name for error messages.

Raises:

ValueError: If the pixel diameter or pixel shape is invalid.

mirrors#

Definition and modeling of mirror panels.

exception model.mirrors.InvalidMirrorListFileError[source]#: Exception for invalid mirror list file.

class model.mirrors.Mirrors(mirror_list_file, parameters=None)[source]#

Mirrors class, created from a mirror list file.

Parameters:

mirror_list_file: str: mirror list in sim_telarray or ecsv format (with panel focal length only).
parameters: dict: Dictionary of parameters from the database.

get_single_mirror_parameters(number)[source]#

Get parameters for a single mirror given by number.

Parameters:

number: int: Mirror number of desired parameters.

Returns:

(pos_x, pos_y, mirror_diameter, focal_length, shape_type): tuple of float: X, Y positions, mirror_diameter, focal length and shape_type.

plot_mirror_layout()[source]#: Plot the mirror layout (not implemented yet).

model_parameter#

Base class for simulation model parameters.

exception model.model_parameter.InvalidModelParameterError[source]#: Exception for invalid model parameter.

class model.model_parameter.ModelParameter(mongo_db_config, model_version, site=None, array_element_name=None, collection='telescopes', db=None, label=None)[source]#

Base class for simulation model parameters.

Provides methods to read and manipulate parameters from DB.

Parameters:

db: DatabaseHandler: Database handler.
model_version: str: Version of the model (ex. 5.0.0).
site: str: Site name (e.g., South or North).
array_element_name: str: Array element name (e.g., LSTN-01, LSTN-design, ILLN-01).
collection: str: instrument class (e.g. telescopes, calibration_devices) as stored under collection in the DB.
mongo_db_config: dict: MongoDB configuration.
label: str: Instance label. Important for output file naming.

change_multiple_parameters(**kwargs)[source]#

Change the value of multiple existing parameters in the model.

This function does not modify the DB, it affects only the current instance.

Parameters:

**kwargs: Parameters should be passed as parameter_name=value.

change_multiple_parameters_from_file(file_name)[source]#

Change values of multiple existing parameters in the model from a file.

This function does not modify the DB, it affects only the current instance. Experimental feature: insufficient validation of parameters.

Parameters:

file_name: str: File containing the parameters to be changed.

change_parameter(par_name, value)[source]#

Change the value of an existing parameter.

This function does not modify the DB, it affects only the current instance.

Parameters:

par_name: str: Name of the parameter.
value:: Value of the parameter.

Raises:

InvalidModelParameterError: If the parameter to be changed does not exist in this model.

property config_file_directory#: Directory for configure files. Configure, if necessary.

property config_file_path#: Path of the config file. Configure, if necessary.

property derived#: Load the derived values and export them if the class instance hasn’t done it yet.

export_config_file()[source]#: Export the config file used by sim_telarray.

export_model_files()[source]#: Export the model files into the config file directory.

export_nsb_spectrum_to_telescope_altitude_correction_file(model_directory)[source]#

Export the NSB spectrum to the telescope altitude correction file.

This method is needed because testeff corrects the NSB spectrum from the original altitude used in the Benn & Ellison model to the telescope altitude. This is done internally in testeff, but the NSB spectrum is not written out to the model directory. This method allows to export it explicitly.

Parameters:

model_directory: Path: Model directory to export the file to.

export_parameter_file(par_name, file_path)[source]#

Export a file to the config file directory.

Parameters:

par_name: str: Name of the parameter.
file_path: str: Path of the file to be added to the config file directory.

property extra_label#: Return the extra label if defined, if not return ‘’.

get_config_file(no_export=False)[source]#

Get the path of the config file for sim_telarray.

The config file is produced if the file is not up to date.

Parameters:

no_export: bool: Turn it on if you do not want the file to be exported.

Returns:

Path: Path of the exported config file for sim_telarray.

get_parameter_file_flag(par_name)[source]#

Get value of parameter file flag of this database entry (boolean ‘file’ field of DB entry).

Parameters:

par_name: str: Name of the parameter.

Returns:

bool: True if file flag is set.

get_parameter_type(par_name)[source]#

Get the type of existing parameter of the model (value of ‘type’ field of DB entry).

Parameters:

par_name: str: Name of the parameter.

Returns:

str or None: type of the parameter (None if no type is defined)

get_parameter_value(par_name, parameter_dict=None)[source]#

Get the value of a model parameter.

List of values stored in strings are returns as lists, so that no knowledge of the database structure is needed when accessing the model parameters.

Parameters:

par_name: str: Name of the parameter.
parameter_dict: dict: Dictionary with complete DB entry for the given parameter (including the ‘value’, ‘units’ fields).

Returns:

Value of the parameter.

Raises:

KeyError: If par_name does not match any parameter in this model.

get_parameter_value_with_unit(par_name)[source]#

Get the value of an existing parameter of the model as an Astropy Quantity with its unit.

Parameters:

par_name: str: Name of the parameter.

Returns:

Astropy quantity with the value of the parameter multiplied by its unit.
If no unit is provided in the model, the value is returned without a unit.

get_simtel_parameters(parameters=None, telescope_model=True, site_model=True)[source]#

Get simtel parameters as name and value pairs.

Parameters:

parameters: dict: Parameters (simtools) to be renamed (if necessary)
telescope_model: bool: If True, telescope model parameters are included.
site_model: bool: If True, site model parameters are included.

Returns:

dict: simtel parameters as dict (sorted by parameter names)

get_simulation_software_parameters(simulation_software)[source]#

Get simulation software parameters.

Parameters:

simulation_software: str: Simulation software name.

Returns:

dict: Simulation software parameters.

print_parameters()[source]#: Print parameters and their values for debugging purposes.

set_extra_label(extra_label)[source]#

Set an extra label for the name of the config file.

Parameters:

extra_label: str: Extra label to be appended to the original label.

Notes

The config file directory name is not affected by the extra label. Only the file name is changed. This is important for the ArrayModel class to export multiple config files in the same directory.

model utilities#

Helper functions calculations related to model parameters.

model.model_utils.compute_telescope_transmission(pars, off_axis)[source]#

Compute telescope transmission (0 < T < 1) for a given off-axis angle.

The telescope transmission depends on the MC model used.

Parameters:

pars: list of float: Parameters of the telescope transmission. Len(pars) should be 4.
off_axis: float: Off-axis angle in deg.

Returns:

float: Telescope transmission.

model.model_utils.is_two_mirror_telescope(telescope_model_name)[source]#

Check if the telescope is a two mirror design.

Parameters:

telescope_model_name: str: Telescope model name (ex. LSTN-01).

Returns:

bool: True if the telescope is a two mirror one.

site_model#

Definition of site model.

class model.site_model.SiteModel(site: str, mongo_db_config: dict, model_version: str, label: str | None = None)[source]#

SiteModel represents the MC model of an observatory site.

Parameters:

site: str: Site name (e.g., South or North).
mongo_db_config: dict: MongoDB configuration.
model_version: str: Model version.
label: str: Instance label. Important for output file naming.

export_atmospheric_transmission_file(model_directory: Path)[source]#

Export atmospheric transmission file.

This method is needed because when CORSIKA is not piped to sim_telarray, the atmospheric transmission file is not written out to the model directory. This method allows to export it explicitly.

Parameters:

model_directory: Path: Model directory to export the file to.

get_array_elements_for_layout(layout_name: str) → list[source]#

Return list of array elements for a given array layout.

Parameters:

layout_name: str: Name of the array layout

Returns:

list: List of array elements

get_corsika_site_parameters(config_file_style: bool = False, model_directory: Path | None = None) → dict[source]#

Get site-related CORSIKA parameters as dict.

Parameters are returned with units wherever possible.

Parameters:

config_file_style: bool: Return using CORSIKA config file syntax
model_directory: Path, optional: Model directory to use for file paths

Returns:

dict: Site-related CORSIKA parameters as dict

get_list_of_array_layouts() → list[source]#

Get list of available array layouts.

Returns:

list: List of available array layouts

get_reference_point() → dict[source]#

Get reference point coordinates as dict.

Returns:

dict: Reference point coordinates as dict

telescope_model#

MC model of a telescope.

class model.telescope_model.TelescopeModel(site, telescope_name, mongo_db_config, model_version, label=None)[source]#

TelescopeModel represents the MC model of an individual telescope.

TelescopeModel contains parameter names and values for a specific telescope model.

Parameters:

site: str: Site name (e.g., South or North).
telescope_name: str: Telescope name (ex. LSTN-01, LSTN-design, …).
mongo_db_config: dict: MongoDB configuration.
model_version: str: Model version.
label: str: Instance label. Important for output file naming.

static calc_average_curve(curves, incidence_angle_dist)[source]#

Calculate an average curve from a set of curves.

The calculation uses weights the distribution of incidence angles provided in incidence_angle_dist.

Parameters:

curves: dict: dict of with 3 “columns”, Wavelength, Angle and z. The dictionary represents a two dimensional distribution of wavelengths and angles with the z value being e.g., reflectivity, transmission, etc.
incidence_angle_dist: astropy.table.Table: Instance of astropy.table.Table with the incidence angle distribution. The assumed columns are “Incidence angle” and “Fraction”.

Returns:

average_curve: astropy.table.Table: Instance of astropy.table.Table with the averaged curve.

property camera#: Load the camera information if the class instance hasn’t done it yet.

export_single_mirror_list_file(mirror_number, set_focal_length_to_zero)[source]#

Export a mirror list file with a single mirror in it.

Parameters:

mirror_number: int: Number index of the mirror.
set_focal_length_to_zero: bool: Set the focal length to zero if True.

export_table_to_model_directory(file_name, table)[source]#

Write out a file with the provided table to the model directory.

Parameters:

file_name: str: File name to write to.
table: astropy.table.Table: Instance of astropy.table.Table with the values to write to the file.

Returns:

Path:: Path to the file exported.

get_on_axis_eff_optical_area()[source]#: Return the on-axis effective optical area (derived previously for this telescope).

get_single_mirror_list_file(mirror_number, set_focal_length_to_zero=False)[source]#

Get the path to the single mirror list file.

Parameters:

mirror_number: int: Mirror number.
set_focal_length_to_zero: bool: Flag to set the focal length to zero.

Returns:

Path: Path of the single mirror list file.

get_telescope_effective_focal_length(unit='m', return_focal_length_if_zero=False)[source]#

Return effective focal length.

The function ensures backwards compatibility with older sim-telarray versions.

Parameters:

unit: str: Unit of the effective focal length. Default is ‘m’.
return_focal_length_if_zero: bool: If True, return the focal length if the effective focal length is 0.

Returns:

float:: Effective focal length.

is_file_2d(par)[source]#

Check if the file referenced by par is a 2D table.

Parameters:

par: str: Name of the parameter.

Returns:

bool:: True if the file is a 2D map type, False otherwise.

property mirrors#: Load the mirror information if the class instance hasn’t done it yet.

position(coordinate_system='ground')[source]#

Get coordinates in the given system.

Parameters:

coordinate_system: str: Coordinates system. Default is ‘ground’.

Returns:

list: List of telescope position in the requested coordinate system.

Raises:

KeyError: If the coordinate system is not found.

read_incidence_angle_distribution(incidence_angle_dist_file)[source]#

Read the incidence angle distribution from a file.

Parameters:

incidence_angle_dist_file: str: File name of the incidence angle distribution

Returns:

incidence_angle_dist: astropy.table.Table: Instance of astropy.table.Table with the incidence angle distribution.

read_two_dim_wavelength_angle(file_name)[source]#

Read a two dimensional distribution of wavelength and angle (z-axis can be anything).

Return a dictionary with three arrays, wavelength, angles, z (can be transmission, reflectivity, etc.)

Parameters:

file_name: str or Path: File assumed to be in the model directory.

Returns:

dict:: dict of three arrays, wavelength, degrees, z.

MC Model

Contents

MC Model#

array_model#

calibration_model#

camera#

mirrors#

model_parameter#

model utilities#

site_model#

telescope_model#