11institutetext:  Faculdade de Engenharia da Universidade do Porto, Rua Dr.
Roberto Frias, s/n, 4200-465 Porto, Portugal 22institutetext: Center for
Astrophysics and Gravitation, Instituto Superior Técnico, Av. Rovisco Pais 1,
1049-001 Lisboa, Portugal 33institutetext: Durham University (United Kingdom)
44institutetext: European Southern Observatory 55institutetext: Université
Paris-Saclay, Institut d’Optique Graduate School, CNRS, Laboratoire Charles
Fabry, 91127 Palaiseau, France 66institutetext: Aix Marseille Univ, CNRS,
CNES, LAM, Marseille, France

# Adaptive Optics Telemetry Standard

Design and specification of a novel data exchange format

Tiago Gomes 1122 Carlos M. Correia 1122 Lisa Bardou 33 Sylvain Cetre 33 Johann
Kolb 44 Caroline Kulcsár 55 François Leroux 66 Timothy Morris 33 Nuno Morujão
1122 Benoît Neichel 66 Jean-Luc Beuzit 66 Paulo Garcia 1122

(Received TBD; accepted TBD)

###### Abstract

Context. The amount of Adaptive Optics (AO) telemetry generated by VIS/NIR
ground-based observatories is ever greater, leading to a growing need for a
standardised data exchange format to support performance analysis and AO
research and development activities that involve large-scale telemetry mining,
processing, and curation.

Aims. This paper introduces the Adaptive Optics Telemetry (AOT) data exchange
format as a standard for sharing AO telemetry from visible/infrared ground-
based observatories. AOT is based on the Flexible Image Transport System
(FITS) and aims to provide unambiguous and consistent data access across
various systems and configurations, including natural and single/multiple
laser guide-star AO systems.

Methods. We designed AOT focused on two key use cases: atmospheric turbulence
parameter estimation and point-spread function reconstruction (PSF-R). We
prototyped and tested the design using existing AO telemetry datasets from
multiple systems: single conjugate with natural and laser guide stars,
tomographic systems with multi-channel wavefront sensors, single and multi
wavefront correctors in systems featuring either a Shack-Hartmann or Pyramid
as main wavefront sensors.

Results. The AOT file structure has been thoroughly defined, specifying data
fields, descriptions, data types, units, and expected dimensions. To support
this format, we have developed a Python package that enables data conversion,
reading, writing and exploration of AOT files, which has been made publicly
available and compatible with a general-purpose Python package manager. We
demonstrate the flexibility of the AOT format by packaging data from five
different instruments, installed on different telescopes.

###### Key Words.:

Adaptive Optics – Telemetry – Data Exchange Format – FITS – Data Model – PSF
reconstruction – Atmospheric turbulence

##  1 Introduction

The adoption and interest in Adaptive Optics (AO) for astronomy has increased
significantly in recent years. As a consequence, there has been a large
increase in observatories and researchers producing AO telemetry data. We use
the term “telemetry” to represent AO internal signals such as wavefront sensor
measurements, deformable mirror commands and several other reconstruction and
control matrices and parameters.

Recent developments have shown that AO telemetry data is of high scientific
interest, allowing for use-cases such as:

  * •

Advanced exploitation of scientific data - telemetry data can be used to
derive the state of the atmospheric turbulence during observations (Vidal et
al. 2010; Guesalaga et al. 2014; Martin et al. 2016; Jolissaint et al. 2018;
Laidlaw et al. 2019; Andrade et al. 2019). For situations where the point-
spread function (PSF) of the system is not available it allows to derive one,
with high accuracy (Veran et al. 1997; Gendron et al. 2006; Gilles et al.
2012; Beltramo-Martin et al. 2019; Fusco et al. 2020; Beltramo-Martin et al.
2020). These situations are very common nowadays, and related to high impact
science cases.

  * •

System performance estimation and runtime optimization - applications such as
fine-tuning of AO systems, advanced real-time strategies, wave-front
prediction or even scheduling of observations (Sivo et al. 2014; Petit et al.
2014; Sinquin et al. 2020).

  * •

Instrumentation research - for either established or newer teams without
direct access to AO instrumentation (Conan & Correia 2014; Muslimov et al.
2021).

Despite the demonstrated usefulness as a science product, AO telemetry has
been traditionally seen as “engineering data”, typically used internally for
one-off instrument commissioning or regular calibration (Hirst et al. 2020).
As a result of this, AO telemetry datasets are usually saved in private
archives that are out of reach for the end-user, or they may simply not be
kept in the long-term. Even in cases where third-parties can access telemetry
datasets, their documentation tends to be poor or non-existent. This is
problematic because each data-producing system may be saving different sets of
data, using different formats and providing access through different ways (in
some cases, even datasets generated by the same system are completely
distinct). As a result, the task of interpreting and analysing data is a huge
burden on the users and it is difficult to create data analysis programs that
can be generalised to multiple systems.

In light of this context, we consider that AO telemetry currently has a large
untapped potential that can be uncovered by broadening the access to this
data, in what we call the “hidden iceberg” of adaptive optics. Accordingly,
many systems are starting to show interest in saving and sharing such data.
One of the earliest examples of public archiving of AO telemetry was carried
out by the CANARY project (Myers et al. 2008), having made its open loop data
for the sodium laser guide star experiment (Bardou, Lisa et al. 2021)
available on the ESO Science Archive, using a data format that is extensively
detailed in an accompanying manual (Bardou, Lisa & Schulz, Christine 2018a,
b). The Gemini Observatory is planning on publishing one of the first large
scale archives of telemetry data (Hirst et al. 2020) (mostly composed of
wavefront slopes and DM commands), through the Gemini Observatory Archive
(Hirst & Cardenes 2016). However, publishing AO telemetry data currently
requires significant effort from the responsible teams, as they are forced to
design their own purpose-made data format, and make it available along with
proper documentation for their prospective users. While such formats represent
a significant step forward in data accessibility, given that they are tailored
specifically for one instrument/observatory, they typically make no attempts
at generalising support for multiple systems. In fact, to our knowledge, there
has been no major attempt in the AO community to establish a consensual data
format for AO telemetry to date.

We believe that access to AO telemetry data can only become ubiquitous by
having the bulk of the AO community agree on a common way of sharing their
data, that is, agreeing on a data exchange format. A data exchange format
essentially defines a set of attributes/fields, their meanings, the way they
relate to other data and the way they are stored in a shareable format. We
share our considerations on designing such a format in Sec.2.

With these considerations in mind, we propose the Adaptive Optics Telemetry
(AOT) data exchange format, built on top of the Flexible Image Transport
System (FITS) (Wells & Greisen 1979). This format draws some inspiration from
OIFITS (Pauls et al. 2004, 2005; Duvert et al. 2017), which was created as a
reaction to similar challenges that the interferometry community was facing.
This paper aims to discuss the thought process behind the design decisions and
to standardise this format by fully defining its details such as its
structure, the set of data that may be shared and their respective
definitions, conventions and units (Sec. 3). In Sec.4, we also discuss how
tools and data models can support the format by providing useful abstractions
for the users, on which a previous paper has been published (Gomes et al.
2022).

In summary, AOT aims to provide a common interface for AO telemetry data
access regardless of the specific data-producing system, its size (VLT-class,
ELT-class), the AO mode used (SCAO, SLAO, GLAO, MOAO, LTAO, MCAO), number and
type of wavefront sensors (Shack-Hartmann, Pyramid) and specific wavefront
correction setup (linear stages, tip-tilt mirrors, deformable mirrors). It is
envisioned as a convenient way of gathering relevant data from a single system
(which may have been produced by different instruments/devices, in different
subsystems) and packaging everything in a easily shareable format that is
well-understood. This means that AOT is not meant to replace the actual real-
time writing (dumping) of instrument data, but rather to be used as a data
processing step that makes such data digestible by its users. While the format
defines a large amount of fields that can describe the different aspects of
telemetry data, most of these are not mandatory; thus file sizes vary
significantly based on the needs of the user, the complexity of the system and
data reduction mechanisms that may have been applied.

This project is being developed in the context of OPTICON–RadioNet Pilot, an
European collaboration through which we aim to promote broad discussion and
consensus within the AO community. A set of proof-of-concept AOT files has
been made publicly available on both the ESO archive (for existing ESO
systems) and Zenodo.

The emphasized words ”must”, ”must not”, ”should”, ”should not”,
”recommended”, ”may”, and ”optional” in this document are to be interpreted as
described in RFC 2119 (Bradner 1997).

##  2 Format Considerations

The overall goal of this data exchange format is to lay the foundation to
allow easier data sharing of any interested teams and researchers in the
future. In other words, we aim to support the community’s need of treating AO
telemetry data as a science product. To achieve this, we need to create a
format that is widely used by the community. Since this requires support by
the many interested parts in the community, we paid special attention in
defining the set of use-cases that we want to support (Sec. 2.1) and a data
model that would streamline such usage (Sec. 2.2). We also pondered on the
suitable file formats for implementing that data model (Sec. 2.3). Overall,
our decision-making was guided by the design principles set in Appendix A.

###  2.1 Use-cases

To ensure that a format fits the user’s needs, it is essential to design it
around the specific use-cases it is intended to support, as that allows us to
verify its completeness for those purposes. In other words, these use-cases
enable a top-down approach to the design, as they directly imply a set of
requirements that must be satisfied. Although AO telemetry data has a wide
range of use-cases in astronomy, AOT will be designed with two main use-cases
in mind, which we intend to fully support: 1) atmospheric turbulence
parameters estimation and 2) point-spread function reconstruction (PSF-R).

We have looked into state-of-the-art algorithms for these use-cases to
guarantee that, to our knowledge, AOT is able to package all data that may be
relevant. AOT also specifies some data that, although not currently used for
these purposes, we expect may be necessary for future algorithms. Finally, AOT
can accommodate data that is not directly targeted at these specific use-
cases, but that may help broaden the format’s usefulness and potential
applications, or simply improve its convenience and user-friendliness. Despite
our primarily top-down approach, we also made sure to analyse datasets already
being created by existing systems; this bottom-up approach allowed us to
identify the types of data that the community currently prioritises and ensure
AOT can fill those needs.

It is important to note that science images are not a part of AOT. These are
already commonly shared within the astronomical community through fairly well-
established means, therefore there does not seem to be a benefit in sharing
them through a different format. Regardless, public data archives may choose
to provide science data along with AOT files, in separate files.

###  2.2 Data model

In the development of AOT, we designed a data model that attempts to
generalise the different parts that may compose an AO system and their
relationships, such that it can be used to describe a wide variety of system
configurations (including Single Conjugate, Single Laser, Ground Layer, Multi-
Object, Laser Tomography and Multi-Conjugate Adaptive Optics) and different
wavefront correction and sensing setups. This data model defines conceptual
relationships between the different sets of instruments and their data, with
the goal of providing an intuitive and simplified way of accessing data. An
overview of this data model can be seen in Fig. 1.

Figure 1:  Simplified UML Class Diagram representing the AOT data model. The
central AOSystem class can hold information about the entire system, via
references to its multiple parts. Classes represented via dashed rectangles
are abstract, and are implemented by the classes that inherit from them. For
simplicity, some inner classes have been omitted.

The AOT data model is agnostic both in terms of programming language and
specific file format, meaning it can be used as the basis for any
implementation of the format. An earlier version of this data model has been
discussed in greater detail in Gomes et al. (2022).

###  2.3 File format

While the AOT data model does not imply any specific file format, in this
paper we will provide the reference implementation of this data model in a
specific file format. Rather than creating our own file format, we believe it
is in the best interest of the astronomical community to opt for one that is
already commonly used in the community, as that allows us to leverage the high
degree of familiarity that astronomers already have with such file formats and
the widely available tools for creating, reading and editing them. Therefore,
we looked into established file formats that would be able to contain all the
necessary data while being easily shareable, namely: FITS (Wells & Greisen
1979), HDF5 (The HDF Group 1997-2022), VOTable (Ochsenbein et al. 2004) and
ASDF (Greenfield et al. 2015).

