aotpy package

Subpackages

Module contents

aotpy is a package that supports the Adaptive Optics Telemetry (AOT) data exchange standard.

class aotpy.AOSystem(*, ao_mode: str, date_beginning: ~datetime.datetime | None = None, date_end: ~datetime.datetime | None = None, name: str | None = None, strehl_ratio: float | None = None, strehl_wavelength: float | None = None, config: str | None = None, atmosphere_params: list[~aotpy.core.atmosphere.AtmosphericParameters] = <factory>, main_telescope: ~aotpy.core.telescope.MainTelescope | None = None, sources: list[~aotpy.core.source.Source] = <factory>, scoring_cameras: list[~aotpy.core.optical_sensor.ScoringCamera] = <factory>, wavefront_sensors: list[~aotpy.core.optical_sensor.WavefrontSensor] = <factory>, wavefront_correctors: list[~aotpy.core.wavefront_corrector.WavefrontCorrector] = <factory>, loops: list[~aotpy.core.loop.Loop] = <factory>, metadata: list[~aotpy.core.base.Metadatum] = <factory>)[source]

Bases: object

Contains all the relevant information about an adaptive optics system. Different parts of the system can be accessed via the lists of objects it contains.

ao_mode: str

Describes the system’s AO configuration.

Must be one of 'SCAO', 'SLAO', 'GLAO', 'MOAO', 'LTAO' or 'MCAO' (which respectively stand for Single Conjugate, Single Laser, Ground Layer, Multi-Object, Laser Tomography and Multi-Conjugate Adaptive Optics).

atmosphere_params: list[AtmosphericParameters]

List of all atmospheric data related to the system.

config: str = None

Free-form text that describes configuration parameters of the system.

date_beginning: datetime = None

Start time of data acquisition.

date_end: datetime = None

Stop time of data acquisition.

loops: list[Loop]

List of all loops in the system.

main_telescope: MainTelescope = None

The main telescope of the system.

metadata: list[Metadatum]

List of Metadatum objects that are associated with the overall system.

name: str = None

Name of the AO system that produced the data.

static read_from_file(filename: str | PathLike, file_type: str | None = None, **kwargs) → AOSystem[source]

Reads AOSystem from a file using the correct reading function for that file type. The file type is deduced by the extension in the specified filename but it may instead be directly set via the file_type parameter.

Parameters:

  • filename – Path to the file to be read.

  • file_type – The type of the file to be read. By default, it attempts to determine the type from the file extension.

  • kwargs – Optional keyword arguments passed on as options to the reader function.

scoring_cameras: list[ScoringCamera]

List of all the scoring cameras in the system.

sources: list[Source]

List of all the light sources in the system.

strehl_ratio: float = None

Estimated mean Strehl ratio for the duration of the observation (arcsec).

strehl_wavelength: float = None

Reference wavelength for the Strehl ratio estimation (m).

wavefront_correctors: list[WavefrontCorrector]

List of all wavefront correctors in the system.

wavefront_sensors: list[WavefrontSensor]

List of all wavefront sensors in the system.

write_to_file(filename: str | PathLike, file_type: str | None = None, **kwargs) → None[source]

Writes AOSystem to a file using the correct writing function for that file type. The file type is deduced by the extension in the specified filename but it may instead be directly set via the file_type parameter.

Parameters:

  • filename – Path to the file to be written.

  • file_type – The type of the file to be written. By default, it attempts to determine the type from the file extension.

  • kwargs – Optional keyword arguments passed on as options to the writer function.

class aotpy.AOTFITSReader(filename, **kwargs)[source]

Bases: SystemReader

get_extra_data()[source]

Return a tuple of extra data that may have been in AOTFITS file.

get_system() → AOSystem[source]

Return AOSystem that has been read.

class aotpy.AOTFITSWriter(system: AOSystem)[source]

Bases: SystemWriter

get_hdulist()[source]

Get the HDUList that produces the AOT FITS file for the initialized system.

write(filename, **kwargs) → None[source]

Write the initialized system into the specified filename.

Parameters:

  • filename – Path to the file that will be written.

  • **kwargs – Keyword arguments passed on as options to the file handling function.

class aotpy.Aberration(uid: str, *, modes: ~aotpy.core.image.Image, coefficients: ~aotpy.core.image.Image, offsets: list[~aotpy.core.base.Coordinates] = <factory>)[source]

Bases: Referenceable

Represents an optical aberration that may exist in a certain part of the AO system.

coefficients: Image

Set of \(m\) coefficients (one for each of the orthonormal basis of modes) for each \(n\) pupil offset. (Dimensions \(m \times n\), in user defined units, using data type flt)

modes: Image

Set of \(m\) different \(h \times w\) arrays, each representing the orthonormal basis of the corresponding mode. (Dimensions \(m \times h \times w\), dimensionless quantity, using data type flt)

offsets: list[Coordinates]

List of horizontal/vertical offsets from the centre of the field, defined as Coordinates. There must be an offset for each set of coefficients.

class aotpy.AtmosphericParameters(uid: str, *, wavelength: float | None = None, time: ~aotpy.core.time.Time | None = None, r0: list[float] = <factory>, seeing: list[float] = <factory>, tau0: list[float] = <factory>, theta0: list[float] = <factory>, layers_relative_weight: ~aotpy.core.image.Image | None = None, layers_height: ~aotpy.core.image.Image | None = None, layers_l0: ~aotpy.core.image.Image | None = None, layers_wind_speed: ~aotpy.core.image.Image | None = None, layers_wind_direction: ~aotpy.core.image.Image | None = None, transformation_matrix: ~aotpy.core.image.Image | None = None)[source]

