Layout#

The Layout Array module deals with the telescope positions and coordinate transformations. It is used within CORSIKA Config and Array Model in order to encapsulate the information about the telescope positions.

array_layout#

Prepare layout for coordinate transformations.

class layout.array_layout.ArrayLayout(site, model_version, label=None, name=None, telescope_list_file=None, telescope_list_metadata_file=None, validate=False, model_reader=None, context=None)[source]#

Manage telescope positions at the array layout level.

Parameters:

site: str: Site name or location (e.g., North/South or LaPalma/Paranal)
model_version: str: Version of the model (e.g., 6.0.0).
label: str: Instance label.
name: str: Name of the layout.
telescope_list_file: str or Path: Path to the telescope list file.
telescope_list_metadata_file: str or Path: Path to telescope list metadata (if not part of telescope_list_file)
validate: bool: Validate input file list.

convert_coordinates()[source]#: Perform all the possible conversions the coordinates of the tel positions.

export_one_telescope_as_json(crs_name, parameter_version=None, schema_version=None)[source]#

Return a list containing a single telescope in simtools model JSON.

Parameters:

crs_name: str: Name of coordinate system to be used for export.
schema_version: str: Version of the schema.

Returns:

dict: Dictionary with array element information.

export_telescope_list_table(crs_name)[source]#

Export array elements positions to astropy table.

Parameters:

crs_name: str: Name of coordinate system to be used for export.

Returns:

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

print_telescope_list(crs_name)[source]#

Print list of telescopes.

Parameters:

crs_name: str: Name of coordinate system to be used for export.

select_assets(asset_list=None)[source]#

Select a subsets of telescopes / assets from the layout.

Parameters:

asset_list: list: List of assets to be selected (telescope names or types)

Raises:

ValueError: If the asset list is empty.

exception layout.array_layout.InvalidTelescopeListFileError[source]#: Exception for invalid telescope list file.

telescope_position#

Telescope positions and coordinate transformations.

exception layout.telescope_position.InvalidCoordSystemErrorError[source]#: Exception for invalid coordinate system.

class layout.telescope_position.TelescopePosition(name=None)[source]#

Store a telescope position and perform coordinate transformations.

The definition of x_coord and y_coord in this class depend on the coordinate system (e.g., (x_coord, y_coord) == (UTM_east, UTM_north)). Altitude describes always the element height above sea level, position_z the height above a reference altitude (e.g., CORSIKA observation level).

Each array element stores its position in multiple coordinate systems with the TelescopePosition.crs dictionary. The definition of coordinate systems and corresponding axes is as follows:

{
    "ground": {
        "crs": <pyproj.CRS>,
        "xx": {"name": "position_x", "value": float, "unit": m},
        "yy": {"name": "position_y", "value": float, "unit": m},
        "zz": {"name": "position_z", "value": float, "unit": m},
    },
    "utm": {
        "crs": <pyproj.CRS>,
        "xx": {"name": "utm_east", "value": float, "unit": m},
        "yy": {"name": "utm_north", "value": float, "unit": m},
        "zz": {"name": "altitude", "value": float, "unit": m},
    },
    "mercator": {
        "crs": <pyproj.CRS>,
        "xx": {"name": "latitude", "value": float, "unit": deg},
        "yy": {"name": "longitude", "value": float, "unit": deg},
        "zz": {"name": "altitude", "value": float, "unit": m},
    },
    "auxiliary": {
        "telescope_sphere_radius": {...},
        "telescope_axis_height": {...},
    }
}

Parameters:

name: str: Name of the telescope (e.g LSTN-01, SSTS-05, …).

convert_all(crs_local=None, crs_wgs84=None, crs_utm=None)[source]#

Perform conversions and fill coordinate variables.

Parameters:

crs_local: pyproj.crs.crs.CRS: Pyproj CRS of the local coordinate system.
crs_wgs84: pyproj.crs.crs.CRS: Pyproj CRS of the mercator coordinate system.
crs_utm: pyproj.crs.crs.CRS: Pyproj CRS of the utm coordinate system.

static convert_telescope_altitude_from_corsika_system(tel_corsika_z, corsika_observation_level=None, telescope_axis_height=None)[source]#

Convert Corsika (pos_z) to altitude.

Parameters:

tel_corsika_z: astropy.Quantity: Telescope z-position in CORSIKA system in equivalent units of meter.
corsika_observation_level: astropy.Quantity: CORSIKA observation level in equivalent units of meter.
telescope_axis_height: astropy.Quantity: Height of telescope elevation axis above ground level in equivalent units of meter.