Ultimately, we opted to provide an implementation using the FITS standard. The
biggest driving factor in this decision was that we aimed to publish AOT data
on the ESO Science Archive, which currently only provides full support for
this format. Nonetheless, we acknowledge that FITS is an ageing standard that
can be a limiting in some particular scenarios (Thomas et al. 2015; Scroggins
& Boscoe 2020); therefore there might be interest in implementing the AOT data
model using other file formats in the future.

Significant familiarity with the FITS specification is necessary to fully
understand the AOT specification described in the following sections; with
that in mind, we provide an overview of the most relevant FITS concepts in
Appendix B.

##  3 Data Format

A standard AOT file fully adheres to the FITS specification; in other words, a
file that follows the AOT standard is also a standard FITS file. An AOT file
is composed of one specially formatted primary HDU with no data array (Sec.
3.1), followed by a specific set of binary table extensions (Sec. 3.2) and
possibly some image extensions (Sec. 3.3). A single AOT file is capable of
supporting all relevant information related to a single telemetry recording.
In the following sections, we use a set of AOT-specific conventions (see
Appendix E) that help describing the data format in detail.

###  3.1 Primary HDU

The primary HDU in an AOT file contains no data array. However, its header
contains a set of keywords that are used to provide metadata about the file
and its data in general, as described in Table 1. It is recommended that these
keywords are defined in the sequence described in the table, after all the
mandatory FITS keyword. Keywords that are not strictly mandatory may be
omitted or have null values.

Table 1: Primary Header of an AOT file.

Keyword | Type |  Description
---|---|---
AOT-VERS | str |  Its presence identifies the file as an AOT file and indicates the version of the format that it complies with, following Semantic Versioning (Preston-Werner 2013). For the current specification, the value must be ’2.0.0’.aa$a$Strictly mandatory (value must not be null).
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).aa$a$Strictly mandatory (value must not be null).
TIMESYS | str |  Defines the temporal reference frame for the entire file. Value must be ’UTC’.a,ba,bfootnotemark: $a,b$
DATE-BEG | str |  Start time of data acquisition in ISO derived format (see Appendix E.5).bb$b$All entries in this field must be unique.
DATE-END | str |  Stop time of data acquisition in ISO derived format (see Appendix E.5).bb$b$All entries in this field must be unique.
SYS-NAME | str |  Name of the AO system that produced the data.
STREHL-R | float |  Estimated Strehl ratio (arcsec).
FITT-ERR | float |  Estimated fitting error, in squared radians at the sensing wavelength.
ALIA-ERR | float |  Estimated aliasing error, in squared radians at the sensing wavelength.
NOIS-ERR | float |  Estimated photon/detector noise error, in squared radians at the sensing wavelength.
TEMP-ERR | float |  Estimated temporal error, in squared radians at the sensing wavelength.
OTHE-ERR | float |  Estimated other sources of error, in squared radians at the sensing wavelength.
CONFIG | str |  Free-form text that describes configuration parameters of the system.

111
bb$b$All entries in this field must be unique.Standard FITS keyword.

###  3.2 Binary tables

After the primary HDU, all AOT files files should contain a sequence of up to
17 specifically formatted binary table extensions. The names (EXTNAME) of
these tables must be:

  1. 1.

AOT_TIME

  2. 2.

AOT_ATMOSPHERIC_PARAMETERS

  3. 3.

AOT_ABERRATIONS

  4. 4.

AOT_TELESCOPES

  5. 5.

AOT_SOURCES

  6. 6.

AOT_SOURCES_SODIUM_LGS

  7. 7.

AOT_SOURCES_RAYLEIGH_LGS

  8. 8.

AOT_DETECTORS

  9. 9.

AOT_SCORING_CAMERAS

  10. 10.

AOT_WAVEFRONT_SENSORS

  11. 11.

AOT_WAVEFRONT_SENSORS_SHACK_HARTMANN

  12. 12.

AOT_WAVEFRONT_SENSORS_PYRAMID

  13. 13.

AOT_WAVEFRONT_CORRECTORS

  14. 14.

AOT_WAVEFRONT_CORRECTORS_DM

  15. 15.

AOT_LOOPS

  16. 16.

AOT_LOOPS_CONTROL

  17. 17.

AOT_LOOPS_OFFLOAD

The tables in bold are the ”mandatory tables” and they must always exist in
the file, even if they contain no rows. The remaining are ”secondary tables”
and they are related to the mandatory tables with which they share part of the
name (e.g. AOT_LOOPS_CONTROL is related to AOT_LOOPS). If an entry in an
secondary table shares the UID with an entry in the mandatory table it is
related to, then both entries describe the same object: in that case, the
mandatory table holds general data about the object, while the secondary table
stores data corresponding to the object’s specific sub-type. All secondary
tables are optional, meaning that they may be omitted if they would otherwise
be empty (that is, if no elements of that particular sub-type exist).

It is strongly recommended that the binary tables in AOT files follow the
specified sequence; they are ordered in this way in order to ensure that, when
reading sequentially, tables that may be referenced by entries on a certain
field have always been read previously. However, the order of the rows inside
each table is irrelevant; tables that have the same rows ordered differently
are considered equivalent.

In the following sections, we will define the purpose of each of these binary
table extensions and their contents. It is recommended that all of the
specified table fields exist (even if all of their entries are null) and that
they follow their defined sequence. An AOT file must adhere to the name and
type of each field defined in the tables of these sections (through the
TTYPE$n$, TFORM$n$ keywords, respectively). It is recommended that the data
follows the unit of measurement specified in the table and that it is
specified through the TUNIT$n$ keyword; if an alternative unit of measurement
is used, it must be specified through that same keyword. The description of
each field (provided in the tables) may be saved in the AOT file through a
TCOMM$n$ keyword.

####  3.2.1 AOT_TIME

The fields of this binary table are described in Table 2.

This table allows the user to relate time-varying data to their corresponding
progress of time. Specifically, each row in this table specifies moments at
which some data-points occurred, allowing fields or image extension that
describe time-varying data to then directly reference their corresponding row.

The time instants in this table must be defined through synchronised Unix
timestamps and/or through a synchronised frame number, such that two data
points that occurred simultaneously always share the same timestamp/frame
number. If in one row both a list of timestamps and frame numbers are
provided, they must share the same length.

Table 2: AOT_TIME fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the set of time data.a,ba,bfootnotemark: $a,b$
TIMESTAMPS | lst | s |  List of Unix timestamps at which the respective data applies (see Appendix E.5).cc$c$For each row in the table, at least one of the entries in these fields must not be null; if both are not null, they must have the same length.
FRAME_NUMBERS | lst | count |  List of frame numbers at which the respective data applies.cc$c$For each row in the table, at least one of the entries in these fields must not be null; if both are not null, they must have the same length.

222

####  3.2.2 AOT_ATMOSPHERIC_PARAMETERS

The fields of this binary table are described in Table 3.

Each row in this table describes a set of relevant atmospheric parameters that
were obtained from a certain data source. Data source is identified via the
UID field and the reference wavelength of the data is defined in WAVELENGTH.
Then, time data may be associated via TIME_UID and, for each of those
instances, data regarding the overall seeing and conditions of each turbulence
layer may also be defined.

Table 3: AOT_ATMOSPHERIC_PARAMETERS fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the data source for these atmospheric parameters.a,ba,bfootnotemark: $a,b$
WAVELENGTH | flt | m |  Reference wavelength.
TIME_UID | str | n.a. |  AOT_TIME row-reference.
R0 | lst | m |  List of Fried parameters at reference wavelength at zenith, over time.
SEEING | lst | arcsec |  List of full width at half maximum measures of the seeing disc at reference wavelength at zenith, over time.
TAU0 | lst | s |  List of atmospheric coherence times at reference wavelength at zenith, over time.
THETA0 | lst | rad |  List of isoplanatic angles at reference wavelength, over time.
LAYERS_REL_WEIGHT | str | n.a. |  Image-reference.
LAYERS_HEIGHT | str | n.a. |  Image-reference.
LAYERS_L0 | str | n.a. |  Image-reference.
LAYERS_WIND_SPEED | str | n.a. |  Image-reference.
LAYERS_WIND_DIRECTION | str | n.a. |  Image-reference.
TRANSFORMATION_MATRIX | str | n.a. |  Image-reference.

333
$b$$b$footnotetext: All entries in this field must be unique.

####  3.2.3 AOT_ABERRATIONS

The fields of this binary table are described in Table 4.

This table defines data that allows for the description of optical aberrations
that may exist in different parts of the AO system. Rows may be referenced by
Wavefront Sensors, Scoring Cameras or Wavefront Correctors, and they contain
data that defines a set of aberrations related to that device.

In each row, the MODES field provides a reference to a 3D image, which is
interpreted as a set of $n$ 2D images representing the orthonormal basis of
modes for this row. Then, the COEFFICIENTS field provides a reference to a 2D
image that contains $n$ columns, each containing the coefficient for that
particular basis, with as many rows as necessary to describe the different
aberrations that may occur at different field offsets. The field offsets for
these aberrations are specified by the X_OFFSETS and Y_OFFSETS lists, which
provide an horizontal and vertical offset for each set of coefficients. For
each field offset, the user is able to calculate the overall optical
aberration by multiplying each mode basis by its respective coefficients for
that field offset, and summing those results.

If no field offsets are specified, there may only be one row of coefficients,
which is assumed to be representative of the average field offset.

Table 4: AOT_ABERRATIONS fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the aberration.a,ba,bfootnotemark: $a,b$
MODES | str | n.a. |  Image-reference.aa$a$Strictly mandatory (value must not be null).Strictly mandatory (value must not be null).
COEFFICIENTS | str | n.a. |  Image-reference.aa$a$Strictly mandatory (value must not be null).
X_OFFSETS | lst | rad |  List of horizontal offsets from the centre of the field.cc$c$For each row in the table, entries in these fields must have the same length, equal to the number of sets of coefficients specified.
Y_OFFSETS | lst | rad |  List of vertical offsets from the centre of the field.cc$c$For each row in the table, entries in these fields must have the same length, equal to the number of sets of coefficients specified.

444
$b$$b$footnotetext: All entries in this field must be unique.

####  3.2.4 AOT_TELESCOPES

The fields of this binary table are described in Table 5.

This table describes all telescopes in the AO system, with each one being
either a Main Telescope (that is, the telescope performing the observation
itself) or a Laser Launch Telescope (LLT, which generates one or more laser
guide stars). There must be exactly one Main Telescope, and all LLTs should be
referenced by at least one laser guide star.

Table 5: AOT_TELESCOPES fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the telescope.a,ba,bfootnotemark: $a,b$
TYPE | str | n.a. |  Indicates the type of telescope (either ’Main Telescope’ or ’Laser Launch Telescope’).aa$a$Strictly mandatory (value must not be null).
LATITUDE | flt | deg |  Latitude of the telescope (World Geodetic System).
LONGITUDE | flt | deg |  Longitude of the telescope (World Geodetic System).
ELEVATION | flt | deg |  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).
AZIMUTH | flt | deg |  Azimuth of the telescope at start, the angle of the object around the horizon with 0° being North, increasing eastward (horizontal coordinate system).
PARALLACTIC | flt | deg |  Parallactic angle, the spherical angle between the hour circle and the great circle through a celestial object and the zenith.
PUPIL_MASK | str | n.a. |  Image-reference.
PUPIL_ANGLE | flt | rad |  Clockwise rotation of the pupil mask.
ENCLOSING_D | flt | m |  Diameter of the smallest circle that contains the entirety of the pupil (enclosing circle).
INSCRIBED_D | flt | m |  Diameter of the largest circle that can be contained in the pupil (inscribed circle). On monolithic circular pupils this is equivalent to ENCLOSING_D.
OBSTRUCTION_D | flt | m |  Diameter of the smallest circle that contains the entire central obstruction.
SEGMENTS_TYPE | str | n.a. |  Describes the type of the segments that constitute the pupil. Value must be ’Monolithic’ if the pupil is monolithic, ’Hexagon’ if the segments are hexagons or ’Circle’ if the segments are circles.aa$a$Strictly mandatory (value must not be null).
SEGMENTS_SIZE | flt | m |  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 must be null.
SEGMENTS_X | lst | m |  List of horizontal coordinates of each segment in the pupil.cc$c$List must have the same length as the total number of segments (or be empty if the pupil is monolithic). The origin of the coordinates is the centre of the inscribed circle.
SEGMENTS_Y | lst | m |  List of vertical coordinates of each segment in the pupil.cc$c$List must have the same length as the total number of segments (or be empty if the pupil is monolithic). The origin of the coordinates is the centre of the inscribed circle.
TRANSFORMATION_MATRIX | str | n.a. |  Image-reference.
ABERRATION_UID | str | n.a. |  AOT_ABERRATIONS row-reference.