Bases: Referenceable

Contains atmospheric data relevant to the telemetry data recorded.

layers_height: Image = None

Height above observatory at zenith of each \(l\) turbulence layer, for each time instant. (Dimensions \(t \times l\), in m units, using data type flt)

layers_l0: Image = None

Outer scale of turbulence at reference wavelength at zenith of each \(l\) turbulence layer, for each time instant. (Dimensions \(t \times l\), in m units, using data type flt)

layers_relative_weight: Image = None

Fractional weight of each \(l\) turbulence layer (sums to 1), for each time instant. (Dimensions \(t \times l\), dimensionless quantity, using data type flt)

layers_wind_direction: Image = None

Wind direction of each \(l\) turbulence layer, for each time instant, with 0° being North, increasing eastward. (Dimensions \(t \times l\), in deg units, using data type flt)

layers_wind_speed: Image = None

Wind speed of each \(l\) turbulence layer, for each time instant. (Dimensions \(t \times l\), in ms\(^{-1}\) units, using data type flt)

r0: list[float]

List of Fried parameters at reference wavelength at zenith, over time. (in m units)

seeing: list[float]

List of full width at half maximum measures of the seeing disc at zenith, over time. (in arcsec units)

tau0: list[float]

List of atmospheric coherence times, over time. (in s units)

theta0: list[float]

List of isoplanatic angles, over time. (in rad units)

time: Time = None
transformation_matrix: Image = None

Matrix that defines 2-dimensional affine transformations over time (\(t\)) using homogeneous coordinates. Any combination of translation, reflection, scale, rotation and shearing can be described via a single \(3 \times 3\) matrix \(M\) such that \(P' = MP\), where \(P\) is a \(\begin{bmatrix}x & y & 1 \end{bmatrix}\) vector (with \(x\) and \(y\) being the original horizontal and vertical coordinates, respectively) and \(P'\) is a \(\begin{bmatrix}x' & y' & 1 \end{bmatrix}\), where \(x'\) and \(y'\) are the transformed coordinates. All geometry information must be described relative to the same reference origin point, from which transformations may occur. (Dimensions \(3 \times 3 \times t\), dimensionless quantity, using data type flt)

wavelength: float = None

Reference wavelength. (in m units)

class aotpy.CircularSegments(*, size: float | None = None, coordinates: list[~aotpy.core.base.Coordinates] = <factory>)[source]

Bases: Segments

Describes the circular segments that constitute the pupil.

class aotpy.ControlLoop(uid: str, *, commanded_corrector: WavefrontCorrector, time: Time | None = None, closed: bool = True, commands: Image | None = None, ref_commands: Image | None = None, framerate: float | None = None, delay: float | None = None, time_filter_num: Image | None = None, time_filter_den: Image | None = None, input_sensor: WavefrontSensor, modes: Image | None = None, modal_coefficients: Image | None = None, control_matrix: Image | None = None, measurements_to_modes: Image | None = None, modes_to_commands: Image | None = None, interaction_matrix: Image | None = None, commands_to_modes: Image | None = None, modes_to_measurements: Image | None = None, residual_commands: Image | None = None)[source]

Bases: Loop

Contains data relevant to a control loop (relation between one wavefront sensor and one wavefront corrector).

commands_to_modes: Image = None

Represents the modal response (\(m\)) to each actuator of the wavefront corrector (\(a_v\)). (Dimensions \(m \times a_v\), in user defined units, using data type flt)

control_matrix: Image = None

Linear relationship between the wavefront sensor measurements (\(d \times s_v\)) and the corrector commands (\(a_v\)). (Dimensions \(a_v \times d \times s_v\), in user defined units, using data type flt)

input_sensor: WavefrontSensor
interaction_matrix: Image = None

Represents the measurements of the wavefront sensor (\(s_v \times d\)) in response to each actuator of the wavefront corrector (\(a_v\)). (Dimensions \(s_v \times d \times a_v\), in user defined units, using data type flt)

measurements_to_modes: Image = None

Linear relationship between the wavefront sensor measurements (\(d \times s_v\)) and the modes to be corrected (\(m\)). (Dimensions \(m \times d \times s_v\), in user defined units, using data type flt)

modal_coefficients: Image = None

Sequence of coefficients of the modes to be corrected on the wavefront corrector. Each of the \(t\) frames contains the coefficients respective to each of the \(m\) modes being corrected. (Dimensions \(t \times m\), in user defined units, using data type flt)

modes: Image = None

Set of \(m\) different \(h \times w\) arrays, each representing the orthonormal basis of the corresponding mode. (Dimensions \(m \times h \times w\), dimensionless quantity, using data type flt)

modes_to_commands: Image = None

Linear relationship between the modes (\(m\)) to be corrected and the corrector commands (\(a_v\)). (Dimensions \(a_v \times m\), in user defined units, using data type flt)

modes_to_measurements: Image = None

Linear relationship between the modal response (\(m\)) and the wavefront sensor measurements (\(s_v \times d\)). (Dimensions \(s_v \times d \times m\), in user defined units, using data type flt)

residual_commands: Image = None

Reconstructed corrector commands before time filtering (Dimensions \(t \times a_v\), in user defined units, using data type flt)

class aotpy.Coordinates(x: float | None = None, y: float | None = None)[source]

Bases: object

Contains a set of horizontal (x) and vertical (y) Cartesian coordinates in a plane.

