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(mongo_db_config, site, model_version, label=None, name=None, telescope_list_file=None, telescope_list_metadata_file=None, validate=False)

Manage telescope positions at the array layout level.

Parameters:

mongo_db_config: dict

MongoDB configuration.

site: str

Site name or location (e.g., North/South or LaPalma/Paranal)

model_version: str

Version of the model (e.g., prod6).

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.

add_telescope(telescope_name, crs_name, xx, yy, altitude=None, tel_corsika_z=None)

Add an individual telescope to the telescope list.

Parameters:

telescope_name: str

Name of the telescope starting with L, M or S (e.g. LST-01, MST-06 …)

crs_name: str

Name of coordinate system

xx: astropy.units.quantity.Quantity

x-coordinate for the given coordinate system

yy: astropy.units.quantity.Quantity

y-coordinate for the given coordinate system

altitude: astropy.units.quantity.Quantity

Altitude coordinate in equivalent units of u.m.

tel_corsika_z: astropy.units.quantity.Quantity

CORSIKA z-position (requires setting of CORSIKA observation level and telescope sphere center).

convert_coordinates()

Perform all the possible conversions the coordinates of the tel positions.

export_one_telescope_as_json(crs_name)

Return a list containing a single telescope in simtools-DB-style json.

Parameters:

crs_name: str

Name of coordinate system to be used for export.

Returns:

dict

Dictionary with array element information.

export_telescope_list_table(crs_name)

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.

get_number_of_telescopes()

Return the number of telescopes in the list.

Returns:

int

Number of telescopes.

print_telescope_list(crs_name)

Print list of telescopes.

Parameters:

crs_name: str

Name of coordinate system to be used for export.

select_assets(asset_list=None)

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

Exception for invalid telescope list file.

telescope_position

Telescope positions and coordinate transformations.

exception layout.telescope_position.InvalidCoordSystemErrorError

Exception for invalid coordinate system.

class layout.telescope_position.TelescopePosition(name=None)

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

Parameters:

name: str

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

convert_all(crs_local=None, crs_wgs84=None, crs_utm=None)

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)

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)

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_altitude()

Get altitude of an array element.

Returns:

astropy.Quantity

telescope altitude.

get_axis_height()

Get telescope axis height.

Returns:

astropy.quantity

Telescope axis height.

get_coordinates(crs_name, coordinate_field=None)

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

Get telescope sphere radius.

Returns:

astropy.quantity

Telescope sphere radius

has_altitude(crs_name=None)

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)

Check if coordinates are set for a given coordinate system.

Returns:

bool

True if coordinate system is defined.

Raises:

InvalidCoordSystemErrorError

If coordinate system is not known.

Attributes:

crs_name: str

Name of coordinate system.

crs_check: bool

Check that projection system is defined.

is_coordinate_system(crs_name)

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)

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)

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)

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)

Set coordinates of an array element.

Raises:

InvalidCoordSystemErrorError

If coordinate system is not known.

Attributes:

crs_name: str

Name of coordinate system.

xx: float

x-coordinate.

yy: float

y-coordinate.

zz: float

z-coordinate (altitude).

geo_coordinates

Definition of geospatial coordinate systems.

class layout.geo_coordinates.GeoCoordinates

Geospatial Coordinate systems.

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

crs_local(reference_point)

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)

UTM coordinate system definition.

Parameters:

epsg: int

EPSG code for UTM zone.

Returns:

pyproj.CRS

UTM coordinate system.

static crs_wgs84()

WGS84 coordinate system definition.

Returns:

pyproj.CRS

WGS84 coordinate system.