555
$b$$b$footnotetext: All entries in this field must be unique.

####  3.2.5 AOT_SOURCES

The fields of this binary table are described in Table 6.

This table describes all light sources in the system, which may be of 4
different types: Science Star, Natural Guide Star (NGS), Sodium Laser Guide
Star or Rayleigh Laser Guide Star. Astronomical coordinates for the sources
may be provided. Both types of Laser Guide Star (LGS) sources may provide
secondary data through the Tables 7 or 8, respectively.

Table 6: AOT_SOURCES fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the light source.a,ba,bfootnotemark: $a,b$
TYPE | str | n.a. |  Indicates the type of light source (either ’Science Star’, ’Natural Guide Star’, ’Sodium Laser Guide Star’ or ’Rayleigh Laser Guide Star’).aa$a$Strictly mandatory (value must not be null).
RIGHT_ASCENSION | flt | deg |  Right ascension of the light source, epoch J2000 (equatorial coordinate system).
DECLINATION | flt | deg |  Declination of the light source, epoch J2000 (equatorial coordinate system).
ELEVATION_OFFSET | flt | deg |  Offset from the Main Telescope’s ELEVATION.
AZIMUTH_OFFSET | flt | deg |  Offset from the Main Telescope’s AZIMUTH.
WIDTH | flt | rad |  Effective width at zenith.

666
$b$$b$footnotetext: All entries in this field must be unique.

Table 7: AOT_SOURCES_SODIUM_LGS fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the light source.a,ba,bfootnotemark: $a,b$
HEIGHT | flt | m |  Mean LGS height above sea level at zenith.
PROFILE | str | n.a. |  Image-reference.
ALTITUDES | lst | m |  LGS layer profile altitudes at zenith. Must be the same length as the number of layers defined in PROFILE.
LLT_UID | str | n.a. |  AOT_TELESCOPES row-reference, which contains data related to the LLT used to generate the source. Referenced row must have TYPE=’Laser Launch Telescope’.

777
Secondary table exclusively for sources of type ’Sodium Laser Guide Star’. If
there are entries of this type in the mandatory table, there must also exist
an entry with the same UID in this table.
$b$$b$footnotetext: All entries in this field must be unique.

Table 8: AOT_SOURCES_RAYLEIGH_LGS fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the light source.a,ba,bfootnotemark: $a,b$
DISTANCE | flt | m |  Fixed distance of the LGS from the telescope.
DEPTH | flt | m |  Range covered by the laser light while the shutter is opened.
LLT_UID | str | n.a. |  AOT_TELESCOPES row-reference, which contains data related to the LLT used to generate the source. Referenced row must have TYPE=’Laser Launch Telescope’.

888
Secondary table exclusively for sources of type ’Rayleigh Laser Guide Star’.
If there are entries of this type in the mandatory table, there must also
exist an entry with the same UID in this table.
$b$$b$footnotetext: All entries in this field must be unique.

####  3.2.6 AOT_DETECTORS

The fields of this binary table are described in Table 9.

Data related to the physical characteristics and configurations of a detector,
as well as the actual pixels recorded by it, may be saved in this table. All
rows should describe detectors that are referenced by Wavefront Sensors or
Scoring Cameras.

Table 9: AOT_DETECTORS fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the detector.a,ba,bfootnotemark: $a,b$
TYPE | str | n.a. |  Identifies the type of detector, such as ’CMOS’ or ’CCD’.
SAMPLING_TECHNIQUE | str | n.a. |  Identifies the sampling technique, for example ’Single Reset Read’, ’Fowler’, ’Double Correlated’, ’Uncorrelated’.
SHUTTER_TYPE | str | n.a. |  Identifies the shutter type, typically ’Rolling’ or ’Global’.
FLAT_FIELD | str | n.a. |  Image-reference.
READOUT_NOISE | flt |  e- s-1 pix-1 |  Digital detector read noise generated by its output amplifier in photo-electrons / second / pixel.
PIXEL_INTENSITIES | str | n.a. |  Image-reference.
FIELD_CENTRE_X | flt | pix |  Defines the horizontal coordinate of the detector pixel on which the centre of the field is projected.dd$d$A fractional value implies the centre is located in-between two pixels.
FIELD_CENTRE_Y | flt | pix |  Defines the vertical coordinate of the detector pixel on which the centre of the field is projected.dd$d$A fractional value implies the centre is located in-between two pixels.
INTEGRATION_TIME | flt | s |  Duration in seconds a pixel integrates flux, independent of the detector reading scheme.
COADDS | int | count |  Number of frame co-additions.
DARK | str | n.a. |  Image-reference.
WEIGHT_MAP | str | n.a. |  Image-reference.
QUANTUM_EFFICIENCY | flt | n.a. |  A 0–1 scalar indicating the ability to convert a photon into a usable electron. Quoted at the central wavelength as an effective value.
PIXEL_SCALE | flt |  rad pix-1 |  Resolution in radians per detector pixel.
BINNING | int | count |  Integer value indicating the 2D pixel combination by the binning factor
BANDWIDTH | flt | m |  Width of the filter/bandpass of the optics+detector.
TRANSMISSION_WAVELENGTH | lst | m |  List of wavelengths that describe a transmission profile.cc$c$For each row in the table, entries in these fields must have the same length, equal to the number of wavelengths at which transmission was calculated.
TRANSMISSION | lst | n.a. |  List of transmission percentages that describe a transmission profile.cc$c$For each row in the table, entries in these fields must have the same length, equal to the number of wavelengths at which transmission was calculated.
SKY_BACKGROUND | str | n.a. |  Image-reference.
GAIN | flt |  e- |  Scalar magnitude of detector signal amplification.
EXCESS_NOISE | flt |  e- |  Photon-noise gain factor (scalar) as a result of the electron-multiplied gain amplification in EMCCDs
FILTER | str | n.a. |  Name of filter in use.
BAD_PIXEL_MAP | str | n.a. |  Image-reference.
DYNAMIC_RANGE | flt | dB |  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.
READOUT_RATE | flt |  pix s-1 |  Inverse of the time required to digitize a single pixel.
FRAME_RATE | flt |  frame s-1 |  Inverse of the time needed for the detector to acquire an image and then completely read it out.
TRANSFORMATION_MATRIX | str | n.a. |  Image-reference.

999
$b$$b$footnotetext: All entries in this field must be unique.

####  3.2.7 AOT_SCORING_CAMERAS

The fields of this binary table are described in Table 10. Some general
information about each scoring camera in the system may be provided here.
Scoring cameras are able to reference the detector being used and an existing
optical aberration.

Table 10: AOT_SCORING_CAMERAS fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the camera.a,ba,bfootnotemark: $a,b$
PUPIL_MASK | str | n.a. |  Image-reference.
WAVELENGTH | flt | m |  Observation wavelength
TRANSFORMATION_MATRIX | str | n.a. |  Image-reference.
DETECTOR_UID | str | n.a. |  AOT_DETECTORS row-reference.
ABERRATION_UID | str | n.a. |  AOT_ABERRATIONS row-reference.

101010
$b$$b$footnotetext: All entries in this field must be unique.

####  3.2.8 AOT_WAVEFRONT_SENSORS

The fields of this binary table are described in Table 11.

This table contains data for all wavefront sensors in the system, which may be
Shack-Hartmann or Pyramid. Wavefront sensors are able to reference the
detector being used and an existing optical aberration. Wavefront sensors may
also define the non-common path aberration between them and the science
detector. Rows must reference the source that they are sensing. Each wavefront
sensor may be referenced by multiple controls loops that interact with it.

Both types of wavefront sensors may provide secondary data through the tables
12 or 13.

SUBAPERTURE_MASK, MASK_X_OFFSETS, MASK_Y_OFFSETS and SUBAPERTURE_SIZE together
describe the relationship between the detector’s pixels and the wavefront
sensor’s subapertures. This mechanism is exemplified in Fig. 2.

Table 11: AOT_WAVEFRONT_SENSORS fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the wavefront sensor.a,ba,bfootnotemark: $a,b$
TYPE | str | n.a. |  Indicates the type of wavefront sensor (either ’Shack-Hartmann’ or ’Pyramid’).aa$a$Strictly mandatory (value must not be null).Strictly mandatory (value must not be null).Strictly mandatory (value must not be null).Strictly mandatory (value must not be null).
SOURCE_UID | str | n.a. |  AOT_SOURCES row-reference. Indicates source being sensed.aa$a$Strictly mandatory (value must not be null).
DIMENSIONS | int | count |  Number of dimensions being measured by each subaperture. For ’Shack-Hartmann’ this must be equal to 2 (horizontal and vertical offset). For ’Pyramid’ this must be equal to either 2 (if the signals are also interpreted as horizontal and vertical offsets), 1 (if the subapertures overlap and are interpreted as a single signal) or the number of sides of the pyramid (that is, N_SIDES signals).aa$a$Strictly mandatory (value must not be null).
N_VALID_SUBAPERTURES | int | count |  Number of valid subapertures (must coincide with SUBAPERTURE_MASK data).aa$a$Strictly mandatory (value must not be null).
MEASUREMENTS | str | n.a. |  Image-reference.
REF_MEASUREMENTS | str | n.a. |  Image-reference.
SUBAPERTURE_MASK | str | n.a. |  Image-reference.
MASK_X_OFFSETS | lst | pix |  List of horizontal offsets in detector pixels. Each offset defines the lowest horizontal position occupied by the respective mask. cc$c$For each row in the table, entries in these fields must have the same length, equal to the number of masks projected on the detector pixels (there must be one mask for ’Shack-Hartmann’ and as many as the number of pyramid sides for ’Pyramid’).
MASK_Y_OFFSETS | lst | pix |  List of vertical offsets in detector pixels. Each offset defines the lowest vertical position occupied by the respective mask. cc$c$For each row in the table, entries in these fields must have the same length, equal to the number of masks projected on the detector pixels (there must be one mask for ’Shack-Hartmann’ and as many as the number of pyramid sides for ’Pyramid’).
SUBAPERTURE_SIZE | flt | pix |  Size of each subaperture in detector pixels.
SUBAPERTURE_INTENSITIES | str | n.a. |  Image-reference.
WAVELENGTH | flt | m |  Wavelength being sensed.
OPTICAL_GAIN | str | n.a. |  Image-reference.
TRANSFORMATION_MATRIX | str | n.a. |  Image-reference.
DETECTOR_UID | str | n.a. |  AOT_DETECTORS row-reference.
ABERRATION_UID | str | n.a. |  AOT_ABERRATIONS row-reference.
NCPA_UID | str | n.a. |  AOT_ABERRATIONS row-reference, which describes the non-common path aberrations between the wavefront sensor and science detector.

111111
$b$$b$footnotetext: All entries in this field must be unique.

Table 12: AOT_WAVEFRONT_SENSORS_SHACK_HARTMANN fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the wavefront sensor.a,ba,bfootnotemark: $a,b$
CENTROIDING_ALGORITHM | str | n.a. |  Name of the centroiding algorithm used.
CENTROID_GAINS | str | n.a. |  Image-reference.
SPOT_FWHM | str | n.a. |  Image-reference.

121212
Secondary table exclusively for wavefront sensors of type ’Shack-Hartmann’. If
there are entries of this type in the mandatory table, there must also exist
an entry with the same UID in this table.
$b$$b$footnotetext: All entries in this field must be unique.