x: float = None

Horizontal Cartesian coordinate.

y: float = None

Vertical Cartesian coordinate.

class aotpy.DeformableMirror(uid: str, *, telescope: ~aotpy.core.telescope.Telescope, n_valid_actuators: int, pupil_mask: ~aotpy.core.image.Image | None = None, tfz_num: list[float] = <factory>, tfz_den: list[float] = <factory>, transformation_matrix: ~aotpy.core.image.Image | None = None, aberration: ~aotpy.core.aberration.Aberration | None = None, actuator_coordinates: list[~aotpy.core.base.Coordinates] = <factory>, influence_function: ~aotpy.core.image.Image | None = None, stroke: float | None = None)[source]

Bases: WavefrontCorrector

Contains data related to a deformable mirror in the system.

actuator_coordinates: list[Coordinates]

List of horizontal/vertical coordinates of the valid actuators of the DM. (in m units)

influence_function: Image = None

A set of 2D images, one for each valid actuator, where each image represents the displacement of the surface of the deformable mirror after poking the respective actuator. (Dimensions \(a_v \times h \times w\), in m units, using data type flt)

stroke: float = None

Maximum possible actuator displacement, measured as an excursion from a central null position. (in m units)

class aotpy.Detector(uid: str, *, type: str | None = None, sampling_technique: str | None = None, shutter_type: str | None = None, flat_field: ~aotpy.core.image.Image | None = None, readout_noise: float | None = None, pixel_intensities: ~aotpy.core.image.Image | None = None, field_centre: ~aotpy.core.base.Coordinates = <factory>, integration_time: float | None = None, coadds: int | None = None, dark: ~aotpy.core.image.Image | None = None, weight_map: ~aotpy.core.image.Image | None = None, quantum_efficiency: float | None = None, pixel_scale: float | None = None, binning: int | None = None, bandwidth: float | None = None, transmission_wavelength: list[float] = <factory>, transmission: list[float] = <factory>, sky_background: ~aotpy.core.image.Image | None = None, gain: float | None = None, excess_noise: float | None = None, filter: str | None = None, bad_pixel_map: ~aotpy.core.image.Image | None = None, dynamic_range: float | None = None, readout_rate: float | None = None, frame_rate: float | None = None, transformation_matrix: ~aotpy.core.image.Image | None = None)[source]

Bases: Referenceable

Contains data regarding a detector in the system. Detectors are a part of wavefront sensors and scoring cameras.

bad_pixel_map: Image = None

Binary image which identifies the bad pixels. Pixels identified with 1 are considered bad, while 0 is considered normal. (Dimensions \(h \times w\), dimensionless quantity, using data type int)

bandwidth: float = None

Width of the filter/bandpass of the optics+detector. (in m units)

binning: int = None

Integer value indicating the 2D pixel combination by the binning factor. (in count units)

coadds: int = None

Number of frame co-additions. (in count units)

dark: Image = None

Intensity detected in each pixel when there is no light being observed. This is an image spanning \(x\) pixels horizontally and \(y\) pixels vertically. (Dimensions \(h \times w\), in ADU units, using data type flt)

dynamic_range: float = None

Ratio of the maximum signal that can be integrated to the r.m.s. noise floor. If this ratio is R, then dynamic range in decibels is 20 log R. (in dB units)

excess_noise: float = None

Photon-noise gain factor (scalar) as a result of the electron-multiplied gain amplification in EMCCDs. (in e\(^-\) units)

field_centre: Coordinates

Defines the horizontal/vertical coordinates of the detector pixel on which the centre of the field is projected. Fractional Coordinates values imply that the centre is located in-between two pixels. (in pix units)

filter: str = None

Name of filter in use. (dimensionless quantity)

flat_field: Image = None

Inverse of the detector pixel-to-pixel sensitivity (Dimensions \(h \times w\), dimensionless quantity, using data type flt)

frame_rate: float = None

Inverse of the time needed for the detector to acquire an image and then completely read it out. (in frame s\(^{-1}\) units)

gain: float = None

Scalar magnitude of detector signal amplification. (in e\(^-\) units)

integration_time: float = None

Duration in seconds a pixel integrates flux, independent of the detector reading scheme. (in s units)

pixel_intensities: Image = None

Intensity detected in each pixel, for each data frame. This is a sequence of \(t\) images, each spanning \(x\) pixels horizontally and \(y\) pixels vertically. (Dimensions \(t \times h \times w\), in ADU units, using data type flt)

pixel_scale: float = None

Resolution in radians per detector pixel. (in rad pix\(^{-1}\) units)

quantum_efficiency: float = None

A 0–1 scalar indicating the ability to convert a photon into a usable electron. Quoted at the central wavelength as an effective value (dimensionless quantity)

readout_noise: float = None

Readout noise. (in e\(^-\) s\(^{-1}\) pix\(^{-1}\) units)

readout_rate: float = None

Inverse of the time required to digitize a single pixel (in px s\(^{-1}\) units)

sampling_technique: str = None

Identifies the sampling technique, for example 'Single Reset Read', 'Fowler', 'Double Correlated', 'Uncorrelated'. (dimensionless quantity)

shutter_type: str = None

Identifies the shutter type, typically 'Rolling' or 'Global'. (dimensionless quantity)

sky_background: Image = None

detector pixel intensities from a source-less direction in the sky (Dimensions \(h \times w\), in ADU units, using data type flt)

transformation_matrix: Image = None

