3 FORMAT DEFINITIONS

One typical task of the Instrumentation Software is the handling of setup files. How this is done, and the way setup files are conceived, is described here.

3.1.1 Types of setup files

OS has to keep track of all setup parameters for every exposure, i.e. both the instrument setting and the detector or target setup. From the observer's point of view, it is on the other hand more practical to separate instrument specific setup parameters from the detector or target related setup parameters. And even more: it would be convenient if only a subset of all setup parameters have to be defined explicitly for each exposure, the rest of them being either set to default values or left to the current values.

· reference setup file: any setup file which contains all parameters defining unambiguously the complete setup for an exposure, as needed by OS. This is needed to set all parameters to certain default values, as they may be undefined or have improper values after start-up or initialization. The proper filtering of FITS header data of an archived exposure, combined with the data contained in the different logs, should for example yield such a complete setup file, containing all instrument and target parameters. Reference setup files may be shared among different templates. For every standard observation mode there is at least one reference setup file, and normally templates should be able to use it without modifications. In fact, several of the setup parameters (e.g. position of a mirror) contained in the reference setup files should only be accessible by maintenance staff (see [6] for the different responsibilities of the two UNIX users associated to each instrument).

Remark that not every single FITS header line of an archived exposure has a matching line in a reference setup file. FITS headers contain lots of status information which is impossible or very difficult to influence, e.g. the wind speed. All instrument/telescope parameters which cannot or should not be modified on-line shall not be included in a reference setup file. A typical example is the detector identifier for an instrument with only one detector, as normally the exchange of detector is a time-consuming, off-line operation.

· partial setup file: any setup file that is not a complete setup file, i.e. which cannot be used as a reference setup file. Examples are an instrument setup file and a target setup file, each of which do not have the parameters contained in the other. Another example is a detector setup file.

Remark that this differentiation is rather for the internal use of the INS software. The observer will mainly be confronted via the P2PP GUI with Template Signature File parameters and not with setup files, which instead are used within the control code (Template Scripts, OS, ICS and DCS).

The setup command is always incremental, i.e. it only modifies the setup of functions that are contained in its list of parameters. Additional setup commands will use the actual position or last definition as starting point, i.e. there is no automatic reset to the values contained in the reference setup file, and functions that are not given in the list of parameters of the setup command stay where they are.

3.1.2 Setup file handling

The default search path for setup files is normally defined by the INS_ROOT directory structure in conjunction with the environment variable INS_USER (see 3.7), which contains a single directory name¹. At present INS_USER is basically always set or defaulted to SYSTEM; any other value is not supported any longer.

All commands may return errors which are the normal file access errors. More detailed information can be found in the user manuals of the tools provided by ESO to deal with this ([16] and [17]).

3.1.3 Setup file format

For instruments controlling more than one detector, the DET category needs to be extended with an index (e.g. DET1, DET2). Remark that the keywords belonging to the DETx category written in the FITS header should NOT contain indices. So it is the task of DCS to strip these indices off before recording the corresponding keywords in the FITS header.

3.2 OBSERVATION BLOCKS AND TEMPLATES

3.2.1 Introduction

Setup files offer a great deal of flexibility for setting up an instrument, but this flexibility and level of granularity is not always needed or desired. The observation of a single celestial object may involve several exposures in a particular order, each with some specific settings. Defining such an observation or repeating it on a different target should therefore be only a matter of (re)defining a few parameters, instead of the complete setup files. In other words, there have to be standard sequences (see also [6]), each with its own limited set of parameters. These parameters will complement (overwrite) the information contained in the reference setup file corresponding with this mode of observation.

Such a top-down view of operations is also part of the VLT On-line Data Flow (see [14]). Some of the terms defined in the VLT On-line Data Flow documents are repeated here, with particular emphasis on how they map into the VLT INS Software concepts described above and in [6]. Support for these concepts is extremely important, as it enables a unified view of the data flow. Moreover, pipeline reduction, automatic quality control and long-term trend analyses all depend heavily on these concepts.

More detailed and some complementary information can be found in [5], the ICD between VCS and P2PP/Scheduling Tools.

3.2.2 Templates

A template is a Sequencer script (see [12]), dealing with the setup and execution of one or more exposures. It is literally a "template", to which a set of parameters belong whose specific values determine the exact behavior of its execution. The end-user who operates an instrument via templates will only be exposed to a limited set of template parameters, instead of all the parameters of the setup files.

Technically speaking (in Data Flow parlance) a template is an object belonging to the Template class, and has several components, one of them being the Sequencer script described above. The other components of the template-object which are seen at some point by the VLT Control Software are as follows:

· template signature file: contains the description of the parameters (name, type, range, ..), in short hierarchical format, together with some information about the template itself. The parameter description is used to do a trivial type/range checking when values are entered.

During development of any instrument, one of the tasks of the Instrument Scientist will be to identify the modes in which the instrument is going to be used, and for which template support is needed. I.e. the way certain types of observations are performed is a characteristic element of the instrument, and not of the individual observer. For every instrument the developers are responsible for providing these templates, together with their signature and test observation blocks.