Table 13: AOT_WAVEFRONT_SENSORS_PYRAMID fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the wavefront sensor.a,ba,bfootnotemark: $a,b$
N_SIDES | int | count |  Number of pyramid sides (typically 4).
MODULATION | flt | m |  Modulation amplitude.

131313
Secondary table exclusively for wavefront sensors of type ’Pyramid’. If there
are entries of this type in the mandatory table, there must also exist an
entry with the same UID in this table.
$b$$b$footnotetext: All entries in this field must be unique.

(a) Example $80\times 80$ PIXEL_INTENSITIES image from the wavefront sensor’s
detector.

(b) Example $4\times 4$ SUBAPERTURE_MASK for a wavefront sensor with 12 valid
subapertures. Cells with value $-1$ indicate an invalid subaperture, while the
others indicate the index of that subaperture in the sensor data.

(c) SUBAPERTURE_MASK superimposed over PIXEL_INTENSITIES. In this case,
MASK_X_OFFSETS and MASK_Y_OFFSETS have length one, indicating that the mask is
superimposed once, and its lowermost positions in X and Y are 13 and 8,
respectively. SUBAPERTURE_SIZE defines each subaperture as corresponding to 16
pixels.

Figure 2: Diagram showing how the relationship between wavefront sensor
subapertures and detector pixels can be deduced from SUBAPERTURE_MASK,
MASK_X_OFFSETS, MASK_Y_OFFSETS and SUBAPERTURE_SIZE.

####  3.2.9 AOT_WAVEFRONT_CORRECTORS

The fields of this binary table are described in Table 14.

This table contains data for all wavefront correctors in the system, which may
be Linear Stages (a correction that is applied in only one axis, usually
focus), Tip-Tilt Mirrors (TTM, which correct in two axis, tip and tilt) or
Deformable Mirrors (DM, which can correct multiple aberrations).

Rows in this table may reference relevant optical aberrations that may exist.
They must reference the telescope in which the corrector is installed. Each
row may be referenced by multiple system loops that interact with the
corrector.

Deformable mirrors may provide secondary data through Table 15.

Table 14: AOT_WAVEFRONT_CORRECTORS fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the wavefront corrector.a,ba,bfootnotemark: $a,b$
TYPE | str | n.a. |  Indicates the type of wavefront corrector (either ’Deformable Mirror’, ’Tip-Tilt Mirror’ or ’Linear Stage’).aa$a$Strictly mandatory (value must not be null).Strictly mandatory (value must not be null).
TELESCOPE_UID | str | n.a. |  AOT_TELESCOPES row-reference. Indicates which telescope the corrector is installed on.aa$a$Strictly mandatory (value must not be null).
N_VALID_ACTUATORS | int | count |  Number of valid actuators in the corrector. This must be 1 for ’Linear Stage’, 2 for ’Tip-Tilt Mirror’.
PUPIL_MASK | str | n.a. |  Image-reference.
TFZ_NUM | lst | n.a. |  List of numerators of the transfer function Z.
TFZ_DEN | lst | n.a. |  List of denominators of the transfer function Z.
TRANSFORMATION_MATRIX | str | n.a. |  Image-reference.
ABERRATION_UID | str | n.a. |  AOT_ABERRATIONS row-reference.

141414
$b$$b$footnotetext: All entries in this field must be unique.

Table 15: AOT_WAVEFRONT_CORRECTORS_DM fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the wavefront corrector.a,ba,bfootnotemark: $a,b$
ACTUATORS_X | lst | m |  List of horizontal coordinates of the valid actuators of the DM.cc$c$For each row in the table, entries in these fields must have the same length, equal to the number of valid actuators as defined by N_VALID_ACTUATORS.
ACTUATORS_Y | lst | m |  List of vertical coordinates of the valid actuators of the DM.cc$c$For each row in the table, entries in these fields must have the same length, equal to the number of valid actuators as defined by N_VALID_ACTUATORS.
INFLUENCE_FUNCTION | str | n.a. |  Image-reference.
STROKE | flt | m |  Maximum possible actuator displacement, measured as an excursion from a central null position.

151515
Secondary table exclusively for wavefront correctors of type ’Deformable
Mirror’. If there are entries of this type in the mandatory table, there must
also exist an entry with the same UID in this table.
$b$$b$footnotetext: All entries in this field must be unique.

####  3.2.10 AOT_LOOPS

This binary table is described in Table 16.

Each row in the table aggregates data related to one system loop. In this
context, loops are understood as the conceptual mechanism through which the
RTC periodically gathers data from a certain input, performs some calculation
in those data, and outputs a set of commands to some sort of wavefront
corrector.

Rows may describe Control Loops, in which wavefront data (as sensed by a
wavefront sensor) are taken as the input, from which the RTC calculates the
necessary adjustments to a wavefront corrector (commands), based on
interaction and control matrices. Alternatively, rows may describe Offload
Loops, which take the set of commands received by one wavefront corrector as
the input and, based on a offload matrix, output commands to another wavefront
corrector (offloading the commands).

In the real-world, an AO loop may command multiple wavefront correctors based
on a single wavefront sensor, or even multiple wavefront sensors may be used
to command a single wavefront corrector (many-to-many relationships). While by
design each row in this table can only describe a one-to-one relationship, AOT
can still be used to describe many-to-many relationships. This is achieved by
creating multiple conceptual loops that represent the same real-world loop,
each having different inputs or outputs, as necessary to fully describe the
loop 111For example, if a real-world AO loop uses a single wavefront sensor to
command multiple wavefront correctors, we can have one control loop row for
each wavefront corrector being commanded. These rows will all reference the
same wavefront sensor as input, but their output wavefront corrector will
differ, as will the control matrices and commands accordingly. The overhead
for this is minimal, given that the duplicated data will be composed almost
entirely of references.

Given that control loops must reference the wavefront sensor and wavefront
corrector being used (which themselves must reference a source and a telescope
respectively), the data chain related to a control loop can be fully explored
through references, allowing the user to study how these elements interact.

Table 16: AOT_LOOPS fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the loop.a,ba,bfootnotemark: $a,b$
TYPE | str | n.a. |  Indicates the type of loop (either ’Control Loop’ or ’Offload Loop’).aa$a$Strictly mandatory (value must not be null).
COMMANDED_UID | str | n.a. |  AOT_WAVEFRONT_CORRECTORS row-reference. This identifies the wavefront corrector that is being commanded by this loop.aa$a$Strictly mandatory (value must not be null).
TIME_UID | str | n.a. |  AOT_TIME row-reference.
STATUS | str | n.a. |  Values must be ’Open’ or ’Closed’, indicating whether the loop was opened or closed for the duration of the data collection.
COMMANDS | str | n.a. |  Image-reference.
REF_COMMANDS | str | n.a. |  Image-reference.
FRAMERATE | flt | Hz |  Frequency at which the loop operates.
DELAY | flt | frame |  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.
TIME_FILTER_NUM | str | n.a. |  Image-reference.
TIME_FILTER_DEN | str | n.a. |  Image-reference.

161616
$b$$b$footnotetext: All entries in this field must be unique.

Table 17: AOT_LOOPS_CONTROL fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the loop.a,ba,bfootnotemark: $a,b$
INPUT_SENSOR_UID | str | n.a. |  AOT_WAVEFRONT_SENSORS row-reference, which contains input data used to calculate commands, based on the CONTROL_MATRIX.aa$a$Strictly mandatory (value must not be null).
MODES | str | n.a. |  Image-reference.
MODAL_COEFFICIENTS | str | n.a. |  Image-reference.
CONTROL_MATRIX | str | n.a. |  Image-reference.
MEASUREMENTS_TO_MODES | str | n.a. |  Image-reference.
MODES_TO_COMMANDS | str | n.a. |  Image-reference.
INTERACTION_MATRIX | str | n.a. |  Image-reference.
COMMANDS_TO_MODES | str | n.a. |  Image-reference.
MODES_TO_MEASUREMENTS | str | n.a. |  Image-reference.
RESIDUAL_COMMANDS | str | n.a. |  Image-reference.

171717
Secondary table exclusively for loops of type ’Control Loop’. If there are
entries of this type in the mandatory table, there must also exist an entry
with the same UID in this table.
$b$$b$footnotetext: All entries in this field must be unique.

Table 18: AOT_LOOPS_OFFLOAD fields.

Name | Type | Unit |  Description
---|---|---|---
UID | str | n.a. |  Unique ID that identifies the loop.a,ba,bfootnotemark: $a,b$
INPUT_CORRECTOR_UID | str | n.a. |  AOT_WAVEFRONT_CORRECTORS row-reference, from which commands are offloaded, based on the OFFLOAD_MATRIX.aa$a$Strictly mandatory (value must not be null).
OFFLOAD_MATRIX | str | n.a. |  Image-reference.

181818
Secondary table exclusively for loops of type ’Offload Loop’. If there are
entries of this type in the mandatory table, there must also exist an entry
with the same UID in this table.
$b$$b$footnotetext: All entries in this field must be unique.

###  3.3 Images

In AOT, multidimensional data is always stored in images extensions that may
be referenced. These image extensions may be contained in the AOT file itself
(after all the binary tables), or in separate FITS files (see Appendix E.3).

There are 35 different categories of images that may be referenced, as seen in
Table 3.3. For each image category, the table specifies the data type, their
expected dimensions, their units and a description that characterises the
data. In a single AOT file there may be any number of images of the same
category and the same image may be referenced by multiple entries. This means
that, in cases where different table rows need to reference the exact same
multidimensional data, it is highly recommended that only a single image
extension is created for that data, avoiding data duplication. Images that are
never referenced in the file should not be included.

As mentioned in Appendix E.3, each image extension must have a unique non-null
name (as set through EXTNAME), which is defined by the user. It is recommended
that images are named in a way that allows the file to be self-explanatory.
Image extensions must respect the data type (as set through BITPIX) and
dimensions (as set through NAXIS) specified in the table. If the unit of
measurement of the data in a certain image is not specified (through BUNIT),
it is assumed it follows the table specification; if it is different from the
specification, the unit must be specified (through BUNIT). Whenever the unit
of an image does not follow the specification, it is recommended that it is
kept consistent with other images of the same category, as well as related
image categories. Users are free to further describe the contents of an image
extension through the addition of any user-defined metadata keywords in the
header, as long as the FITS specification is respected.

All images may have a $t$ dimension (defined after all the dimensions
specified in Table 3.3); in such cases, the data in that image is understood
to be time-varying. It is recommended that time-varying images contain a
TIME_UID keyword in their header, whose value is a AOT_TIME row-reference.
This row must have time data of the same length as the $t$ dimension, allowing
the user to relate the data to the specific instants it applies to. If an
image is not time-varying (e.g. it applies to the entire recording, or it
describes average values over the relevant timeframe rather than the values at
a specific instant), the $t$ dimension may be omitted and the TIME_UID keyword
must not be present. Although technically supported, we recommend not saving
time-varying images containing AOT_TIME row-references externally (for
example, to be used as external image-references, as described in Appendix
E.3); this is because the row-reference has no meaning outside the particular
AOT file. Overall, external image-references are better suited to avoid data
duplication for images which remain unchanged throughout multiple observations
(that is, typically images that contain non-time-varying data).