Matrix that defines 2-dimensional affine transformations over time (\(t\)) using homogeneous coordinates. Any combination of translation, reflection, scale, rotation and shearing can be described via a single \(3 \times 3\) matrix \(M\) such that \(P' = MP\), where \(P\) is a \(\begin{bmatrix}x & y & 1 \end{bmatrix}\) vector (with \(x\) and \(y\) being the original horizontal and vertical coordinates, respectively) and \(P'\) is a \(\begin{bmatrix}x' & y' & 1 \end{bmatrix}\), where \(x'\) and \(y'\) are the transformed coordinates. All geometry information must be described relative to the same reference origin point, from which transformations may occur. (Dimensions \(3 \times 3 \times t\), dimensionless quantity, using data type flt)

transmission: list[float]

List of transmission percentages that describe a transmission profile. (dimensionless quantity)

transmission_wavelength: list[float]

List of wavelengths that describe a transmission profile. (in m units)

type: str = None

Identifies the type of detector, such as 'CMOS' or 'CCD'. (dimensionless quantity)

weight_map: Image = None

Pixel weight map, where each detector pixel is associated with a number that represents its relative value. Summing up to 1. (Dimensions \(h \times w\), dimensionless quantity, using data type flt)

class aotpy.FITSFileImage(path: str | PathLike, index: int | None = None, *, read_data=True, **kwargs)[source]

Bases: _FITSExternalImage

Describes an external FITS file present locally, containing multidimensional data and metadata related to it.

FITSFileImage remembers the path from which the data came from, enabling future referencing of that path.

Parameters:

  • path – Path to FITS file that contains multidimensional data.

  • index (int, optional) – Index of the HDU that contains the image data. If omitted, the first HDU containing image data is assumed.

  • **kwargs – Keyword arguments passed on as options to the file handling function.

class aotpy.FITSURLImage(url: str, index: int | None = None, *, read_data=True, **kwargs)[source]

Bases: _FITSExternalImage

Describes an external FITS file available via URL, containing multidimensional data and metadata related to it.

FITSURLImage remembers the URL from which the data came from, enabling future referencing of that URL.

Parameters:

  • url – URL to FITS file that contains multidimensional data.

  • index (int, optional) – Index of the HDU that contains the image data. If omitted, the first HDU containing image data is assumed.

  • **kwargs – Keyword arguments passed on as options to the file handling function.

class aotpy.HexagonalSegments(*, size: float | None = None, coordinates: list[~aotpy.core.base.Coordinates] = <factory>)[source]

Bases: Segments

Describes the hexagonal segments that constitute the pupil.

class aotpy.Image(name: str, data: ~numpy.ndarray, unit: str | None = None, time: ~aotpy.core.time.Time | None = None, metadata: list[~aotpy.core.base.Metadatum] = <factory>)[source]

Bases: object

Contains multidimensional data and the metadata related to it.

data: ndarray

The multi-dimensional data itself.

metadata: list[Metadatum]

List of Metadatum objects that describe the Image data.

metadata_to_dict() → dict[str, Any][source]

Return the metadata as a dictionary key->value (comments are ignored).

name: str

Unique name that identifies the data.

time: Time = None
unit: str = None

Unit of measurement used for the data.

class aotpy.LaserLaunchTelescope(uid: str, *, latitude: float | None = None, longitude: float | None = None, elevation: float | None = None, azimuth: float | None = None, parallactic: float | None = None, pupil_mask: ~aotpy.core.image.Image | None = None, pupil_angle: float | None = None, enclosing_diameter: float | None = None, inscribed_diameter: float | None = None, obstruction_diameter: float | None = None, segments: ~aotpy.core.telescope.Segments = <factory>, transformation_matrix: ~aotpy.core.image.Image | None = None, aberration: ~aotpy.core.aberration.Aberration | None = None)[source]

Bases: Telescope

Contains data related to a laser launch telescope in the system. These telescopes produce a laser guide star.

class aotpy.LinearStage(uid: str, *, telescope: ~aotpy.core.telescope.Telescope, pupil_mask: ~aotpy.core.image.Image | None = None, tfz_num: list[float] = <factory>, tfz_den: list[float] = <factory>, transformation_matrix: ~aotpy.core.image.Image | None = None, aberration: ~aotpy.core.aberration.Aberration | None = None)[source]

Bases: WavefrontCorrector

Contains data related to a linear stage in the system. It is assumed it has a single axis of movement.

n_valid_actuators: int = 1

Number of valid actuators in the corrector. (in count units)

class aotpy.Loop(uid: str, *, commanded_corrector: WavefrontCorrector, time: Time | None = None, closed: bool = True, commands: Image | None = None, ref_commands: Image | None = None, framerate: float | None = None, delay: float | None = None, time_filter_num: Image | None = None, time_filter_den: Image | None = None)[source]

Bases: Referenceable

Base class that contains data regarding one system loop.

closed: bool = True

Indicates whether the loop was opened or closed for the duration of the data collection.

commanded_corrector: WavefrontCorrector

Wavefront corrector that is being commanded by this loop.

commands: Image = None

Sequence of commands sent to the associated wavefront corrector. Each of the \(t\) frames contains the values sent to each of the \(a_v\) valid actuators of a certain wavefront corrector. (Dimensions \(t \times a_v\), in m units, using data type flt)

delay: float = None

Full AO loop delay, measured from the mid-point of the integration to the mid-point of the command applied. Includes the RTC latency and other communication delays. (in frame units)

framerate: float = None

Frequency at which the loop operates. (in Hz units)

ref_commands: Image = None