Returns:

astropy.units.m: Telescope altitude (above sea level)

static convert_telescope_altitude_to_corsika_system(tel_altitude, corsika_observation_level, telescope_axis_height)[source]#

Convert telescope altitude to CORSIKA system (pos_z).

Parameters:

tel_altitude: astropy.Quantity: Telescope altitude in equivalent units of meter.
corsika_ob_level: astropy.Quantity: CORSIKA observation level in equivalent units of meter.
telescope_axis_height: astropy.Quantity: Height of telescope elevation axis above ground level in equivalent units of meter.

Returns:

astropy.units.m: Z-position of a telescope in CORSIKA system.

get_axis_height()[source]#

Get telescope axis height.

Returns:

astropy.quantity: Telescope axis height.

get_coordinates(crs_name, coordinate_field=None)[source]#

Get coordinates in a given coordinate system.

Parameters:

crs_name: str: name of coordinate system.
coordinate_field: str: return specified field of coordinate descriptor.

Returns:

x, y, z coordinate including corresponding unit (or coordinate field). If coordinate_field is None, returns value x unit.

Raises:

InvalidCoordSystemErrorError: if coordinate system is not defined

get_sphere_radius()[source]#

Get telescope sphere radius.

Returns:

astropy.quantity: Telescope sphere radius

has_altitude(crs_name=None)[source]#

Return True if array element has altitude defined.

Parameters:

crs_name: str: Name of coordinate system to be checked for altitude. If None: check if altitude is define for any system.

Returns:

bool: array element has altitude defined.

Raises:

InvalidCoordSystemErrorError: If coordinate system is not known

has_coordinates(crs_name, crs_check=False)[source]#

Check if coordinates are set for a given coordinate system.

Attributes:

crs_name: str: Name of coordinate system.
crs_check: bool: Check that projection system is defined.

Returns:

bool: True if coordinate system is defined.

Raises:

InvalidCoordSystemErrorError: If coordinate system is not known.

is_coordinate_system(crs_name)[source]#

Check if crs_name describes a coordinate system or auxiliary information.

Parameters:

crs_name: str: Name of coordinate system.

Returns:

bool: True if coordinate system is defined.

Raises:

InvalidCoordSystemErrorError: If coordinate system is not known.

print_compact_format(crs_name, print_header=False, corsika_observation_level=None)[source]#

Print array element coordinates in compact format.

Parameters:

crs_name: str: Name of coordinate system to be used for printing.
print_header: bool: Print table header.
corsika_observation_level: astropy.Quantity: CORSIKA observation level in equivalent units of meter.

Raises:

InvalidCoordSystemErrorError: if coordinate system is not defined.

set_altitude(tel_altitude)[source]#

Set altitude of an array element.

Assume that all coordinate system have same altitude definition, meaning altitude is set for all systems here.

Attributes:

tel_altitude: astropy.Quantity

set_auxiliary_parameter(parameter_name, quantity)[source]#

Set auxiliary parameter.

Parameters:

parameter_name: str: Name of parameter.
quantity: astropy.units.Quantity: Quantity of parameter.

set_coordinates(crs_name, xx, yy, zz=None)[source]#

Set coordinates of an array element.

Attributes:

crs_name: str: Name of coordinate system.
xx: float: x-coordinate.
yy: float: y-coordinate.
zz: float: z-coordinate (altitude).

Raises:

InvalidCoordSystemErrorError: If coordinate system is not known.

geo_coordinates#

Definition of geospatial coordinate systems.

class layout.geo_coordinates.GeoCoordinates[source]#

Geospatial Coordinate systems.

Defines UTM, WGS84 and ground (sim_telarray) coordinate systems.

static coordinate_parameter_names()[source]#: Return site parameters required for coordinate transformations.

crs_local(reference_point)[source]#

Local coordinate system definition.

This is a cartesian coordinate system with the origin at the array center. X-axis points towards geographic North, y-axis towards geographic West.

Parameters:

reference_point: simtools.layout.telescope_position: Reference coordinate.

Returns:

pyproj.CRS: local coordinate system.

crs_utm(epsg)[source]#

UTM coordinate system definition.

Parameters:

epsg: int: EPSG code for UTM zone.

Returns:

pyproj.CRS: UTM coordinate system.

static crs_wgs84()[source]#

WGS84 coordinate system definition.

Returns:

pyproj.CRS: WGS84 coordinate system.

array_layout_utils#

Retrieve, merge, and write layout dictionaries.

layout.array_layout_utils.create_regular_array(array_name, site, n_telescopes, telescope_type, telescope_distance, shape='square')[source]#

Create a regular array layout table.

Parameters:

array_namestr: Name of the regular array (e.g. “4MST”).
sitestr: Site identifier.
n_telescopesint: Number of telescopes in the array.
telescope_typestr: Type of telescope (e.g. “MST”).
telescope_distanceQuantity: Distance between telescopes in the array.
shapestr: Shape of the array: “square” or “star” (default: “square”).

Returns:

astropy.table.Table: Table with the regular array layout.

Raises:

ValueError: If the shape is not supported.

layout.array_layout_utils.get_array_layout_elements(array_layouts, layout_name)[source]#

Return the elements of a named layout in an array-layout parameter.

Parameters:

array_layoutsdict: Canonical array_layouts model parameter.
layout_namestr: Name of the reference layout.

Returns:

list: Elements in the named layout, in stored order.

Raises:

ValueError: If the layout does not exist or has no elements.

layout.array_layout_utils.merge_array_layouts(layouts_1, layouts_2)[source]#

Compare two array layout dictionaries and merge them.

Parameters:

layouts_1dict: Array layout dictionary 1.
layouts_2dict: Array layout dictionary 2.

Returns:

dict: Merged array layout dictionary based on layout_1.

layout.array_layout_utils.prepare_array_layouts_for_submission(model_reader, args_dict)[source]#

Read or construct array layouts for the submit application.

The legacy file input is returned unchanged. Direct input reads the base parameter, validates the requested layout against its reference layout, and adds the new layout to the base value.

Parameters:

model_readerSimulationModelReader: Configured source-neutral simulation-model reader.
args_dictdict: Parsed application arguments.

Returns:

tuple: Array-layout parameter and the single model version used for validation.

Raises:

ValueError: If the input mode or required direct-layout arguments are invalid.

layout.array_layout_utils.read_layouts(args_dict, model_reader=None, context=None)[source]#

Read array layouts from the model repository or parameter file.

Parameters:

args_dictdict: Dictionary with command line arguments.
model_readerSimulationModelReader, optional: Model reader.
contextRunContext, optional: Run context.

Returns:

tuple: List of array layouts and the background layout (or None).

Raises:

ValueError: If array_layout_name_from_parameter_file is given without array_layout_parameter_file.

layout.array_layout_utils.resolve_array_layout_name(array_layout_name, model_version)[source]#

Resolve array layout configuration for a specific model version.

Parameters:

array_layout_namestr or dict or list of str or list of dict: Array layout name(s) or configuration(s) to resolve.
model_versionstr: Model version to resolve for.

Returns:

str or dict or list: The resolved array layout name(s) or configuration.

layout.array_layout_utils.retrieve_ctao_array_layouts(site, repository_url, branch_name='main')[source]#

Retrieve array layouts from the CTAO common identifiers repository.

Parameters:

sitestr: Site identifier.
repository_urlstr: URL or path to CTAO common identifiers.
branch_namestr: Repository branch to use.

Returns:

tuple: Array layouts for the site (list of dicts) and subarray-ids.json metadata (list).

layout.array_layout_utils.validate_array_layout_subset_of_reference(layout_name, elements, reference_elements, reference_layout_name)[source]#

Validate and return one array layout constrained by a reference layout.

Parameters:

layout_namestr: Name of the new layout.
elementslist: Telescope names selected for the new layout.
reference_elementslist: Telescope names allowed by the reference layout.
reference_layout_namestr: Name used in validation error messages.

Returns:

dict: Canonical one-layout dictionary.

Raises:

ValueError: If the name or element list is invalid, has duplicates, or is not a subset of the reference layout.

layout.array_layout_utils.validate_array_layouts_with_model_repository(production_table, array_layouts)[source]#

Validate that all telescopes in the array layouts exist in the production table.

Parameters:

production_tabledict: Production table from the model repository.
array_layoutsdict: Array layouts to be validated.

Returns:

dict: Validated array layouts.

Raises:

ValueError: If array elements are not in the production table.

layout.array_layout_utils.write_array_elements_from_file_to_repository(coordinate_system, input_file, repository_path, parameter_version, context=None)[source]#

Read array elements from file and write their positions to the model repository.

Writes one model parameter file per array element.

Parameters:

coordinate_systemstr: Coordinate system of array element positions (utm or ground).
input_filestr or Path: Path to input file with array element positions.
repository_pathstr or Path: Path to model repository.
parameter_versionstr: Parameter version to use when writing to repository.
contextRunContext, optional: Run context.

Notes

Writes files directly and does not query the model repository for an existing version.

layout.array_layout_utils.write_array_elements_info_yaml(array_table, site, model_version, output_file, parameter_version='2.0.0')[source]#

Write YAML file for array layout in a format compatible with overwrite.

Parameters:

array_tableastropy.table.Table: Table with telescope positions.
sitestr: Site identifier (e.g., ‘North’ or ‘South’).
model_versionstr: Model version.
output_filePath: Path to the output YAML file.
parameter_versionstr: Parameter version to use in the YAML file.

layout.array_layout_utils.write_array_layouts(array_layouts, args_dict, associated_data=None, *, context=None)[source]#

Write array layouts as model parameter.

Parameters:

array_layoutsdict: Array layouts to be written.
args_dictdict: Command line arguments.
associated_datalist, optional: Associated data entries to include in the metadata.
contextRunContext, optional: Run context (defaults to the environment).

array_layout_sources#

Read array layouts from the model repository, parameter files, and astropy table files.

layout.array_layout_sources.get_array_elements_from_model_repository(layouts, site, model_version, model_reader=None, context=None)[source]#

Get the array elements from the model repository for a list of layout names.

Structure of the returned dictionary:

{"layout_name_1": [telescope_id_1, ...], "layout_name_2": [telescope_id_3, ...]}

Parameters:

layoutslist[str]: Layout names to read. If [“all”], read all available layouts.
sitestr: Site name for the array layouts.
model_versionstr: Model version for the array layouts.
model_readerSimulationModelReader, optional: Model reader.
contextRunContext, optional: Run context.

Returns:

dict: Dictionary mapping layout names to telescope IDs.

layout.array_layout_sources.get_array_layouts_from_file(file_path, context=None)[source]#

Retrieve array layout(s) from astropy table file(s).

Parameters:

file_pathstr or Path or list of str or list of Path: Path(s) to array layout file(s).
contextRunContext, optional: Run context.

Returns:

list: List of dictionaries containing array layout names and their elements.

layout.array_layout_sources.get_array_layouts_from_model_repository(layout_name, site, model_version, coordinate_system='ground', ignore_software_version=False, model_reader=None, context=None)[source]#

Retrieve array layouts from the model repository.

Parameters:

layout_namestr or list: Layout name(s) to retrieve (None: retrieve all layouts).
sitestr: Site identifier.
model_versionstr: Model version to retrieve.
coordinate_systemstr: Coordinate system for the array elements (default: “ground”).
ignore_software_versionbool: If True, skip the software version compatibility check.
model_readerSimulationModelReader, optional: Model reader.
contextRunContext, optional: Run context.

Returns:

list or dict: Array layouts (a single dict if exactly one layout is found).

layout.array_layout_sources.get_array_layouts_from_parameter_file(file_path, model_version, coordinate_system='ground', array_layout_name=None, context=None)[source]#

Retrieve array layouts from a parameter file.

Parameters:

file_pathstr or Path: Path to the array layout parameter file.
model_versionstr: Model version to retrieve.
coordinate_systemstr: Coordinate system for the array elements (default: “ground”).
array_layout_namelist, optional: Layouts to retrieve (None: retrieve all).
contextRunContext, optional: Run context.

Returns:

list: List of dictionaries containing array layout names and their elements.

Raises:

ValueError: If the file has no ‘value’ key.

layout.array_layout_sources.get_array_layouts_using_telescope_lists_from_model_repository(telescope_lists, site, model_version, coordinate_system='ground', ignore_software_version=False, model_reader=None, context=None)[source]#

Retrieve array layouts from the model repository using telescope lists.

Parameters:

telescope_listslist: Telescope lists to retrieve array layouts for.
sitestr or None: Site identifier. If None, derived from the telescope names.
model_versionstr: Model version to retrieve.
coordinate_systemstr: Coordinate system for the array elements (default: “ground”).
ignore_software_versionbool: If True, skip the software version compatibility check.
model_readerSimulationModelReader, optional: Model reader.
contextRunContext, optional: Run context.

Returns:

list: List of dictionaries containing array layout names and their elements.

Raises:

ValueError: If a telescope list mixes sites and no site is given.