List of possible image categories. |  |  |  |
---|---|---|---|---
Image category | Type | Dimensions ($\times t$) | Unit |  Description
Referenceable in multiple tables
TRANSFORMATION_MATRIX | flt | $3\times 3$ | n.a. |  Matrix that defines 2-dimensional affine transformations using homogeneous coordinates. For more detail see Appendix E.6.
PUPIL_MASK | int | $w\times h$ | n.a. |  Binary image that describes the shape of the pupil. A 1 indicates the presence of the pupil, while a 0 indicates the opposite.
MODES | flt | $w\times h\times m$ | n.a. |  Set of $m$ different $w\times h$ arrays, each representing the orthonormal basis of the corresponding mode.
AOT_ATMOSPHERIC_PARAMETERS
LAYERS_WEIGHT | flt | $l$ | n.a. |  Fractional weight of each $l$ turbulence layer (sums to 1).
LAYERS_HEIGHT | flt | $l$ | m |  Height above observatory at zenith of each $l$ turbulence layer.
LAYERS_L0 | flt | $l$ | m |  Outer scale of turbulence at reference wavelength at zenith of each $l$ turbulence layer.
LAYERS_WIND_SPEED | flt | $l$ |  ms-1 |  Wind speed of each $l$ turbulence layer.
LAYERS_WIND_DIRECTION | flt | $l$ | deg |  Wind direction of each $l$ turbulence layer, with 0° being North, increasing eastward.
AOT_ABERRATIONS
COEFFICIENTS | flt | $n\times m$ | u.d. |  Set of $m$ coefficients (one for each of the orthonormal basis of modes) for each $n$ pupil offset.
AOT_SOURCES_SODIUM_LGS
PROFILE | flt | $l$ | n.a. |  Normalised LGS profile (each set of $l$ layers $\sum=1$) at zenith.
AOT_DETECTORS
FLAT_FIELD | flt | $w\times h$ | n.a. |  Inverse of the detector pixel-to-pixel sensitivity.
PIXEL_INTENSITIES | flt | $w\times h$ | ADU |  Intensity detected in each pixel, for each data frame. This is an image spanning $w$ pixels horizontally and $h$ pixels vertically.
DARK | flt | $w\times h$ | ADU |  Intensity detected in each pixel when there is no light being observed. This is an image spanning $w$ pixels horizontally and $h$ pixels vertically.
WEIGHT_MAP | flt | $w\times h$ | n.a. |  Pixel weight map, where each detector pixel is associated with a number that represents its relative value. Summing up to 1.
SKY_BACKGROUND | flt | $w\times h$ | ADU |  Detector pixel intensities from a source-less direction in the sky.
BAD_PIXEL_MAP | int | $w\times h$ | n.a. |  Binary image which identifies the bad pixels, that is, pixels that should be ignored for the purpose of the analysis. Pixels identified with 1 are considered bad, while 0 is considered normal.
AOT_WAVEFRONT_SENSORS
MEASUREMENTS | flt | $s_{v}\times d$ | u.d. |  Wavefront measurements from the wavefront sensor. Each of its $s_{v}$ subapertures is able to measure in $d$ dimensions.
REF_MEASUREMENTS | flt | $s_{v}\times d$ | u.d. |  Reference measurements.
SUBAPERTURE_MASK | int | $s\times s$ | n.a. |  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).
SUBAPERTURE_INTENSITIES | flt | $s_{v}$ | ADU |  Detected average intensity (flux) of each of the $s_{v}$ valid subapertures.
OPTICAL_GAIN | flt | $1$ | n.a. |  Wavefront sensor optical gain.
AOT_WAVEFRONT_SENSORS_SHACK_HARTMANN
CENTROID_GAINS | flt | $s_{v}\times d$ | n.a. |  Centroid gain factors for each of $s_{v}$ subapertures and $d$ dimensions.
SPOT_FWHM | flt | $s_{v}\times d$ | arcsec |  Spot full width half maximum for each of $s_{v}$ subapertures and $d$ dimensions.
AOT_WAVEFRONT_CORRECTORS_DM
INFLUENCE_FUNCTION | flt | $w\times h\times a_{v}$ | m |  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.
AOT_LOOPS
COMMANDS | flt | $a_{v}$ | m |  Commands sent to the associated wavefront corrector. Contains the values sent to each of the $a_{v}$ valid actuators of a certain wavefront corrector.
REF_COMMANDS | flt | $a_{v}$ | m |  Reference offset commands for each of $a_{v}$ actuators.
TIME_FILTER_NUM | flt | $i\times m$ | n.a. |  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.
TIME_FILTER_DEN | flt | $j\times m$ | n.a. |  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}$.
AOT_LOOPS_CONTROL
MODAL_COEFFICIENTS | flt | $m\times t$ | u.d. |  Coefficients respective to each of the $m$ modes being corrected on the wavefront corrector.
CONTROL_MATRIX | flt | $s_{v}\times d\times a_{v}$ | u.d. |  Linear relationship between the wavefront sensor measurements ($s_{v}\times d$) and the corrector commands ($a_{v}$).
MEASUREMENTS_TO_MODES | flt | $s_{v}\times d\times m$ | u.d. |  Linear relationship between the wavefront sensor measurements ($s_{v}\times d$) and the modes to be corrected ($m$).
MODES_TO_COMMANDS | flt | $m\times a_{v}$ | u.d. |  Linear relationship between the modes ($m$) to be corrected and the corrector commands ($a_{v}$).
INTERACTION_MATRIX | flt | $a_{v}\times d\times s_{v}$ | u.d. |  Represents the measurements of the wavefront sensor ($d\times s_{v}$) in response to each actuator of the wavefront corrector ($a_{v}$).
COMMANDS_TO_MODES | flt | $a_{v}\times m$ | u.d. |  Represents the modal response ($m$) to each actuator of the wavefront corrector ($a_{v}$).
MODES_TO_MEASUREMENTS | flt | $m\times d\times s_{v}$ | u.d. |  Linear relationship between the modal response ($m$) and the wavefront sensor measurements ($d\times s_{v}$).
RESIDUAL_COMMANDS | flt | $a_{v}$ | u.d. |  Reconstructed corrector commands before time filtering.
AOT_LOOPS_OFFLOAD
OFFLOAD_MATRIX | flt | $a1_{v}\times a2_{v}$ | u.d. |  Linear relationship between the commands from one actuator ($a1$) and the corresponding commands that get offloaded to another actuator ($a2$).
191919
The unit ”n.a.” stands for ”not applicable”, meaning that the data is a
dimensionless quantity, such as countable quantities, ratios and proportions.
The unit ”u.d.” stands for ”user defined” meaning that the user is free to
pick a unit as long as it is consistent with the rest of the data.
All images in this table may vary over time. In such cases, the images must
have an extra $t$ dimension, which must defined after all the other specified
dimensions. It is recommended that images with a $t$ contain a TIME_UID
keyword in their header, whose value is a AOT_TIME row-reference with time
data of $t$ length. The $t$ dimension may be omitted if it is of size 1.
$w$ and $h$ are (respectively) the width and height of the image in pixels,
$s_{v}$ is the number of valid subapertures (ordered as defined via
SUBAPERTURE_MASK), $d$ is the number of dimensions being measured by the
wavefront sensor, $a_{v}$ is the number of valid actuators, $m$ is the number
of modes being controlled.
If an image of data type flt can be accurately described with a int type,
users may opt to do so. However, this does not apply to the inverse.

###  3.4 Extra data

While there are no theoretical obstacles to creating a FITS file that contains
extra HDUs, keywords or fields on top of the ones that were already explicitly
defined in this specification, tools specially designed to support AOT files
may not be expecting such non-standard data. Consequentially, these extra data
may be ignored by supporting tools or, in a worst case scenario, cause
unexpected behaviour. In order to ensure maximal compatibility, it is highly
recommended that such arbitrary modifications are avoided, particularly in
files that are meant to be shared with third-parties. If adding some extra
metadata is absolutely necessary (for example, to ensure compatibility with
existing archives or pipelines), it is recommended that these additions are
limited to the primary header.

##  4 Supporting tools

Given that the usefulness of a format of this kind is largely predicated on
its wide adoption, reducing any existing barriers to adoption is of paramount
importance. One of the ways user-friendliness can be improved is by providing
the community with a set of supporting tools.

In general terms, an AOT supporting tool should provide functionalities that
help users read, edit and write AOT files, while abstracting them from format
specification details (such as layout of the file, table naming, mandatory
keywords and the cross-referencing mechanisms). They may also provide provide
translation mechanism for interacting with existing non-AOT telemetry
datasets. Since AOT files potentially contain large amounts of data, it is
recommended that tools avoid loading all data to memory (and instead load it
as it becomes necessary) and that special care is taken to avoid unnecessary
data duplication (particularly in image extensions).

The language-agnostic data model for AOT described in Sec. 2.2 enables the
abstractions described above while still allowing access to all relevant data.
In a previous paper (Gomes et al. 2022), we discussed the development of aotpy
(Adaptive Optics Telemetry for Python), an object-oriented Python (Van Rossum
& Drake 2009) package based on the AOT data model, which was designed with the
considerations described above; we will provide an overview of this package in
the following section.

###  4.1 aotpy

aotpy is an implementation of the AOT data model along with other
functionalities that improve the ease-of-use of the AOT format. In aotpy a
recording of AO telemetry data can be described by one Python object (named
AOSystem) which contains all the data and relationships between parts of the
system (see data model in Fig. 1).

Using aotpy, an AOT file can be read into a set of related objects (as defined
in the data model) that enable the user to interact with the data in a
generalised manner. These objects can also be automatically written back into
an AOT file, completely abstracting the user from file handling details. These
operations are performed by ”writers” and ”readers”, such that one writer-
reader pair must exist per each file format supported. While currently only
the FITS format is implemented, the package is designed in a modular way that
would allow for a simple expansion to further formats. A diagram of the
writing and reading process is shown in Fig. 3.

Figure 3:  Diagram that exemplifies how ”readers” and ”writers” work in aotpy.
The starting and final ”AOT .fits” files are functionally equivalent. The
AOSystem object is completely agnostic from the specific file format in use,
meaning that it would be possible to read a FITS file and write an equivalent
file in another file format, as long as such a writer was implemented.

On top of the file handling functionalities, aotpy is also able to translate
some existing non-standard data files into a standard aotpy object. This
allows the user to handle data from systems that do not follow the AOT
specification using aotpy, which is achieved by providing one translation
script (”translator”) for each supported system. These scripts are able to
read and interpret the files produced by the respective system, and convert
that data into an AOSystem object that describes the recording. This object is
system-agnostic and can be treated as any other such AOSystem object, meaning
that it can, among other things, be written as a standard AOT FITS file.
Currently, we have implemented proof-of-concept translators for ESO’s GALACSI
(Stuik et al. 2006), NAOMI (Aller-Carpentier et al. 2014), CIAO (Kendrew et
al. 2012) and ERIS (Riccardi et al. 2016), as well as ALPAO’s PAPYRUS
(Muslimov et al. 2021). A diagram exemplifying the translation process can be
seen in Fig. 4.

Figure 4:  Diagram that exemplifies how ”translators” work in aotpy. The files
to the left are non-standard and may use any file format (or even multiple
formats). Each system requires a specific translator that is able to interpret
data from their respective files and fill the corresponding fields of the
AOSystem object. This resulting object is completely agnostic from the system
where the data originated from, and it can then be used as any other aotpy
object. In this example, it is written back into a single AOT .fits file using
the FITS writer.

We have made aotpy publicly available on PyPI (Python Package Index) and its
source code is also available on GitHub and Zenodo (Gomes 2023; Gomes & Leroux
2023)202020Accessible via https://github.com/STAR-PORT/aotpy and
https://zenodo.org/doi/10.5281/zenodo.8187229, respectively..

##  5 Demonstration and data availability

In the interest of allowing users to have an immediate experience with AOT
files, we made available some proof-of-concept files. Using aotpy, we
translated GALACSI, CIAO, NAOMI and ERIS data gathered under ESO’s program IDs
60.A-9278(B), 60.A-9278(C), 60.A-9278(D) and 60.A-9278(E) respectively, and
published the translated files on the ESO archive. These are publicly
accessible and searchable under the respective program IDs212121Queries on the
ESO archive can be performed at
https://archive.eso.org/eso/eso_archive_main.html. The ”Program ID” textbox
can be used to specify the instrument.. A small dataset has also been made
available on Zenodo (Gomes et al. 2023)222222Accessible at
https://zenodo.org/doi/10.5281/zenodo.8187229.; this dataset contains PAPYRUS
data, along with a subset of the data also shared through the ESO archive.
This demonstration shows the adaptability of the format to vastly different
systems, including different telescopes, different AO modes, different
wavefront sensor types and different control schemes.

