Future enhancements for tom_eso

[talister]

Intro

During the Rubin Solar System Science Collaboration (SSSC) Sprint/Hackathon in Belfast in Feb 2026, I got a chance to sit down with Colin Snodgrass, a long-term ESO user, observer and former instrument operation scientist, to walk through setting up a new proposal and observing run in the phase2 and some general comments and thoughts on what is needed.
(Apologies for the length, I've tried to be extra explicit and illustrate as much as possible. Also Firefox crashed twice during the creation of this issue, so hopefully nothing important got lost in the prior iterations)
Happy to discuss and explain further; this is a bit of a "notes dump"

General Phase2 setup/Instrument support priority

1. There is a bunch of a Run-level metadata that needs to be entered at the start of the observing period which is frequently the same boilerplate from other previous proposals see example screenshots. These are just to provide the telescope operators and observers executing things out of the queue with broad context on what the program and observations are trying to achieve. This could potentially be stored within the TOM in a Proposal-level or broader "Science Area"-level entity and provided to the Phase 2's at various facilities (not just ESO's)

2. Suggested priority order on desirability of support for various ESO instruments (most useful first within each category):
   1st priority:

• FORS2 (optical 0.33--1.1µm imager/spectrograph),

• X-SHOOTER (Multi-wavelength 0.3--2.5µm medium res spectrograph),

• HAWK-I (Near IR 0.85--2.5µm wide-field imager)

  2nd priority:

• UVES (Optical 0.3--1.1µm high res spectrograph similar toNRES),

• CRIRES (Near/Mid IR 0.95--5.3µm high res spectrograph),

• MUSE (Optical 0.48--0.93µm multiplex Integral Field Spectrograph; mainly for comet people)

OB creation in the Phase2 UI

The remainder of the time was spent creating imaging FORS2 OBs - these are the notes from this part:

1. Normally create OBs within the ESO Phase2 UI, which can then be checked (Check button) within the Phase2 before hitting Certify which sends it to ESO Garching for a human review. Not sure if the API can do the Check or bypass the review.
2. OBs need to have a Acquisition and Science templates defined. For Acquisition, this is almost always FORS2_img_acq ("FORS2 Imaging Acquisition" for optical imaging) or FORS2_lss_acq_fast ("FORS2 Long Slit Spectroscopy Acquisition Fast" for optical spectroscopy). The CCD can be ANY, the guide star source ("Get Guide Star From") can be CATALOGUE and the RA/Dec all 00's. This means the system will pick an acquisition star at the time. This has no issues with moving targets except for fast moving targets/long integrations. Example screenshot:

For the Science template FORS2_img_obs_crsplit ("FORS2 Imaging Observation with exposure splitting for Cosmic Ray rejection") is the normal one for imaging. For long slit spectroscopy, need a FORS2_lss_obs_slit_fast after acquisition to do the through slit imaging to check target centroiding (I think), followed by a FORS2_lss_obs_off_fast for the science exposure. Phase2 will let you do imaging acquisition and spectroscopy observing template; this won't fail the verify but won't work - good candidate for TOM checking
3. For the Science template, this is normally setup (see 1st screenshot below for a 7x95s exposure in Bessell R (R_SPECIAL+76) filter. Link to standard FORS2 filters) with a -60" initial offset in Dec since the telescope pointing center (cross in 2nd screenshot) is quite close to the edge of the larger CCD, meaning the target could be off the CCD in a gap. The telescope then does small (1-2") dithers around taking 1 exposure (Number of Exposures per Setup) at each offset to make sure cosmic rays don't land on the target and in the same place.
The Phase2 UI doesn't check that the Number of Tel. Offsets, List of Tel. Offsets in RA and List of Tel. Offsets in DEC have the same number of entries and will loop back to the start and "replay" offsets for missing ones. This could result in the target going off the chip if you had a big initial offset. I find the list of offsets in RA and Dec hard to read/count so this would be a good candidate for autogeneration/verification by the toolkit.

