Aeonlib design considerations

[Fingel]

I've spent the last 2 days thinking and experimenting with what Aeonlib might look like in the immediate future.

Several times Astropy's Astroquery has been mentioned as a possible model. Astroquery provides many Python classes for different astronomical catalog services. What Astroquery does not provide is an entirely uniform interface for these classes. For example, compare the interfaces for NED, SIMBAD, and HEASARC. While some of these classes do have common methods (query_object or query_region) for the most parts their APIs are unique.

This is no surprise as these are unique catalogs with differing functionalities. The consequence of this is that the operator still needs to be familiar with the services they are querying, or at least spend some time reading the documentation on Astropy's website. There are no guarantees made that a query crafted for SIMBAD will succeed unaltered for NED, or that the data returned will be uniform in shape or meaning.

This doesn't mean that Astroquery provides no value, far from it. Here are the benefits to a user of Astroquery:

1. All the catalogs in one place. This cannot be understated - instead of searching the internet for bespoke libraries to interface with each catalog, you mostly only need Astroquery, even if you do need to learn a little about each individual service within Astroquery.

2. A Python interface. These catalogs can be behind internet services of various types. JSON APIs are the most common, but some of these catalogs don't use JSON, and some don't even use HTTP! For example, (if I remember correctly) JPL Horizons uses some kind of telnet protocol. Using Astroquery abstracts away the transportation layer, meaning the user can be sure they only need to know Python.

3. Common building blocks. I think this is the most subtle, but potentially the most powerful feature of Astroquery. When a function in Astroquery requires a unit Astropy units are always used. For example, Coordinates are from astropy.coordinates and date/times are from astropy.time. This means that even if the interface is different between Astroquery classes, if one requires a coordinate it's easy for the user to provide one, no need to lookup whether it needs to be specified in h/m/s or decimal.

So how does this all relate to Aeonlib? Well we are trying something similar, but not quite the same. But I believe there are similar issues. The most glaring is that there is very little uniformity (currently) between observatory APIs. That means I believe it is not feasible to expect a common interface for observation requests at this time. Obviously if more observatories begin to adopt the OCS request language, this will begin to change. However, given the diversity of hardware and instruments at use in astronomy, I find it unlikely that observation requests will ever be truly 100% cross-observatory. Individual instruments in all except the most basic configurations will need specific parameters. We are spoiled at LCO because we have many uniform instruments and telescopes spread around the network.

Here's what I think we can reasonably provide in the short term future:

1. A breadth of observatory modules. Just like Astroquery, if an observer wants to interface with an observatory Aeonlib should be the first tool they reach for. We just should not guarantee that these modules work the same way.

2. A guaranteed Python interface. We should aim for users of Aeonlib to never have to hand-write XML or JSON . This is actually harder than it might sound.

3. Like Astroquery, I believe we should use common building blocks for all modules. Ideally we even leverage Astropy's datatypes. We can build on top of these to provide our own cross-observatory types. For example, an "Observation Window" could be a class made up of two astropy.time.Time's. Astropy.coordinates for targets is another obvious choice. This will be a huge boon to users of the library that don't need to look up specific data formats for each observatory.

4. One place we can improve on the example of Astroquery is with strongly typed schemas, especially around request languages. For example, currently the recommended workflow for API requests to the LCO API is to go to the observation portal, type out a request into the webpage, copy the API view and paste it as a dictionary into your code. We can do better! Recent improvements to Python's type system coupled with libraries like Pydantic provide library authors and users with a means to interact with strongly-typed data and guarantees that are normally reserved mostly for other languages. For example, providing a Pydantic model that represents a particular Instrument's configuration provides some nice benefits: A) Users of the library get code completion and hints in their editor for the available fields when constructing a configuration B) At runtime these schemas are validated, preventing invalid configurations from ever being sent to an observatory, C) Downstream application (Like TOMs) can use these schemas to build forms. Other applications can use them to programmatically provide user interfaces. This is all in contrast to simply building Python dictionaries in which there is very little preventing mistakes and typically real submissions have to be made in order to check their validity.

In section 6 of aeon_project_description.pdf Activity 1 of the first obective reads:

Activity 1: Develop a Python library with core modules including observation submission, observation
status, observatory status and availability, data product availability, starting with the founding AEON
partner facilities and current AEON-compatible telescopes.

This is good, but I think we need to have expectations in place especially around observation submission. In my opinion, it might be easier to start with observation stats, availability, data products, etc as these actually do have a higher likelihood of being able to share common interfaces between observatories. Something to think about when coming up with timelines.

Here are some ideas for cross-observation functionality that might not require completely bespoke interfaces, and might be the basis for development stories:

• Data product search.
• Availability.
• Request status (result will differ between observatories, but calling interface might be generalized)
• //Add more here