The translation of the original non-AOT datasets into these proof-of-concept
followed the process described in Sec. 4.1; for example, converting ERIS data
contained in a folder located at ”path/to/folder” into a single ”example.fits”
AOT file can be done with the following code (as long as the aotpy package is
installed):

⬇

from aotpy.translators import ERISTranslator

sys = ERISTranslator(’path/to/folder’).translate()

sys.write_to_file(’example.fits’)

In Morujão, N. et al. (2023), NAOMI AO telemetry data (made available by this
project) is used to estimate integrated turbulence parameters, fully
demonstrating the suitability of AOT for such use-cases.

The PSF-R use case is still in development and a full demonstration is not
available at this time. We are supporting the developments made under the ELT
working group for PSF-R232323See https://elt.eso.org/about/workinggroups/. in
all its dimensions, namely with demonstrations on the VLT with ERIS in
preparation for the full-blown deployment on the ELT.

##  6 Summary and Outlook

In this paper, we highlight the immense scientific potential within the field
of AO research. To harness this potential, we address the challenge of limited
end-user access to pertinent data. Despite a growing interest among data-
producing systems to share their valuable data, the community has yet to
establish a consensus on the most effective approach. To overcome this
challenge, we introduce AOT, an innovative data exchange format that has been
collaboratively developed within the community. AOT is designed to accommodate
a wide range of system configurations, empowering us to unlock the full
potential of AO research.

AOT is focused on supporting scientifically important use-cases through a set
of design principles that address the needs of the community. It is a FITS-
based format, on top of which we have developed a set of conventions and
structures that enable users to have access to relevant data in a standardised
manner. This format is fully specified in order to avoid ambiguity and allow
for interchangeability.

We discuss the need to provide the community with supporting tools that ease
the adoption of the format. We demonstrate their use and provide public
datasets.

###  6.1 Future Work

This first public version of AOT aims to get a significant foothold in the AO
space, while acknowledging that future expansions may be necessary, as the
field progresses and community needs change. Therefore, we are committed to
providing continuous support and improvements in the foreseeable future.

Looking ahead, our foremost objectives include:

  * •

Continue developing and improving supporting tools and their documentation. We
are currently in the early stages of developing a graphical user interface for
AOT data, with the goal of providing a dashboard that allows users to perform
exploratory data analysis interactively. In conjunction with the ESO Archive
team, we are also developing new user-facing query forms that improve access
to AOT data in the archive.

  * •

Further promoting and discussing the format with both end-users and data-
producing teams. We have initiated talks with other instrument teams
(including the teams responsible for Keck AO (Wizinowich et al. 2000), LBT AO
(Skemer et al. 2012), NFIRAOS (Herriot et al. 2005), HARMONI (Thatte et al.
2010), MICADO (Davies et al. 2010) and METIS (Brandl et al. 2008)) to explore
the possibility of also providing translation scripts for those systems; this
diversification would further exemplify AOT’s adaptability to different AO
configurations. We are also exploring how AOT/aotpy can be integrated into
data processing pipelines currently in use by AO instruments.

  * •

Exploring and demonstrating the usefulness of AOT in additional scenarios such
as AIT phases, ELT-class telescopes, High-Contrast Imaging and Interferometry.

All in all, in the coming phases, the pivotal focus will be on establishing
and maintaining enduring community support and funding for the AOT software
package, ensuring its continuous development to meet the evolving needs of
future scientific instruments and observatories. Transitioning from the
current proof-of-concept phase to a fully operational setting will be
instrumental in realising the adoption of AOT by the next generation of state-
of-the-art instruments, underscoring the essential role of sustained financial
and community backing in this endeavour.

##  Appendix A Design principles

In order to guide the necessary decision-making for designing the format, we
deem that a set of design principles must be defined. These principles
essentially illustrate the characteristics of a format that would best meet
the goals of this format. Specifically, this idealised format would be:

  * •

Shareable: exchanging data between data-producing systems and their end-users
must be a straightforward process.

  * •

Unambiguous: ensure that data shared can only be interpreted in one well-
defined manner, that is consistent across all systems.

  * •

Generalised: structure the format in a way that allows the end-user to access
data abstracted from observatory or instrument details.

  * •

Flexible: support as many AO systems as possible, by being sufficiently
adaptable to their differences and the irregularities of real-life telemetry.

  * •

Complete: ensure that all relevant information can be packaged in the format.

  * •

User-friendly: adoption barriers must be reduced by providing accessible tools
and documentation.

  * •

Expansible: allow for future expansions to meet user needs and advancements in
the AO field.

In sum, the format structure and data access should be the exact same across
various systems and configurations, while the data itself should be trivial to
access and understand. Given that some of these design principles can conflict
with each-other, in practice it is not possible to perfectly achieve all of
them. Therefore, some design decisions have to be analysed as compromises
between different principles. In general, we consider these principles should
be prioritised in the listed order.

##  Appendix B FITS overview

The Flexible Image Transport System (FITS) is a data format first proposed in
1979 aimed at standardising the interchange of astronomical images and other
digital arrays on magnetic tapes (Wells & Greisen 1979). The format is now
understood as being independent of physical medium and has since received
multiple revisions that accommodate further features (Hanisch et al. 1993,
2001, 2005; Pence et al. 2010; Chiappetti et al. 2018).

In order to fully describe AOT we will need to reference many FITS concepts.
Below, we provide an overview of the FITS format as a quick-reference guide,
but the most recent FITS specification (Chiappetti et al. 2018, at the time of
writing) should be referred to for the full specification.

In general terms, a FITS file is a sequence of Header Data Units (HDUs), with
each HDU being composed of two parts: the header and the data array. The
header is a series of ASCII text keywords and their respective values, that
are typically used to describe the data array contained in that HDU
(essentially, metadata). While there is a set of reserved keywords whose
meaning is defined in the FITS specification (some of which are mandatory),
any strings may be used as keywords (as long as they are up to 8 characters in
length). The data array itself follows the header, and it can be formatted in
multiple ways depending on its specific type.

The first HDU in a file is known as the primary HDU and it contains the
primary header, which is followed by either image data or no data array at
all. The primary HDU may be followed by any number of HDUs, which are known as
extensions. Unlike the primary HDU, extensions may contain data types other
than images. The data type in use is identified by the value of the XTENSION
keyword, which should be one of the values approved by the IAU FITS Working
Group (Chiappetti et al. 2018, Appendix F). AOT only makes use of the Binary
Table (BINTABLE) and Image (IMAGE␣␣␣) extensions. Sections 3.2 and 3.3
describe how these extensions are used in AOT, respectively.

Despite the name, Image extensions do not necessarily define an image; instead
they may contain any multidimensional homogeneous array (up to 999
dimensions). Each array is composed of either characters, integers or floating
point values, for which metadata such as units of measurement may be defined
(in the corresponding header).

Binary Table extensions are tables composed of up to 999 ordered columns
(known as fields) and as many ordered rows as necessary. Each field has a
case-insensitive name (represented in upper-case) and a certain data type that
applies to all of its entries (there is one entry per row). Other metadata
about the field may also be optionally defined, such as units of measurement.
All these column metadata are described using keywords of the form TXXXX$n$ ,
where TXXXX represents one of an open set of mandatory, reserved or user-
defined keywords up to five characters in length, for example: TFORM
(mandatory), TUNIT (reserved), TCOMM (user-defined). The $n$ part is an
integer between 1 and 999 which indicates the index of the column that the
keyword in question refers to.

FITS provides no limitation on the total number of HDUs nor on the the total
size of the FITS file (Chiappetti et al. 2018, Sec. 3.1). Therefore, in
practical terms the file size is solely restricted by the limits of the
device’s filesystem itself, or of any tools handling the data. We expect that,
in real-world scenarios, this limitation is unlikely to be significant when
using modern 64-bit based filesystems and programs.

##  Appendix C Data types in FITS

Data and metadata in FITS may be represented in many forms depending on the
context.

In headers, metadata is defined by ASCII-text representations of literal
string, logical or numerical constants.

In images, data is represented by bits which, depending on the value of the
BITPIX keyword, must be interpreted as characters, integers or floating-point
values. Integers and floating-point data must be represented in different ways
depending on the desired range of values, accuracy and size constraints.

In binary tables, data is also represented by bits. However, different fields
may have different data types, which are defined through their respective
TFORMn keywords. Similar to images, integer, floating-point, complex and array
data in binary tables may be represented in different ways depending on the
desired range of values, accuracy and size constraints. Specifically, a field
may contain data of one of following types:

  * •

Logical: interpreted as true or false (TFORM is ’L’).

  * •

Binary: interpreted as literal bits (’X’).

  * •

Character: interpreted as the restricted set of 7-bit ASCII-text characters
(’A’).

  * •

Integer: interpreted as signed 16-bit (’I’), 32-bit (’J’) or 64-bit (’K’)
integers, or unsigned 8-bit integers (’B’).

  * •

Floating-point: interpreted as 32-bit single-precision (’E’) or 64-bit double-
precision ’D’ floating point data.

  * •

Complex: interpreted as 32-bit single-precision (’C’) or 64-bit double-
precision ’M’ complex data.

  * •

Array descriptor: interpreted as two 32-bit (’P’) or 64-bit (’Q’) integers.
These two integers are used to essentially define the starting point and
length of a variable-length array (VLA), which is then stored in a
supplemental data area (heap) following the main data table. The TFORM of a
VLA column must define two characters, the first for the type of array
descriptor, and the second for the data type of the actual array stored in the
heap. This means that a VLA may be of any of the types defined previously.

For fields of types other than array descriptor, their entries are assumed by
default to contain a single value. However, those fields may define their
entries as arrays of values; the number of elements (array length) is
specified by a non-negative integer in TFORM which precedes the type
character, meaning that all entries in such a field must have the exact same
number of elements (this limitation is avoided in VLAs, due to the reasons
elucidated above). Multidimensional data may also be specified by a TDIM
keyword, which also applies to all entries in the field; this has some
limitations presented in Appendix D.

##  Appendix D Multidimensional data in AOT

While the FITS specification technically supports storing multidimensional
data in binary tables, this feature has many limitations. The specification
defines that, in order for a certain field to contain multidimensional
entries, this field must have a corresponding TDIMn keyword which defines the
exact dimensions of its arrays. While the array itself is still stored as a
one-dimensional set of data, knowing its intended dimensions allows for a
proper interpretation of the data.

Since we must only define one such keyword per field, a direct consequence is
that all the entries in that field must have the exact same
dimensions242424There is one exception to this: fields containing
multidimensional data formatted as variable-length arrays. In this case, their
entries may either adhere to the specified dimensions or be empty entries
(length 0). This is a very obscure detail which is currently unsupported by
most FITS tools. Regardless, this feature is not particularly useful for the
situation at hand, as VLAs provide no mechanism for defining different
dimensions per entry, and thus there is no meaningful space savings to be
had.. Using AOT as an example, this means that if we wanted to store the
slopes of a certain wavefront sensor as a multidimensional array inside the
binary table, slopes of all further wavefront sensors would also need to
respect those exact dimensions. However, it is not guaranteed that they would
have the same dimensions, as the number of subapertures might not be the same,
or we might be recording at a different frequency. Therefore, it is clear that
the standard implementation of multidimensional data in binary tables is not
versatile enough to fit AOT’s needs.

Since we had to store multidimensional data in some way, we considered three
ways of getting around this limitation:

  1. 1.

Use TDIMn keywords and, for each field, pick a large enough set of dimensions
such that the data from all entries can fit inside those dimensions. Fill the
remaining spaces with some sort of filler value that is ignored when reading.

  2. 2.

Use variable-length arrays without TDIMn keywords, and add an extra column
which specifies the dimensions for each entry.

  3. 3.

Save the multidimensional data as separate image extensions that are then
referenced in the corresponding table entries.