Reference offset commands for each of \(a_v\) actuators. (Dimensions \(a_v\), in m units, using data type flt)

time: Time = None
time_filter_den: Image = None

One set of time filter denominators per mode being described. If \(m=1\), it is assumed to be applicable to all modes. Uses standard transfer function \(sys(z) = \sum_{i=0}^{N-1} b_i z^i/\sum_{j=0}^N a_j z^j\). (Dimensions \(m \times j\), dimensionless quantity, using data type flt)

time_filter_num: Image = None

One set of time filter numerators per mode being described. If \(m=1\), it is assumed to be applicable to all modes. The first numerator is the loop gain. (Dimensions \(m \times i\), dimensionless quantity, using data type flt)

class aotpy.MainTelescope(uid: str, *, latitude: float | None = None, longitude: float | None = None, elevation: float | None = None, azimuth: float | None = None, parallactic: float | None = None, pupil_mask: ~aotpy.core.image.Image | None = None, pupil_angle: float | None = None, enclosing_diameter: float | None = None, inscribed_diameter: float | None = None, obstruction_diameter: float | None = None, segments: ~aotpy.core.telescope.Segments = <factory>, transformation_matrix: ~aotpy.core.image.Image | None = None, aberration: ~aotpy.core.aberration.Aberration | None = None)[source]

Bases: Telescope

Contains data related to the main telescope in the system. There is only one main telescope in each system.

class aotpy.Metadatum(key: str, value: Any, comment: str | None = None)[source]

Bases: object

Contains a set of key, value and (optionally) comment which describe the Image data in some aspect.

comment: str = None

Optional description of the metadatum.

key: str

Identifier of the value.

to_tuple() → tuple[source]

Return the Metadatum object expressed as a tuple (key, value, comment).

value: Any

Information that describes the Image data.

class aotpy.Monolithic[source]

Bases: Segments

Describes a monolithic pupil.

class aotpy.NaturalGuideStar(uid: str, *, right_ascension: float | None = None, declination: float | None = None, elevation_offset: float | None = None, azimuth_offset: float | None = None, fwhm: float | None = None)[source]

Bases: Source

Contains data regarding a natural guide star being observed by the system.

class aotpy.OffloadLoop(uid: str, *, commanded_corrector: WavefrontCorrector, time: Time | None = None, closed: bool = True, commands: Image | None = None, ref_commands: Image | None = None, framerate: float | None = None, delay: float | None = None, time_filter_num: Image | None = None, time_filter_den: Image | None = None, input_corrector: WavefrontCorrector, offload_matrix: Image | None = None)[source]

Bases: Loop

Contains data relevant to an offload loop (relation between two wavefront correctors).

input_corrector: WavefrontCorrector
offload_matrix: Image = None

Linear relationship between the commands from one actuator (\(a1\)) and the corresponding commands that get offloaded to another actuator (\(a2\)). (Dimensions \(a2_v \times a1_v\), in user defined units, using data type flt)

class aotpy.Pyramid(uid: str, *, source: ~aotpy.core.source.Source, dimensions: int = 4, n_valid_subapertures: int, measurements: ~aotpy.core.image.Image | None = None, ref_measurements: ~aotpy.core.image.Image | None = None, subaperture_mask: ~aotpy.core.image.Image | None = None, mask_offsets: list[~aotpy.core.base.Coordinates] = <factory>, subaperture_size: float | None = None, subaperture_intensities: ~aotpy.core.image.Image | None = None, wavelength: float | None = None, optical_gain: ~aotpy.core.image.Image | None = None, transformation_matrix: ~aotpy.core.image.Image | None = None, detector: ~aotpy.core.optical_sensor.Detector | None = None, aberration: ~aotpy.core.aberration.Aberration | None = None, non_common_path_aberration: ~aotpy.core.aberration.Aberration | None = None, n_sides: int, modulation: float | None = None)[source]

Bases: WavefrontSensor

Contains data related to one Pyramid wavefront sensor used by the system.

dimensions: int = 4

Number of dimensions being measured by each subaperture. For Pyramid this may be equal to 2 (if the signals are interpreted as horizontal and vertical offsets), 1 (if the subapertures overlap and are interpreted as a single signal) or as the number of sides of the pyramid (that is, n_sides signals). (in count units)

get_measurements_from_detector_pixels(index: slice | int)[source]

Retrieve measurements from the detector pixels based on the provided index and mask configuration.

This function extracts pixel intensities from the detector, using the subaperture mask and mask offsets to calculate the corresponding pixel positions. The index parameter specifies the frame slice or index for which to retrieve the pixel intensities.

Parameters:

index (slice or int) – The index or slice used to specify the frames to extract from the detector pixel intensities. If an integer is provided, the result will be returned for that frame. If a slice is provided, a corresponding slice of pixel intensities will be returned.

Returns:

An array containing the selected pixel intensities from the detector, with shape (n, len(self.mask_offsets), s), where n is the number of frames selected by index and s is the number of subapertures implied by the subaperture mask (i.e. np.count_nonzero(subaperture_mask.data!=-1)).

Return type:

numpy.ndarray

Raises:

  • TypeError – If the index is not a slice or integer.

  • RuntimeError – If any of the required attributes (detector, detector.pixel_intensities, subaperture_mask, mask_offsets, or subaperture_size) are missing.

  • NotImplementedError – If subaperture_size is not 1, as it is not supported.

Example

pixel_values = get_measurements_from_detector_pixels(slice(0, 10))

modulation: float = None

Modulation amplitude. (in m units)

