Orac Instrument Interface Specification
Alan Bridger
orac015-oiis Version: 01 Original: 7 June 1998 Modified: 17 June 1998
This document sets out a specification of the interface that new UKIRT instruments must meet in order to fit into the control environment of ORAC.
1.0 Introduction
1.1 Purpose
This document is intended to outline the interfaces that an Instrument Control System must meet in order to fit into the UKIRT Orac system.
1.2 Scope
Any instrument intended for UKIRT, and to fit into the Orac control system being written for it, must meet certain interface requirements to achieve that goal. These are set out in this document. The intent is not to restrict instruments, indeed the interface is extensible, but to ensure as much as possible that the common features of Instruments and their control systems are implemented in a common way.
1.3 Overview
In order to fit into ORAC an Instrument System must meet a number of different interfaces, and provide software modules for some systems. These are described in this document starting with a general description and then specifying the requirements for each system in turn.
2.0 The Major Interfaces and Modules
2.1 Relationship to Other Systems
Figure 1 presents a simple context diagram for a typical Instrument Control System destined for UKIRT. Only some of the interfaces are relevant to Orac, those not will be considered only briefly. In addition there are interfaces and modules required not present on this diagram. These will be considered in later sections. Figure 2 from [O-12] gives an overview of the Orac system and will help the reader to understand where the instrument fits in the system.
FIGURE 1. Instrument Control System Context Diagram.
The externals in this diagram are:
Telescope Control System
This is the existing UKIRT telescope control system.
Observatory Control System
This is the system that has overall control of the observing - it is commanding and configuring the primary observatory systems, one of which is the instrument control system.
Data Handling System
This represents the system responsible for storing data and also for performing other services for the instrument control system (quick-look, provision of bad pixel masks etc.).
Array Control Hardware
This is the array or detector controller and acquisition hardware. It is controlled by the Instrument Control System and has no relevance to the interfaces into Orac, except to serve as a reminder that Orac considers the Instrument as including the array control.
Instrument Hardware
This represents the rest of the instrument hardware - the components etc. It has no relevance to the Orac interfaces.
Time Bus
This is the bus that provides time information to the Instrument. It has no relevance tot he Orac interfaces.
The major data flows on Figure 1 are:
instrument configuration info
This is how the component of an Observation Definition that represents an instrument configuration gets to the instrument system. This flow consists of a name of a file containing the configuration and the file itself.
instrument commands
This represents the commands sent to the instrument control system instructing it to configure itself or to acquire data or to perform some other function.
instrument status
This is a flow of status information - usually responses to instrument commands.
dhs commands
This is the flow of commands sent to the data handling system by the instrument control system asking for data to be stored, or perhaps to be imported.
dhs status
A flow of responses and status information to the dhs commands.
image data and header info
This is the data exported by the instrument for storage by the Data Handling System.
imported data
This is the flow of data requested by the instrument for import, usually to use for purposes like background subtraction etc. in the array controller.
array commands
This is the flow of commands to the array hardware.
array status
This is the status of the array hardware, usually in response to array commands.
array data
This is the flow of raw data from the array.
hardware commands
This is the flow of commands to the instrument hardware.
hardware status
This is the status of the instrument hardware, usually in response to instrument commands.
time information
This is the flow of timing information for use by the instrument.
telescope commands
This represents the commands sent to the telescope control system by the instrument. In most cases this is likely to requests to chop. Most higher level telescope commands are issued by the Observatory Control System.
telescope status
This is a flow of status information - usually responses to telescope commands.
The major interfaces are considered below.
2.2 Interface to the Telescope Control System
This interface is not controlled by the Orac project, but is well known ([X-11]). Instrument builders should contact UKIRT for more information.
2.3 Interface to the Observatory Control System
This is a major Orac interface representing how the instrument is controlled and configured by the Orac system. It is considered in more detail in Section 3.0.
2.4 Interface to the Data Handling System
This interface is not strictly controlled by the Orac system. However, as part of both Orac and the Michelle projects it has been decided to use the interface defined by the Gemini project ("ICD3", see [G-4]). Most instrument projects will be expected to follow this interface. A decision to follow another route should be made in conjunction with UKIRT as it would involve changes to the UKIRT Data Handling System.
2.5 Interface to the Array Hardware
This is entirely internal to the Instrument project, though it is suggested that interfaces similar to those used before are followed.
2.6 Interface to the Instrument Hardware
This is entirely internal to the Instrument project, though it is suggested that interfaces similar to those used before are followed.
2.7 Interface to the Time Bus
For information on this interface contact UKIRT.
2.8 Other software modules required
In addition to the interfaces described above Instrument builders will be required to meet interfaces to and provide software modules for parts of Orac not visible in Figure 1, namely the Preparation System and the Data Reduction System. The requirements for these are considered in Section 4.0 and Section 5.0.
3.0 Interface to the Observatory Control System
This is the interface that the instrument presents to the Observatory Control System to allow itself to be controlled as part of overall observation control. This interface is in fact to the Observation Sequencer and some more details may be found in [O-13]. From the discussions presented there we can see that:
- The Instrument Control System should present an interface that is that of a Drama task. An ADAM task interface is supported, but not recommended, and EPICS databases are only currently supported as long as they come with a Drama translation interface. Future enhancements might allow direct interfacing to EPICS databases, but this is not promised.
- The Instrument Control System must provide a certain minimum set of commands in order for it to fit into the Orac observing paradigm
- The Instrument Control System must provide a table readable by the Sequencer that describes its command interface - what the commands are, how they are invoked, and whether or not they may be run in parallel.
3.1 Instrument Command Interface
As the Sequencer is table driven the command interface of the Instrument can vary. However it is clear that certain commands must result in clearly defined actions that the Observatory Control System expects, and it is also useful if the names of the task actions are consistent across instruments for ease of support. None the less, the table driven approach does mean that the system is extensible and that new observing modes and techniques can be easily included (along with the appropriate extensions to the Preparation and Reduction systems) as can engineering actions.
Given the extensibility of the system what is defined here (Table 1) is a minimum interface that all Instrument Control Systems must support, and that the Observatory Control System knows how to use. The names of the commands are not yet confirmed, and might change before the final version of this document.
Command | Parameters | Action | Comments |
|---|---|---|---|
INITIALISE |
| Initialise the instrument |
|
DATUM | Device Name | Causes the instrument sequencer to datum the component "Device Name" | Device Name "ALL" is a special name to datum all devices. |
LOADCONFIG | ConfigurationName | Reads in the configuration given in the file referred to by "Configuration Name". | This does not cause a configuration of the instrument. The file contains information on how to configure the instrument into all the Configuration Types that it supports. It may also be an engineering configuration - this must be determined by the instrument system. |
SET | ConfigurationType (BIAS|DARK|FLAT|ARC|OBJECT|SKY) | Set the instrument to a given configuration type. |
|
TAKEFRAME | FrameTag, ObservationType (BIAS|DARK|FLAT|ARC|OBJECT|SKY) | Take a data frame of the type indicated by the parameter, attach the FrameTag to the data. | Note that a "SKY" is the same as an "OBJECT" except for its label in the header. |
ABORTFRAME | FrameTag | Abort data frame currently in progress - the FrameTag is given as confirmation. |
|
3.2 Instrument Configuration Parameters
This is the list of parameters that make up the configuration for an instrument. As can be seen from Section 3.1 the names of these parameters is in fact irrelevant to the interface to the Observatory Control System as they are hidden in the configuration file which is only read by the instrument system. However, the parameters used and preferably their name, must match up with the "user-selectable" items identified for the instrument as outlined in Section 4.1, as the output of the Preparation system will use these items and their names and the Chooser ([O-14]) will then use them when creating the configuration files. In addition it is clearly useful once more if the names and meanings of the items is consistent across instruments. Table 2 presents the minimum list required.
|
Item Name | Description |
|---|---|
EXPTIME | The "onchip" exposure time, in seconds. |
NUMCOADDS | Number of exposures to coadd together to make a frame |
There will be two separate lists - one for the normal user-selectable items and an engineering list for engineering configurations.
Possible example table of a more typical list?
4.0 Interface to and Modules for the Preparation System
The Preparation System of Orac is a variant of the Gemini Observing Tool designed for use with UKIRT. In order to prepare observations using this system the instrument builder must provide the following:
- A definition of the items that will be user-selectable in the instrument.
- Software modules (written as Java classes) that implement GUIs to present the items above, following the look and feel of the Observing Tool.
- A set of rules that define the default values for some items as a result of the chosen values of others.
- Software modules (written as Java classes) that implement the above rules.
4.1 User Selectable Items
This is a list of items that the observer (user) will be allowed to select the values of when defining an instrument configuration. There will also be items that the user will not be able to choose the value of (e.g. the internal focus position) but will be derived from other choices. It is the responsibility of the instrument control system to derive the values of these items. As a rule of thumb if an item is unlikely to be of scientific interest then it should not be a user-selectable item.
Clearly some of these translate directly into single instrument components (is the mirror set to imaging mode or spectroscopy mode?), and some will define the value of more than one component (a filter choice will usually result in defining the position of at least two filter wheels). The exact items required will clearly depend on the instrument, but consistency with existing instruments is strongly encouraged. A minimum list of items is: exposure time, number of exposures to be coadded in the instrument.
4.2 Rules for determining default values
Some items are clearly of scientific interest and value, but their values can in many circumstances be determined by simple rules. An example here would be a blocking filter for spectroscopy. In normal use the value of the filter can be determined from the central wavelength requested. However, it is also possible that the Observer may wish to override this for a valid scientific reason - perhaps to see lines from other regions in a higher order. The user should not be expected to provide the value, rather it should be defaulted according to the provided rules. The user may, however, override it.
4.3 Calibration items
The Gemini has a separate calibration unit, and so the Observing Tool has separate calibration components. UKIRT instruments typically supply their own calibration unit. To maintain the look and feel of the system the calibration unit of an instrument should be presented to the user as a separate component. However, many (or all) of the values in the calibration component can be deduced using rules of the type mentioned in Section 4.2 so software should be included to do this, in a very similar way as it is provided for the main instrument configuration screens.
4.4 Engineering Configurations
It is recognized that the items mentioned in Section 4.1 that should not be presented to the user as selectable are interesting to an engineering user. It may be highly desirable to be able to create and store engineering configurations for the instrument. This should be done by creating a separate engineering configuration component for the instrument - effectively a different instrument component. Once more the relevant software modules will need to be produced.
5.0 Interface to and Modules for the Data Reduction System
The Orac Data Reduction System is entirely driven by the header information found in the data files stored by the UKIRT Data Handling System. In order to coordinate the reduction of logically connected groups of data files the system uses "recipes" which describe how to use standard data reduction primitives to achieve the required data processing.
This leads to three sets of requirements placed on the instrument builders:
- The provision of adequate header information for the DR recipes and primitives
- The provision of DR recipes reflecting the processing required by the instrument
- The provision of primitives to provide certain specific algorithms required by the instrument.
Of these 1 will always be required, 2 will usually be required, though for simple instruments and observing modes it is envisaged that pre-existing recipes might be used, and 3 should only be required in some special cases. For the most part it is hoped that pre-existing primitives (e.g. Starlink applications) can be used.
5.1 Header Information
Information about the state of the instrument during the exposure is required by the data reduction system in order to automatically reduce the data. It is important that the information is provided and that the correct FITS item names are used otherwise the data reduction system will not be able to function as desired. Where FITS item names have already been used for similar components in previous instruments they should be used again in new ones. A list of such "standard" item names and the descriptions will be given in a later document.
In the situation where an instrument has a new (to UKIRT) component then a new name has to be provided. UKIRT should be consulted on the name, and perhaps other telescopes with instruments having similar components should also be investigated. The latter might make the provision of suitable reduction primitives easier as they may already exist for the other telescope. It should be recognised that such new components might lead to a requirement for new primitives.
5.2 Data Reduction Recipes
The OracDR recipes are what is used to tie together data reduction primitives to reduce connected "groups" of data files from instruments. For instance it is a recipe that defines how to reduce a typical "jittered" pattern of image data for photometry observations.
Instrument builders will be required to deliver a set of recipes to be used for the Observing modes that will be used with their instruments. For many common observing modes (e.g. jitter photometry, spectroscopy with two beam nods along the slit) these recipes will already be available and there may be no need to construct them - the builders can just indicate which ones are to be used. However, for new observing modes theses recipes will be required.
Information on how to write OracDR recipes will be given in a later document.
5.3 Data Reduction Primitives
The OracDR primitives are the applications found in major Data Reduction systems (Starlink, Iraf) that perform certain well defined tasks. These are as simple as subtracting two data frames or as complex as knitting together a set of mosaiked images. These primitives are used by OracDR recipes to act on the raw data files being produced by the instrument. Often the primitives rely on certain FITS header items being present which is why the standard names should be followed if at all possible.
The aim of OracDR is to use primitives written and maintained elsewhere, with Starlink being the current favourite source. New instruments will be expected to ensure that the primitives currently available can meet their requirements, and if not then the instrument team will need to produce new primitives. These should normally be written in the current favourite application environment. Porting primitives from other environments is clearly possible, as is asking or commissioning Starlink to produce them. The UKIRT Orac team would hope to persuade Starlink to take on and maintain any new primitives in any case.