The first option has multiple issues. First off, it can result in large
amounts of wasted storage space given that a user could be forced to write a
small array as a much larger one, in order to respect the dimensions that were
set by another array in that field. On top of that, defining an appropriate
filler value could be difficult given how diverse the data can be. It is also
completely unintuitive for any users that would see such data without context,
as the FITS specification would likely lead them to interpret all entries as
having the dimensions specified by TDIMn. Finally, the implementation
complexity for this would be relatively large, forcing reading and writing
tools to filter and reshape possibly huge amounts of data in order to
correctly interpret it.

By using VLAs, the second option avoids the wasted space that the first option
would create. However, it would force the creation of one extra field for any
field that contains multidimensional data, which is a mechanism that is not
standardised in FITS. Therefore, the interpretation of this field would be
ambiguous for users not familiar with the AOT standard (for example, are the
arrays be stored in row-major or column-major order?), which could lead to
interchangeability issues.

We ended up choosing the third option. The major deciding factor is that
saving multidimensional data in image extensions is a very well-defined
mechanism, since it is fully described in the FITS specification. Using image
extensions also allows us to leverage their already established features and
versatility, such as saving metadata in its headers or using data scaling
features. Another advantage is that FITS tools are usually already prepared to
deal with image extensions and thus they can easily and unambiguously
interpret them without requiring any AOT-specific conventions. Finally, this
approach also allows us to save multidimensional data externally through FITS
image files, which is a very common mechanism. The biggest downside of using
this approach is that it requires AOT to use a non-standard cross-referencing
mechanism. However, the format already required a similar mechanism to deal
with cross-referencing between binary tables (see Appendix E.3), therefore
this did not represent a significant increase in AOT’s complexity.

It is important to note that some fields in AOT contain one-dimensional arrays
that may have a length larger than 1 (that is, lists). While such data could
reasonably be stored as one-dimensional image extensions, we deem doing so
would create unnecessary clutter in the file structure. This is because 1)
these sets of data tend to be relatively small and fairly simple, so they are
unlikely to benefit significantly from the metadata of image extensions and 2)
the standard VLAs are able to fully describe these lists without requiring any
AOT-specific convention. Therefore, in fields where one-dimensional arrays are
expected, AOT uses VLAs.

##  Appendix E AOT Conventions

In this appendix we will define a set of AOT-specific conventions that apply
to the entirety of this paper. Where relevant, some standard FITS conventions
will also be mentioned, but we will not cover the entirety of the FITS
specification; it is implicit that all FITS features are supported, unless
explicitly defined otherwise.

###  E.1 Mandatory FITS Keywords

The FITS specification defines a set of mandatory keywords (Chiappetti et al.
2018, Section 4.4.1.) for both the primary and extension headers. For
simplicity, in the following sections we will only explicitly define AOT-
specific keywords for each HDU, but the mandatory FITS keywords are implicitly
assumed to be present and appropriately adhered to.

###  E.2 Data types

The FITS specification defines a wide range of possible data types for which
we provide an overview in Appendix C. Notwithstanding, in AOT only 4 different
types of data are used:

  * •

Integer, represented as “int”.

  * •

Floating-point, represented as “flt”.

  * •

String, represented as “str”.

  * •

List of floating-point data, represented as “lst”;

Header values are either str or flt. Image data may be int or flt. Fields in
binary tables may be int, flt, str (represented as a fixed-length array of
characters) or lst (represented as a variable-length array of floats). AOT
does not specify the precision for any of the data types; this means that a
field or image specified as, e.g., flt may be represented with single (32-bit)
or double (64-bit) precision, according to the user’s needs (so long as the
FITS specification is properly adhered to).

Although the FITS specification technically allows binary table fields of any
data type to contain multidimensional arrays, this functionality is not used
in AOT and thus all data within AOT binary tables must be uni-dimensional (for
reasoning, see Appendix D). As a result, all multidimensional data in AOT is
contained in image extensions that are cross-referenced via table entries
(this mechanism will be explained in Appendix E.3).

###  E.3 Cross-referencing

The FITS specification does not provide a standard way of cross-referencing
image extensions or table rows. Given that such a mechanism would be
convenient for defining relationships between data and avoiding data
duplication, AOT defines its own cross-referencing mechanism. A diagram
demonstrating its use can be seen in Fig. 5.

Figure 5:  A diagram demonstrating how the cross-referencing mechanism in AOT
works. In this example, each row in the AOT_LOOPS table references one row in
the AOT_WAVEFRONT_SENSORS table, one row in the AOT_WAVEFRONT_CORRECTORS table
and one image extension. Rows are identified by the string value of their UID
fields, while images are identified by the string value of their EXTNAME
keyword.

In general, there are two different types of references in AOT: row-references
and image-references. Both types of references are done through a single str
value, in a field that is specified as being a reference. This str value is
able to uniquely and unambiguously identify the referenced row or image
extension. A null str in a reference field is interpreted as no reference
being made (see Appendix E.4).

A row-reference identifies a specific row of a certain binary table. All AOT
tables contain one UID field, for which all the entries must have a non-null
value that is unique within each table (see Sec. 3.2). This means that we can
uniquely identify any row as long as we know its UID and the table it belongs
to. Given that AOT specifies which table is being referenced in every row-
reference field, a row-reference is made unambiguously with a str value
formatted as ’ROWREF<row_UID>’, where row_UID is the UID of the row being
referenced.

An image-reference identifies a certain image extension. The referenced
extension may either be present in the AOT file itself (internal image-
reference) or in another FITS file (external image-reference), but must always
follow the specifications of one of the image categories defined in Sec. 3.3.
All image extensions present in the AOT file must have a unique non-null name
(EXTNAME keyword), allowing them to be referenced internally by a str value
formatted as ’INTREF<image_EXTNAME>’, where image_EXTNAME is the name of the
image extension being referenced.

An external image-reference identifies the FITS file where a certain image
extension is present, either through a filename (file image-reference) or
through a web address (URL image-reference). A file image-reference is made
through a str value formatted as ’FILEREF<filename.fits>index’, where filename
is the name of the FITS file where the image data is located. To ensure wide
compatibility across most commonly used filesystems, filename must be case-
sensitive and only contain alphanumeric characters, full stops (.),
underscores (_) and hyphens (-). It is recommended that, when file image-
references are used, the referenced file is somehow made available along with
the AOT file, such that it is unambiguously be referenced solely by its name.
An URL image-reference is made through a str value formatted as
’URLREF<url>index’, where url is an URL (as defined in Berners-Lee et al.
2005) to a FITS file. It is highly recommended that this file is publicly
accessible and that it is not ephemeral; in other words, the file should
remain accessible through this URL by anyone for as long as the data is
relevant. For both types of external image-references, index is a non-negative
integer which indicates the position of the HDU that contains the referenced
image data (where index 0 is the primary HDU, index 1 is the first extension,
and so on). index may be omitted as long as the referenced image data is
present in the first HDU that contains non-null image data. Given the
challenges associated with guaranteeing that an external image extension
always remains unambiguously accessible throughout the lifetime of some data,
we highly recommend to only use external image-references in instances where
avoiding data duplication is a major concern.

While the values of both the EXTNAME keywords and the UID entries are freely
defined by the user, it is highly recommended that these values are human-
readable and that they intuitively describe the set of data that they
correspond to. This is beneficial to the readability of the file, as it helps
making it self-explanatory. For example, we recommend the UID of a Telescope
row to be the name of the telescope itself.

###  E.4 Null values

Since AOT defines a wide set of data, we expect that users might not want to
fill all of the available fields. Therefore, with the exception of the
mandatory FITS keywords (Appendix E.1), the fields necessary for uniquely
identifying references (Appendix E.3) and other keywords defined as strictly
mandatory in Secs. 3.1 or 3.2, all values are considered to be nullable.

While the FITS specification allows for keywords in headers to have values of
indeterminate data type (undefined keywords), to avoid confusion this is
strictly disallowed in AOT. Therefore, null strings must be represented as
zero-length arrays of characters (KEYWORD ='', see Chiappetti et al., Sec.
4.2.1.1 for a detailed distinction).

FITS specifies that null values in binary tables are represented in different
ways depending on their specific data type:

  * •

Null str data must be represented by an array of characters where the first
character is the ASCII NULL character (0x00), in other words, a zero-length
null-terminated string.

  * •

In order for null int data to exist in a certain field, that field must have a
TNULLn value specified by the user; all entries containing that exact value
are then interpreted as null. Given that all integer fields in the AOT
standard describe counts, negative integer values inherently have no meaning
and thus are recommended for this purpose (assuming a signed representation).

  * •

For null flt values, the IEEE special value NaN must be used.

  * •

Null lst are specified by having an array length of 0, and should be
interpreted as an empty array rather than a non-existing one (see Chiappetti
et al., Sec. 7.3.5. and 7.3.6.).

If a user does not intend to provide data for a field that references an
image, it is preferable to use a null reference, rather than referencing an
image extension that contains no data.

###  E.5 Date and time representation

Date and time data is vital for interpreting AO telemetry data; accordingly
AOT supports associating date and time data to all time-sensitive and/or time-
varying sets of data. All date and time data in AOT must be in the UTC time
standard, and must be represented in one of two ways (depending on the
specific field): 1) Based on the ISO 8601 format or 2) Unix timestamp.

ISO 8601 provides a set of unambiguous ways of representing calendar dates and
times in a human-readable format. In AOT, we use a ISO 8601 derived format
where date and time are represented as a string in the pattern ¡date¿T¡time¿
with ¡date¿ being specified as YYYY-MM-DD and ¡time¿ specified as
hh:mm:ss[.SSSSSS] (the decimal part, in square brackets, is optional). This
format is used where a single timestamp is expected, for its human-
readability. No other ISO 8601 formats are supported.

In situations where a set of timestamps is expected (for example, timestamps
related to time-varying data) the Unix time format (also known as POSIX or
Epoch time) is used instead. This format represents date and time as a
floating-point value containing the number of seconds that have elapsed since
00:00:00 UTC on 1 January 1970, with decimal digits being allowed. Dates past
03:14:08 UTC on Tuesday, 19 January 2038, cannot be represented by 32-bit
floats (due to overflow); in such cases, 64-bit floats must be used.

###  E.6 Geometric transformations

Any combination of translation, reflection, scale, rotation and shearing
(affine transformations) can be described via a single $3\times 3$ matrix $M$
such that $P^{\prime}=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^{\prime}$ is a
$\begin{bmatrix}x^{\prime}&y^{\prime}&1\end{bmatrix}$ vector, where
$x^{\prime}$ and $y^{\prime}$ are the transformed coordinates. A diagram
exemplifying this mechanism can be see in Fig. 6.

Figure 6:  Diagram describing how different affine transformations can be
performed via 3-by-3 matrices. Illustration by Cmglee, distributed under the
Creative Commons Attribution-Share Alike 3.0 Unported license (Commons 2023).

All geometric information in AOT must be described relative to the same
reference origin point (defined by the user), from which transformations may
occur. For example, if the geometry of the system is defined with the
telescope pupil as the reference point, the TRANFORMATION_MATRIX on the
corresponding AOT_TELESCOPES row will be a 3-by-3 identity matrix. Then, a
wavefront sensor may define a 90° rotation from the pupil with a
$\begin{bmatrix}0&-1&0\\\ 1&0&0\\\ 0&0&1\\\ \end{bmatrix}$ matrix. The
detector used by that wavefront sensor, if not rotated in regards to it, would
define its geometry by using the exact same matrix.

###### Acknowledgements.

This project has received funding from the European Union’s Horizon 2020
research and innovation programme under grant agreement No. 101004719
(OPTICON–RadioNet Pilot) and from the FCT - Fundação para a Ciência e a
Tecnologia through the grant CENTRA UIDB/00099/2020. C. M. Correia
acknowledges the financial support provided by FTC with grant
2022.01293.CEECIND.