n_sides: int

Number of pyramid sides (typically 4). (in count units)

class aotpy.RayleighLaserGuideStar(uid: str, *, right_ascension: float | None = None, declination: float | None = None, elevation_offset: float | None = None, azimuth_offset: float | None = None, fwhm: float | None = None, laser_launch_telescope: LaserLaunchTelescope | None = None, distance: float | None = None, depth: float | None = None)[source]

Bases: LaserGuideStar

Contains data regarding a Rayleigh laser guide star being observed by the system.

depth: float = None

Range covered by the laser light while the shutter is opened. (in m units)

distance: float = None

Fixed distance of the LGS from the telescope. (in m units)

class aotpy.Referenceable(uid: str)[source]

Bases: object

Abstract class for all classes which can be referenced via a UID.

uid: str

Unique identifier of the object, which allows unambiguous referencing.

class aotpy.ScienceStar(uid: str, *, right_ascension: float | None = None, declination: float | None = None, elevation_offset: float | None = None, azimuth_offset: float | None = None, fwhm: float | None = None)[source]

Bases: Source

Contains data regarding a science star being observed by the system.

class aotpy.ScoringCamera(uid: str, *, pupil_mask: Image | None = None, wavelength: float | None = None, transformation_matrix: Image | None = None, detector: Detector | None = None, aberration: Aberration | None = None)[source]

Bases: Referenceable

Contains data regarding a scoring camera in the system.

aberration: Aberration = None
detector: Detector = None
pupil_mask: Image = None

Binary image that describes the shape of the pupil. A 1 indicates the presence of the pupil, while a 0 indicates the opposite. (Dimensions \(h \times w\), dimensionless quantity, using data type int)

transformation_matrix: Image = None

Matrix that defines 2-dimensional affine transformations over time (\(t\)) using homogeneous coordinates. Any combination of translation, reflection, scale, rotation and shearing can be described via a single \(3 \times 3\) matrix \(M\) such that \(P' = MP\), where \(P\) is a \(\begin{bmatrix}x & y & 1 \end{bmatrix}\) vector (with \(x\) and \(y\) being the original horizontal and vertical coordinates, respectively) and \(P'\) is a \(\begin{bmatrix}x' & y' & 1 \end{bmatrix}\), where \(x'\) and \(y'\) are the transformed coordinates. All geometry information must be described relative to the same reference origin point, from which transformations may occur. (Dimensions \(3 \times 3 \times t\), dimensionless quantity, using data type flt)

wavelength: float = None

‘Observation wavelength (in m units)’

class aotpy.Segments(*, size: float | None = None, coordinates: list[~aotpy.core.base.Coordinates] = <factory>)[source]

Bases: object

Abstract class that describes the segments that constitute the pupil.

coordinates: list[Coordinates]

List of horizontal/vertical coordinates of each segment in the pupil. (in m units)

size: float = None

Size of the segments that constitute the pupil, measured as the diameter of the smallest circle that contains the entirety of a segment. If no segments exist (monolithic) this should be null. (in m units)

class aotpy.ShackHartmann(uid: str, *, source: ~aotpy.core.source.Source, n_valid_subapertures: int, measurements: ~aotpy.core.image.Image | None = None, ref_measurements: ~aotpy.core.image.Image | None = None, subaperture_mask: ~aotpy.core.image.Image | None = None, mask_offsets: list[~aotpy.core.base.Coordinates] = <factory>, subaperture_size: float | None = None, subaperture_intensities: ~aotpy.core.image.Image | None = None, wavelength: float | None = None, optical_gain: ~aotpy.core.image.Image | None = None, transformation_matrix: ~aotpy.core.image.Image | None = None, detector: ~aotpy.core.optical_sensor.Detector | None = None, aberration: ~aotpy.core.aberration.Aberration | None = None, non_common_path_aberration: ~aotpy.core.aberration.Aberration | None = None, centroiding_algorithm: str | None = None, centroid_gains: ~aotpy.core.image.Image | None = None, spot_fwhm: ~aotpy.core.image.Image | None = None)[source]

Bases: WavefrontSensor

Contains data related to one Shack-Hartmann wavefront sensor used by the system.

centroid_gains: Image = None

Centroid gain factors for each of \(s_v\) subapertures and \(d\) dimensions. (Dimensions \(d \times s_v\), dimensionless quantity, using data type flt)

centroiding_algorithm: str = None

Name of the centroiding algorithm used. (dimensionless quantity)

dimensions: int = 2

Number of dimensions being measured by each subaperture. For ShackHartmann this must be equal to 2 (horizontal and vertical offset). (in count units)

spot_fwhm: Image = None

Spot full width half maximum for each of \(s_v\) subapertures and \(d\) dimensions. (Dimensions \(d \times s_v\), in arcsec units, using data type flt)

class aotpy.SodiumLaserGuideStar(uid: str, *, right_ascension: float | None = None, declination: float | None = None, elevation_offset: float | None = None, azimuth_offset: float | None = None, fwhm: float | None = None, laser_launch_telescope: ~aotpy.core.telescope.LaserLaunchTelescope | None = None, height: float | None = None, profile: ~aotpy.core.image.Image | None = None, altitudes: list[float] = <factory>)[source]

Bases: LaserGuideStar

Contains data regarding a sodium laser guide star being observed by the system.

altitudes: list[float]

LGS layer profile altitudes at zenith. Must be the same length as the number of layers defined in profile. (in m units)

height: float = None

Mean LGS height at zenith. (in m units)