4. The P2GUI has sensible defaults for readout mode etc - unsure whether this will be the same through the API ?
5. Target tab needs a rough position so to check per night visibility in order to get scheduled - can cause issues for fast moving NEAs, not an issue for slow-moving (distant) objects or sidereal targets.
6. For moving/Solar System observations, the OB Name must begin with the prefix MOV_ (could be checked by looking at Target.scheme in TOM Toolkit and populating OB name appropriately) and a corresponding ephemeris file (see example calling PAF generator notebook
7. The OB Must have a Time Intervals, normally via Absolute Time Constraints, and these need to be covered by the ephemeris - should be checkable by toolkit. See screenshots:

Time Intervals tab:

Top of Ephemeris file:

Suggested enhancements/"User Stories"

Here are my suggestions for what to work on in what order for adding functionality to tom_eso - feel free to discuss, question or ignore...

1. Submit imaging OBs for FORS2 for sidereal targets:
   """As a ESO user, I would like to create functional valid OBs for sidereal imaging targets from the TOM Toolkit Target detail page by filling in a short form of number of exposures per filter and specifying the observation window. This should:

   1.1. Create an OB with an appropriate OB name <TargetName>_<ObsMode>_<instance #> e.g. COSMOS_IMG_1 obeying the Naming Conventions and an appropriate Observing Description Name <ObsMode>_<approx. block length> e.g. IMG_20min
   1.2. The Target tab should be correctly populated with details from the TOM Target including Name, RA, Dec, epoch of proper motion and proper motions in RA, Dec
   1.3. The Time Intervals should match the window from the form
   1.4. A standard/default acquisition FORS2_img_acq template of "pick a star" with CCD=ANY, Get Guide Star from=CATALOGUE, Guide Star RA/DEC=00:00:00.000 should be created
   1.5. A science FORS2_img_obs_crsplittemplate should be created for each filter with the appropriate exposure times and telescope offsets with sensible defaults of an initial offset and small jitters from an optional part of the scheduling form
   1.6. The list of filters in the scheduling form should be the the FORS2 Standard Filters (minus the 2 order sorting filter GG435+81 & OG590+32). The list should show the standard astronomical names e.g. Bessell-R as well as the ESO filter names e.g. R_SPECIAL+76
   1.7. Ensure the total execution time is <1hr as required by the Service Mode Guidelines"""
   1.8. ESO expects there to be finder charts attached for sidereal targets as a human will do the target acquisition. The TOM should generate / check that any OB has a finder chart uploaded for sidereal targets.

2. Submit imaging OBs for FORS2 for slow moving Solar System targets. In addition to the above requirements, this should:
   2.1. Ensure the OB name has the correct (required) MOV_ prefix
   2.2. Generate a suitable positions for the Target tab in the middle of the window
   2.3. Generate and upload a ephemeris PAF file that covers the Time Interval requested. The TOM should ensure that this ephemeris file is uploaded and that an finder chart has NOT been uploaded for moving targets.

3. Submit long slit spectroscopy OBs for FORS2
   3.1 ESO expects there to be finder charts attached for sidereal targets, especially for spectroscopy, as a human will do the target acquisition. Not needed for moving targets (where an ephemeris file is needed instead). The TOM should generate / check that any OB has a finder chart or ephemeris file as appropriate.

4. Support for submitting ToO OBs for e.g. Rubin follow-up. The general procedures for ToO observations are here from which these specific requirements are extracted:
   Before the phase2 deadline for the period (TL: Could be a candidate for a (auto-generated?) reminder event in the new calendar functionality?) the following are required:
   4.1. A set of OBs that completely describe the required observations. The target coordinates should be set to RA=00:00:00.0, Dec=00:00:00. It is not necessary to submit OBs to fill up the entire allocated time: only one complete set of OBs is required. Quote "Multiple sets of OBs to cover different situations (e.g., faint and bright events) can be submitted. In this situation, the submitted OBs can over-subscribe the time allocated to the programme, which will be terminated once the actually executed time equals the allocated time. This is a unique exception in Service mode procedures applicable exclusively to ToO programmes."
   4.2. A complete README file, with particular attention to the ToO Information section, where any particular instructions for the execution must be clearly explained.
   4.3. Submission of finder charts is not required, since the targets are not known in advance.
   4.4. The naming convention for OBs must follow the the ToO convention with a OB name starting with TOO_ (for sidereal targets) and TOO_MOV_ (for non-sidereal/moving targets)

5. Submit OBs for spectroscopy for X-SHOOTER in staring mode 4.1. This should create XSHOOTER_slt_acq and XSHOOTER_slt_obs_Stare templates by default (other science templates such as XSHOOTER_slt_obs_AutoNodOnSlit to nod along the slit and better remove the Near IR background may be more applicable. These would require additional parameters to define the nod throw and optionallya small jitter box (along the slit direction)). 4.2. This should allow selection of the slit, exposure time and no. of exposures for each of the UVB, VIS, NIR arms and no. of sub exposures for the NIR arm

6. Submit Near IR imaging observations for HAWK-I

(4., 5. and 6. may be swapped based on other users' demands and requirements)

[jchate6]

Will break into individual issues during planning week

[talister]

I solicited extra input and review of this issue from ESO-using Rubin SSSC members in the LSST-DA Slack. Based on this feedback I have updated the issue as follows:

1. (From Cyrielle Opitom): "it would be interesting to cover the ToO case. In that case, example OBs are created before the beginning of the period and checked, and those OBs are then copied and adapted to the targets. With LSST follow-up in mind, this might be the most useful mode.". I agree, and have added a new sub-issue 3. ToO support into the list with link to the procedures and extracted requirements for tom_eso
2. (From Colin Snodgrass):
   2.1. "I wouldn’t list VISIR as a priority, it is already being decommissioned :(" - removed from targeted instruments
   2.2. Requirement for finding charts to be present for sidereal targets, particularly for spectroscopy. Added these as requirements 1.8, 2.3 and 3.1
3. (From both Cyrielle and Colin): Addressing the need for OB checking by ESO personnel raised under OB creation in the Phase2 UI 1.: "even OBs created through an API will be checked by someone (all the checking happens before the beginning of the observing period)" (that deadline for putting OBs into the phase2 for checking was yesterday, 2026-03-17 12:00 CET, for the current Period 117 (2026-05-01 -> 2027-04-30)). Additional comment from Colin: "It is a policy/technical discussion to have with ESO about how TOMs write OBs (especially for DDT/ToO) and whether or not they still need the human validation step before being sent to the telescope queue. I could imagine that there could be an agreement that instead the TOM is certified to produce sane OBs and these could bypass the checks, to allow really fast response and automated observing, but that needs discussion. I don’t know if that is already the case for any other systems that use the API, or if everything is still human-checked at the moment. There is always a final human in the loop at the telescope anyway, but it should be possible to have software that is more reliable than humans at 3am … :-) Obviously there would need to be some fairly robust testing of the TOM to have it certified if ESO is persuaded to go down that route."

An additional thing that occurred to me during this update is that things like the ESO Call for Proposals deadline and for submitting OBs into the phase2 would be great events for the new calendar functionality (particularly if they can be auto-fetched from the ESO website and auto-inserted into the calendar)