## References

  * Aller-Carpentier et al. (2014) Aller-Carpentier, E., Dorn, R., Delplancke-Stroebele, F., et al. 2014, in Optical and Infrared Interferometry IV, ed. J. K. Rajagopal, M. J. Creech-Eakman, & F. Malbet, Vol. 9146, International Society for Optics and Photonics (SPIE), 91461C
  * Andrade et al. (2019) Andrade, P. P., Garcia, P. J., Correia, C. M., Kolb, J., & Carvalho, M. I. 2019, Monthly Notices of the Royal Astronomical Society, 483, 1192
  * Bardou, Lisa et al. (2021) Bardou, Lisa, Gendron, Éric, Rousset, Gérard, et al. 2021, Astronomy & Astrophysics, 649, A158
  * Bardou, Lisa & Schulz, Christine (2018a) Bardou, Lisa & Schulz, Christine. 2018a, ESO Science Archive \- Wendelstein Laser Guide Star Unit Data Products, https://archive.eso.org/wdb/wdb/eso/wlgsu/form, accessed: 2022-07-02
  * Bardou, Lisa & Schulz, Christine (2018b) Bardou, Lisa & Schulz, Christine. 2018b, Manual for the open loop LGS-AO data taken with elongated LGS in ELT geometry configuration, https://archive.eso.org/wdb/help/eso/WLGSU_CANARY_AO_Manual.pdf, accessed: 2022-07-02
  * Beltramo-Martin et al. (2019) Beltramo-Martin, O., Correia, C. M., Ragland, S., et al. 2019, Monthly Notices of the Royal Astronomical Society, 487, 5450
  * Beltramo-Martin et al. (2020) Beltramo-Martin, O., Marasco, A., Fusco, T., et al. 2020, Monthly Notices of the Royal Astronomical Society, 494, 775
  * Berners-Lee et al. (2005) Berners-Lee, T., Fielding, R. T., & Masinter, L. M. 2005, Uniform Resource Identifier (URI): Generic Syntax, RFC 3986
  * Bradner (1997) Bradner, S. O. 1997, Key words for use in RFCs to Indicate Requirement Levels, RFC 2119
  * Brandl et al. (2008) Brandl, B. R., Lenzen, R., Pantin, E., et al. 2008, in Ground-based and Airborne Instrumentation for Astronomy II, ed. I. S. McLean & M. M. Casali, Vol. 7014, International Society for Optics and Photonics (SPIE), 70141N
  * Chiappetti et al. (2018) Chiappetti, L., Currie, M. J., Allen, S., et al. 2018, Definition of the Flexible Image Transport System (FITS) The FITS Standard Version 4.0: updated 2016 July 22 by the IAUFWG Original document publication date: 2016 July 22 Language-edited document publication date: 2018 August 13, Tech. rep., Italian National Institute for Astrophysics (INAF)
  * Commons (2023) Commons, W. 2023, File:2D affine transformation matrix.svg — Wikimedia Commons, the free media repository, [Online; accessed 3-November-2023]
  * Conan & Correia (2014) Conan, R. & Correia, C. 2014, in Adaptive optics systems IV, Vol. 9148, SPIE, 2066–2082
  * Davies et al. (2010) Davies, R., Ageorges, N., Barl, L., et al. 2010, in Ground-based and Airborne Instrumentation for Astronomy III, ed. I. S. McLean, S. K. Ramsay, & H. Takami, Vol. 7735, International Society for Optics and Photonics (SPIE), 77352A
  * Duvert et al. (2017) Duvert, G., Young, J., & Hummel, C. A. 2017, Astronomy & Astrophysics, 597, A8, publisher: EDP Sciences
  * Fusco et al. (2020) Fusco, T., Bacon, R., Kamann, S., et al. 2020, Astronomy & Astrophysics, 635, A208
  * Gendron et al. (2006) Gendron, E., Clénet, Y., Fusco, T., & Rousset, G. 2006, Astronomy & Astrophysics, 457, 359
  * Gilles et al. (2012) Gilles, L., Correia, C., Véran, J.-P., Wang, L., & Ellerbroek, B. 2012, Applied Optics, 51, 7443
  * Gomes (2023) Gomes, T. 2023, aotpy, https://github.com/STAR-PORT/aotpy
  * Gomes et al. (2022) Gomes, T., Correia, C., Bardou, L., et al. 2022, in Adaptive Optics Systems VIII, ed. L. Schreiber, D. Schmidt, & E. Vernet, Vol. 12185, International Society for Optics and Photonics (SPIE), 121850H
  * Gomes et al. (2023) Gomes, T., Garcia, P., Correia, C., & Morujão, N. 2023, Proof-of-concept AO telemetry data using the AOT standard format, https://doi.org/10.5281/zenodo.8192741
  * Gomes & Leroux (2023) Gomes, T. & Leroux, F. 2023, STAR-PORT/aotpy, https://doi.org/10.5281/zenodo.8187229
  * Greenfield et al. (2015) Greenfield, P., Droettboom, M., & Bray, E. 2015, Astronomy and Computing, 12, 240
  * Guesalaga et al. (2014) Guesalaga, A., Neichel, B., Cortés, A., Béchet, C., & Carmine, G. 2014, Monthly Notices of the Royal Astronomical Society, 440, 1925
  * Hanisch et al. (2001) Hanisch, R. J., Farris, A., Greisen, E. W., et al. 2001, Astronomy & Astrophysics, 376, 359, number: 1 Publisher: EDP Sciences
  * Hanisch et al. (2005) Hanisch, R. J., Pence, W. D., Schlesinger, B. M., et al. 2005, Definition of the Flexible Image Transport System (FITS), Tech. Rep. 2.1b, IAU FITS Working Group
  * Hanisch et al. (1993) Hanisch, R. J., Schlesinger, B. M., Brotzman, L. E., et al. 1993, Definition of the Flexible Image Transport System (FITS), Tech. Rep. NOST 100-1.0, NASA/Science Office of Standards and Technology
  * Herriot et al. (2005) Herriot, G., Hickson, P., Ellerbroek, B. L., et al. 2005, in Astronomical Adaptive Optics Systems and Applications II, ed. R. K. Tyson & M. Lloyd-Hart, Vol. 5903, International Society for Optics and Photonics (SPIE), 590302
  * Hirst & Cardenes (2016) Hirst, P. & Cardenes, R. 2016, in Software and Cyberinfrastructure for Astronomy IV, ed. G. Chiozzi & J. C. Guzman, Vol. 9913, International Society for Optics and Photonics (SPIE), 531 – 539
  * Hirst et al. (2020) Hirst, P., Jenkins, D., & Sivo, G. 2020, in Adaptive Optics Systems VII, ed. L. Schreiber, D. Schmidt, & E. Vernet, Vol. 11448, International Society for Optics and Photonics (SPIE)
  * Jolissaint et al. (2018) Jolissaint, L., Ragland, S., Christou, J., & Wizinowich, P. 2018, Appl. Opt., 57, 7837
  * Kendrew et al. (2012) Kendrew, S., Hippler, S., Brandner, W., et al. 2012, in Ground-based and Airborne Instrumentation for Astronomy IV, ed. I. S. McLean, S. K. Ramsay, & H. Takami, Vol. 8446, International Society for Optics and Photonics (SPIE), 84467W
  * Laidlaw et al. (2019) Laidlaw, D. J., Osborn, J., Morris, T. J., et al. 2019, Monthly Notices of the Royal Astronomical Society, 491, 1287
  * Martin et al. (2016) Martin, O. A., Correia, C. M., Gendron, E., et al. 2016, in Adaptive Optics Systems V, ed. E. Marchetti, L. M. Close, & J.-P. Véran, Vol. 9909, International Society for Optics and Photonics (SPIE), 1143 – 1157
  * Morujão, N. et al. (2023) Morujão, N., Correia, C., Andrade, P., Woillez, J., & Garcia, P. 2023, A&A, 678, A193
  * Muslimov et al. (2021) Muslimov, E., Levraud, N., Chambouleyron, V., et al. 2021, in Optical Instrument Science, Technology, and Applications II, ed. N. Haverkamp, B. N. Sitarski, & R. N. Youngworth, Vol. 11876, International Society for Optics and Photonics (SPIE), 118760H
  * Myers et al. (2008) Myers, R. M., Hubert, Z., Morris, T. J., et al. 2008, in Adaptive Optics Systems, ed. N. Hubin, C. E. Max, & P. L. Wizinowich, Vol. 7015, International Society for Optics and Photonics (SPIE), 52 – 60
  * Ochsenbein et al. (2004) Ochsenbein, F., Williams, R., Davenhall, C., et al. 2004, in Toward an International Virtual Observatory, ed. P. J. Quinn & K. M. Górski, ESO ASTROPHYSICS SYMPOSIA (Springer), 118–123
  * Pauls et al. (2004) Pauls, T. A., Young, J. S., Cotton, W. D., & Monnier, J. D. 2004, in New Frontiers in Stellar Interferometry, Vol. 5491 (International Society for Optics and Photonics), 1231–1239
  * Pauls et al. (2005) Pauls, T. A., Young, J. S., Cotton, W. D., & Monnier, J. D. 2005, Publications of the Astronomical Society of the Pacific, 117, 1255, publisher: IOP Publishing
  * Pence et al. (2010) Pence, W. D., Chiappetti, L., Page, C. G., Shaw, R. A., & Stobie, E. 2010, Astronomy & Astrophysics, 524, A42, publisher: EDP Sciences
  * Petit et al. (2014) Petit, C., Sauvage, J.-F., Fusco, T., et al. 2014, in Adaptive Optics Systems IV, Vol. 9148, SPIE, 214–230
  * Preston-Werner (2013) Preston-Werner, T. 2013, Semantic Versioning 2.0.0, https://semver.org/spec/v2.0.0.html, accessed: 2023-01-24
  * Riccardi et al. (2016) Riccardi, A., Esposito, S., Agapito, G., et al. 2016, in Adaptive Optics Systems V, ed. E. Marchetti, L. M. Close, & J.-P. Véran, Vol. 9909, International Society for Optics and Photonics (SPIE), 99091B
  * Scroggins & Boscoe (2020) Scroggins, M. & Boscoe, B. M. 2020, IEEE Annals of the History of Computing, 42, 42, conference Name: IEEE Annals of the History of Computing
  * Sinquin et al. (2020) Sinquin, B., Prengere, L., Kulcsár, C., et al. 2020, Monthly Notices of the Royal Astronomical Society, 498, 3228
  * Sivo et al. (2014) Sivo, G., Kulcsár, C., Conan, J.-M., et al. 2014, Optics express, 22, 23565
  * Skemer et al. (2012) Skemer, A. J., Hinz, P. M., Esposito, S., et al. 2012, The Astrophysical Journal, 753, 14
  * Stuik et al. (2006) Stuik, R., Bacon, R., Conzelmann, R., et al. 2006, New Astronomy Reviews, 49, 618, adaptive Optics-Assisted Integral-Field Spectroscopy
  * Thatte et al. (2010) Thatte, N., Tecza, M., Clarke, F., et al. 2010, in Ground-based and Airborne Instrumentation for Astronomy III, ed. I. S. McLean, S. K. Ramsay, & H. Takami, Vol. 7735, International Society for Optics and Photonics (SPIE), 77352I
  * The HDF Group (1997-2022) The HDF Group. 1997-2022, Hierarchical Data Format, version 5, https://www.hdfgroup.org/HDF5/, accessed: 2022-06-27
  * Thomas et al. (2015) Thomas, B., Jenness, T., Economou, F., et al. 2015, Astronomy and Computing, 12, 133
  * Van Rossum & Drake (2009) Van Rossum, G. & Drake, F. L. 2009, Python 3 Reference Manual (Scotts Valley, CA: CreateSpace)
  * Veran et al. (1997) Veran, J. P., Rigaut, F., Maitre, H., & Rouan, D. 1997, Journal of the Optical Society of America A, 14, 3057
  * Vidal et al. (2010) Vidal, F., Gendron, E., & Rousset, G. 2010, Journal of the Optical Society of America A, 27, A260000
  * Wells & Greisen (1979) Wells, D. C. & Greisen, E. W. 1979, in Image Processing in Astronomy, 445
  * Wizinowich et al. (2000) Wizinowich, P., Acton, D. S., Shelton, C., et al. 2000, Publications of the Astronomical Society of the Pacific, 112, 315