profile: Image = None

Normalised LGS profile (each set of \(l\) layers \(\sum = 1\)) at zenith, over time. (Dimensions \(t \times l\), dimensionless quantity, using data type flt)

class aotpy.Source(uid: str, *, right_ascension: float | None = None, declination: float | None = None, elevation_offset: float | None = None, azimuth_offset: float | None = None, fwhm: float | None = None)[source]

Bases: Referenceable

Abstract class that contains data regarding a light source used by the system.

azimuth_offset: float = None

Offset from the Main Telescope’s azimuth. (in deg units)

declination: float = None

Declination of the light source, epoch J2000 (equatorial coordinate system). (in deg units)

elevation_offset: float = None

Offset from the Main Telescope’s elevation. (in deg units)

fwhm: float = None

Effective width at zenith. (in rad units)

right_ascension: float = None

Right ascension of the light source, epoch J2000 (equatorial coordinate system). (in deg units)

class aotpy.SystemReader(filename: str | PathLike, **kwargs)[source]

Bases: ABC

Abstract class for system readers.

Readers are able to create an AOSystem based on a file of a certain format.

Parameters:

  • filename – Path to file to be read into an AOSystem.

  • **kwargs – Keyword arguments passed on as options to the file handling function.

abstract get_system() → AOSystem[source]

Return AOSystem that has been read.

class aotpy.SystemWriter(system: AOSystem)[source]

Bases: ABC

Abstract class for system writers.

Writers are able to write an AOSystem into a file using some format.

Parameters:

system – AOSystem to be written into a file.

abstract write(filename: str | PathLike, **kwargs) → None[source]

Write the initialized system into the specified filename.

Parameters:

  • filename – Path to the file that will be written.

  • **kwargs – Keyword arguments passed on as options to the file handling function.

class aotpy.Telescope(uid: str, *, latitude: float | None = None, longitude: float | None = None, elevation: float | None = None, azimuth: float | None = None, parallactic: float | None = None, pupil_mask: ~aotpy.core.image.Image | None = None, pupil_angle: float | None = None, enclosing_diameter: float | None = None, inscribed_diameter: float | None = None, obstruction_diameter: float | None = None, segments: ~aotpy.core.telescope.Segments = <factory>, transformation_matrix: ~aotpy.core.image.Image | None = None, aberration: ~aotpy.core.aberration.Aberration | None = None)[source]

Bases: Referenceable

Abstract class that contains data related to a telescope in the system.

aberration: Aberration = None
azimuth: float = None

Azimuth of the telescope at start, the angle of the object around the horizon with 0° being North, increasing eastward (horizontal coordinate system). (in deg units)

elevation: float = None

Elevation of the telescope at start, the angle between the object and the observer’s local horizon with 0° being the horizon and 90° being zenith (horizontal coordinate system). (in deg units)

enclosing_diameter: float = None

Diameter of the smallest circle that contains the entirety of the pupil (enclosing circle). (in m units)

inscribed_diameter: float = None

Diameter of the largest circle that can be contained in the pupil (inscribed circle). On monolithic circular pupils this is equivalent to enclosing_diameter. (in m units)

latitude: float = None

Latitude of the telescope (World Geodetic System). (in deg units)

longitude: float = None

Longitude of the telescope (World Geodetic System). (in deg units)

obstruction_diameter: float = None

Diameter of the smallest circle that fully contains the central obstruction. (in m units)

parallactic: float = None

Parallactic angle, the spherical angle between the hour circle and the great circle through a celestial object and the zenith. (in deg units)

pupil_angle: float = None

Clockwise rotation of the pupil mask. (in rad units)

pupil_mask: Image = None

Binary image that describes the shape of the pupil. A 1 indicates the presence of the pupil, while a 0 indicates the opposite. (Dimensions \(h \times w\), dimensionless quantity, using data type int)

segments: Segments
transformation_matrix: Image = None

Matrix that defines 2-dimensional affine transformations over time (\(t\)) using homogeneous coordinates. Any combination of translation, reflection, scale, rotation and shearing can be described via a single \(3 \times 3\) matrix \(M\) such that \(P' = MP\), where \(P\) is a \(\begin{bmatrix}x & y & 1 \end{bmatrix}\) vector (with \(x\) and \(y\) being the original horizontal and vertical coordinates, respectively) and \(P'\) is a \(\begin{bmatrix}x' & y' & 1 \end{bmatrix}\), where \(x'\) and \(y'\) are the transformed coordinates. All geometry information must be described relative to the same reference origin point, from which transformations may occur. (Dimensions \(3 \times 3 \times t\), dimensionless quantity, using data type flt)

class aotpy.Time(uid: str, *, timestamps: list[float] = <factory>, frame_numbers: list[float] = <factory>)[source]

Bases: Referenceable

Contains data that describes the passage of time. All time in a system must be synchronous. Can be associated with time-varying data.

frame_numbers: list[float]

List of frame numbers at which the respective data applies. (in count units)

timestamps: list[float]

List of Unix timestamps at which the respective data applies. (in s units)

class aotpy.TipTiltMirror(uid: str, *, telescope: ~aotpy.core.telescope.Telescope, pupil_mask: ~aotpy.core.image.Image | None = None, tfz_num: list[float] = <factory>, tfz_den: list[float] = <factory>, transformation_matrix: ~aotpy.core.image.Image | None = None, aberration: ~aotpy.core.aberration.Aberration | None = None)[source]

Bases: WavefrontCorrector

Contains data related to a tip-tilt mirror in the system. It is assumed it has a two-axis movement.