Examples of template files are provided with the Template Instrument Software, in particular in the cmm modules xxotsf for the template signature files (e.g. file xxotsf/src/XXXX_optimg_cal_bias.tsfx) and xxoseq for the template call files (e.g. file xxoseq/src/XXXX_optimg_cal_bias.seq)

3.2.3 Observation Blocks

Observation blocks represent a high level view of VLT operations. An observation block is the smallest schedulable observational unit for the VLT. It is a rather complex entity, containing all information necessary to execute sequentially and without interruption a set of correlated exposures, involving a single target (or stated more correctly, a single telescope preset). It contains a.o. one or more template calls, i.e. it describes what Sequencer scripts to call with which parameters. Consequently, during Phase II Proposal Preparation, observers will have to build observation blocks, using the tools provided for that purpose, by selecting templates (part of the P2PP toolset), defining parameters, and giving additional requirements for scheduling and data reduction (again part of the P2PP tools).

For observation blocks involving target acquisition, the first template must be an acquisition template. This acquisition template will always be executed by VCS, independent of the history of observations, thereby guaranteeing that observation blocks remain independent units and are not affected by reordering. The subsequent templates can each deal with one or more exposures.

So the basic unit for the entire VLT Data Flow is the observation block. Although within VCS smaller units exist (i.e. the unit for OS Server is an exposure), VCS obviously needs to be aware of this concept, and must know how to decompose observation blocks it receives from the Scheduler into units of its own. Besides, the end-user will want to dispose within VCS of the same tools as (s)he was exposed to during P2PP. This means that:

· There is a generic tool to "understand" observation blocks; it will decompose an observation block into templates, and templates into single exposures with their corresponding setup. The latter setup and execution commands will be sent to OS. This generic tool is based on the functionality provided by the VLT Sequencer tool and is called Broker for Observation Blocks (BOB). It is described in [34].

Remark however that VCS itself does not allow to build observation blocks - that task is left uniquely to P2PP. And INS/OS is not directly involved in - nor affected by - the concept of observation blocks, except perhaps that INS/OS will be passed some observation block information which it will have to record in the FITS header.

Examples of Observation Block Description files are provided with the Template Instrument Software, in particular the cmm module xxoseq (e.g. file xxoseq/src/XXXX_optimg_cal_bias.obdv)

3.3 ALIAS CONVERSION TABLES

The concept of alias tables, included in previous versions of this document has been dropped and is not supported any more in the INS common software.

3.4 INSTRUMENT DICTIONARY

Each instrument has a dictionary containing a list of permitted keywords for setups, logs and FITS headers. Setup keywords have to be checked by OS against these dictionaries.

Although standard installation procedures (via the VLT Makefile) have to install the dictionaries in $VLTROOT/config, there can also be a local or private copy under the $INS_ROOT directory - see section 3.7.

More detailed information about dictionaries can be found in [8] and in document [1] of ESO's Data Interface Control Board.

3.5 INSTRUMENT CONFIGURATION FILES

The Instrument Configuration Files (identified by a .cfg suffix)² indicate the specific elements that are (or should be) mounted in an instrument at a given time. These files are used by the Instrumentation Software to determine the instrument configuration needed to execute a specific exposure or exposure sequence and check if these exposures are at all possible.

The Configuration Tool ctoo, described in [30], helps Instrumentation Software, in particular MS, to create, modify, load and save an Instrument Configuration File.

OS and ICS should read these files at startup. Having and storing this information in the form of files helps to keep some parts of the Instrumentation Software as OLDB-independent as possible.

Instrument Configuration Files are in PAF format (see [8] for a description of keywords and functions):

3.6 FITS COMPRESSION

3.7 DIRECTORY STRUCTURE

The directory structure common to all instruments is graphically described below. This should be considered the minimum structure, and each instrument may add its own particular subdirectories to store files which do not fit under any of the common subdirectories.

In the following INS_ROOT is the environment variable containing the root-path for a particular instrument. The value of INS_USER is assumed to be set to SYSTEM, which is basically the value largely used by all instruments and users.

In order to have a guaranteed minimum disc space available for acquisition data, the DETDATA subdirectory can e.g. be symbolically linked to a directory on one dedicated discs. Provided such a disc has a sufficiently large capacity, and considering that detector frames are substantially larger than setupfiles etc., one can also put the entire INS_ROOT directory tree on this disc.

For instruments dealing with two or more detectors, there can be a DETDATAx subdirectory per detector; this allows then - again via symbolic links - to store the data of each detector on a physically different disc drive, thereby reducing head movements and overheads during parallel read-out.

The environment variable INS_USER is supposed to be set or defaulted to SYSTEM; any other value is not supported any longer.

The TEMPLATES subdirectories should - as the name suggests - be used for template related files (i.e. within the context of the VLT Data Flow and Observation Blocks).

Instrument or package specific sub-directories may be added only under the MISC directory.

The MISC directory is also the standard location for files, which have the format defined and used by the CCS sampling tool.

Other files, such as the motors configuration and detector .dbcfg files, mentioned in [6], concur to the definition of the instrument configuration, but are not treated here (see instead [35], [23], [24], [25]).