OpticsDescription

class ctapipe.instrument.OpticsDescription(name, size_type, n_mirrors, equivalent_focal_length, effective_focal_length, mirror_area, n_mirror_tiles, reflector_shape)

Bases: object

Describes the optics of a Cherenkov Telescope mirror

The string representation of an OpticsDescription will be a combination of the telescope-type and sub-type as follows: “type-subtype”. You can also get each individually.

Parameters:

namestr

Name of this optical system

n_mirrorsint

Number of mirrors, i. e. 2 for Schwarzschild-Couder else 1

equivalent_focal_lengthastropy.units.Quantity[length]

Equivalent focal-length of telescope, independent of which type of optics (as in the Monte-Carlo). This is the nominal focal length for single mirror telescopes and the equivalent focal length for dual mirror telescopes.

effective_focal_lengthastropy.units.Quantity[length]

The effective_focal_length is the focal length estimated from ray tracing to correct for coma aberration. It is thus not automatically available for all simulations, but only if it was set beforehand in the simtel configuration. This is the focal length that should be used for transforming from camera frame to telescope frame for all reconstruction tasks to correct for the mean aberration.

mirror_areaastropy.units.Quantity[area]

total reflective surface area of the optical system (in m^2)

n_mirror_tilesint

number of mirror facets

Raises:

ValueError:

if tel_type or mirror_type are not one of the accepted values

TypeError, astropy.units.UnitsError:

if the units of one of the inputs are missing or incompatible

Attributes Summary

COMPATIBLE_TEL_TAB_VERSIONS
COMPATIBLE_VERSIONS
CURRENT_TAB_VERSION	Version of the legacy, per-subarray optics table
CURRENT_TEL_TAB_VERSION	Version for the new, per-telescope table that will allow describing mirror facets in the future
effective_focal_length
equivalent_focal_length
mirror_area
n_mirror_tiles
n_mirrors
name
reflector_shape
size_type

Methods Summary

from_name(name[, optics_table])	Construct an OpticsDescription from the name.
from_table(table, **kwargs)	Create an OpticsDescription instance from an astropy Table.
get_focal_length([focal_length_choice])	Get focal length for coordinate transformations.
get_known_optics_names([optics_table])	return the list of optics names from ctapipe resources, i.e. those that can be constructed by name (this does not return the list of known names from an already open Monte-Carlo file).
to_table()	Convert this OpticsDescription to an astropy Table for writing to files.

Attributes Documentation

COMPATIBLE_TEL_TAB_VERSIONS = {'1.0'}

COMPATIBLE_VERSIONS = {'4.0'}

CURRENT_TAB_VERSION = '4.0'

Version of the legacy, per-subarray optics table

CURRENT_TEL_TAB_VERSION = '1.0'

Version for the new, per-telescope table that will allow describing mirror facets in the future

effective_focal_length

equivalent_focal_length

mirror_area

n_mirror_tiles

n_mirrors

name

reflector_shape

size_type

Methods Documentation

classmethod from_name(name, optics_table='optics')

Construct an OpticsDescription from the name.

This needs the optics table dataset to be accessible via ~ctapipe.utils.get_table_dataset.

Parameters:

name: str

string representation of optics (MST, LST, SST-1M, SST-ASTRI,…)

optics_table: str

base filename of optics table if not ‘optics.*’

Returns:

OpticsDescription

classmethod from_table(table: Table | str | Path, **kwargs)

Create an OpticsDescription instance from an astropy Table.

See OpticsDescription.to_table for the opposite operation.

get_focal_length(focal_length_choice=FocalLengthKind.EFFECTIVE)

Get focal length for coordinate transformations.

This is a helper function to get the focal length, mainly to attach it to the CameraFrame coordinate frame for pixel coordinate transformations.

In most cases, the effective focal length should be strongly preferred, as it takes the effect of optical aberrations on the plate scale into account.

By default, this function will try to use the effective focal length and raise an error if it is not available.

classmethod get_known_optics_names(optics_table='optics')

return the list of optics names from ctapipe resources, i.e. those that can be constructed by name (this does not return the list of known names from an already open Monte-Carlo file)

Parameters:

optics_table: str or astropy Table

table where to read the optics description from. If a string, this is opened with ctapipe.utils.get_table_dataset()

to_table()

Convert this OpticsDescription to an astropy Table for writing to files.

See OpticsDescription.from_table for the opposite operation.