n_valid_actuators: int = 2

Number of valid actuators in the corrector. (in count units)

class aotpy.WavefrontCorrector(uid: str, *, telescope: ~aotpy.core.telescope.Telescope, n_valid_actuators: int, pupil_mask: ~aotpy.core.image.Image | None = None, tfz_num: list[float] = <factory>, tfz_den: list[float] = <factory>, transformation_matrix: ~aotpy.core.image.Image | None = None, aberration: ~aotpy.core.aberration.Aberration | None = None)[source]

Bases: Referenceable

Abstract class that contains data related to a wavefront corrector in the system.

aberration: Aberration = None
n_valid_actuators: int

Number of valid actuators in the corrector. (in count units)

pupil_mask: Image = None

Binary image that describes the shape of the pupil. A 1 indicates the presence of the pupil, while a 0 indicates the opposite. (Dimensions \(h \times w\), dimensionless quantity, using data type int)

telescope: Telescope
tfz_den: list[float]

List of denominators of the transfer function Z. (dimensionless quantity)

tfz_num: list[float]

List of numerators of the transfer function Z. (dimensionless quantity)

transformation_matrix: Image = None

Matrix that defines 2-dimensional affine transformations over time (\(t\)) using homogeneous coordinates. Any combination of translation, reflection, scale, rotation and shearing can be described via a single \(3 \times 3\) matrix \(M\) such that \(P' = MP\), where \(P\) is a \(\begin{bmatrix}x & y & 1 \end{bmatrix}\) vector (with \(x\) and \(y\) being the original horizontal and vertical coordinates, respectively) and \(P'\) is a \(\begin{bmatrix}x' & y' & 1 \end{bmatrix}\), where \(x'\) and \(y'\) are the transformed coordinates. All geometry information must be described relative to the same reference origin point, from which transformations may occur. (Dimensions \(3 \times 3 \times t\), dimensionless quantity, using data type flt)

class aotpy.WavefrontSensor(uid: str, *, source: ~aotpy.core.source.Source, dimensions: int, n_valid_subapertures: int, measurements: ~aotpy.core.image.Image | None = None, ref_measurements: ~aotpy.core.image.Image | None = None, subaperture_mask: ~aotpy.core.image.Image | None = None, mask_offsets: list[~aotpy.core.base.Coordinates] = <factory>, subaperture_size: float | None = None, subaperture_intensities: ~aotpy.core.image.Image | None = None, wavelength: float | None = None, optical_gain: ~aotpy.core.image.Image | None = None, transformation_matrix: ~aotpy.core.image.Image | None = None, detector: ~aotpy.core.optical_sensor.Detector | None = None, aberration: ~aotpy.core.aberration.Aberration | None = None, non_common_path_aberration: ~aotpy.core.aberration.Aberration | None = None)[source]

Bases: Referenceable

Abstract class that contains data related to one wavefront sensor in the system.

aberration: Aberration = None
detector: Detector = None
dimensions: int

Number of dimensions being measured by each subaperture. (in count units)

mask_offsets: list[Coordinates]

List of horizontal/vertical offsets in detector pixels, represented as Coordinates. Each offset defines the lowest horizontal/vertical position occupied by the respective mask. (in pix units)

measurements: Image = None

Measurements from the sensor over time. Each of its \(s_v\) subapertures is able to measure in \(d\) dimensions. (Dimensions \(t \times d \times s_v\), in user defined units, using data type flt)

n_valid_subapertures: int

Number of valid subapertures (must coincide with subaperture_mask data). (in count units)

non_common_path_aberration: Aberration = None
optical_gain: Image = None

WFS optical gain over time. (Dimensions \(t\), dimensionless quantity, using data type flt)

ref_measurements: Image = None

Reference measurements. (Dimensions \(d \times s_v\), in user defined units, using data type flt)

source: Source
subaperture_intensities: Image = None

Detected average intensity (flux) of each of the \(s_v\) valid subapertures, over \(t\) time. (Dimensions \(t \times s_v\), in ADU units, using data type flt)

subaperture_mask: Image = None

Representation of the subaperture grid, where the cells corresponding to invalid subapertures are marked as \(-1\) and the cells corresponding to valid subapertures contain their respective index in the sequence of valid subapertures (using zero-based numbering, that is, the initial element is assigned the index 0). (Dimensions \(s \times s\), dimensionless quantity, using data type int)

subaperture_size: float = None

Size of each subaperture in detector pixels. (in pix units)

transformation_matrix: Image = None

Matrix that defines 2-dimensional affine transformations over time (\(t\)) using homogeneous coordinates. Any combination of translation, reflection, scale, rotation and shearing can be described via a single \(3 \times 3\) matrix \(M\) such that \(P' = MP\), where \(P\) is a \(\begin{bmatrix}x & y & 1 \end{bmatrix}\) vector (with \(x\) and \(y\) being the original horizontal and vertical coordinates, respectively) and \(P'\) is a \(\begin{bmatrix}x' & y' & 1 \end{bmatrix}\), where \(x'\) and \(y'\) are the transformed coordinates. All geometry information must be described relative to the same reference origin point, from which transformations may occur. (Dimensions \(3 \times 3 \times t\), dimensionless quantity, using data type flt)

wavelength: float = None

Wavelength being sensed. (in m units)

aotpy.verify_file(path: str | PathLike, log_level=AOTFITSErrorLevel.CRITICAL, exception_level=AOTFITSErrorLevel.CRITICAL, **kwargs)[source]