Guide to Maintaining the Instrument Configuration Files and Libraries in the OT.

The instrument components are configurable in two ways:
The contents of drop down menus can be changed - for example if a new filter is inserted into the instrument. In addition the instrument components are designed to apply rules to automatically determine the values of some parameters derived from the values of others. Most of these rules make use of lookup tables in order to derive the answer. The instrument support scientist is able to change the lookup tables that derive the values. Both of these are changed by use of the instrument configuration files described below.

The libraries are also of course maintained by support scientists.

Although both the instrument configuration files and the libraries can be modified by support scientists, the version acutally used by the OT is kept with the software under version control. (to make sure a user does not accidentally get an out of date copy after a software change). This means that it is necessary to co-ordinate with Malcolm if you want a new version installed as the working version.

Instrument Configuration files

Although the configuration files can be edited by instrument scientists they are kept in the CVS directories with the OT code. Before making changes make sure you start by copying the latest version. The files can be found in:
/ukirt_sw/oracot2/orac2/OT/ot/cfg_ukirt/

At the start of each file there is a history list - if you make a change, please make a one line summary of it here following the format of the examples. This makes sure that if there is a problem every one knows what changed and when. If you make major changes to any of the tables its probably helpful to note details in the comment that starts the table.

Configuration files currently allow the instrument support scientist to change two facets of the instrument: The values that an item may take (e.g. a list of available filters) and the parameters and lookup tables that are used by the instrument when it is deriving the value of an attribute from the values of others using the built-in rules.

The file is organised into a series of information "blocks". One "block" provides information on a single item, though this information may be complex. A block may not have comments within it - it is in fact delimited by the comment character. For practical purposes this means that you must comment each information block, as this will also delimit them, and do not delete comment lines that are already in the file.....

Blank lines are allowed anywhere and ignored. Comment lines (starting with "#") are ignored except that they delimit blocks (as outlined above).

Blocks are one of the following:

• keyword with a single value, e.g. DEFAULT_DISPERSER = "40lpmm".
• keyword with a vector of values, e.g. POLARISERS = {"none", "grid", "prism"}
• keyword with a 2D array of values, e.g. DISPERSERS (see below).

Note that each value may be a string or a number, however, it must be capable of being interpreted correctly by the OT, e.g. if the OT code is expecting a numeric value it will be unable to use a character string.

A vector of values is initiated by "{" and ended by "}", the values being delimited by commas.

A 2D table is written as a series of vectors, i.e. each "row" of the table should be written as a vector, and the rows placed one after another inside a surround brace of curly brackets. It is not necessary to place each row on a separate line, but it is recommended for readability !

Keywords are case insensitive, however, everything else is case sensitive.

This is an example of a single valued item:

# The default mode
DEFAULT_MODE = NDSTARE

This is an example of a vector of values, in this case the possible choices of acquisition mode for CGS4:

# The allowed acquisition modes
MODES = {NDSTARE, STARE, CHOP}

These choices then appear in the dropdown menu in the CGS4 component of the OT.

You can make drop down menu lists longer or shorter if need be.

The item below illustrates the use of a 2D array or table of values. This table is used as a lookup table by the CGS4 component in order to decide which filter to use at a given wavelength. The first column shows the upper wavelength for which the filter in the second column should be used. This example table for the 150 lpmm grating makes use of the fact that the first row in these tables is the order. In this case the look up is "two-dimensional", depending on both order and wavelength.

# For 150lpmm grating
FILTERS150 =
{ {"-", 1, 2, 3}
{1.07, NONE, IJ, IJ}
{1.50, NONE, B1, B1}
{2.05, B2, B2, NONE}
{2.35, B2, B6, NONE}
{3.80, B3, B3, NONE}
{4.25, B4, B4, NONE}
{4.50, B7, B7, NONE}
{5.2, B5, B5, NONE}
}

And finally below is an example of a more complex rule. This uses embedded lookup tables to implement the rule. It is a 2D look-up table for the allowed CGS4 gratings (dispersers). This table references the filter lookup tables defined above (and others not illustrated here). This is illustrates a feature of the look up tables in the configuration files - you may reference other look up tables within them.

# The dispersers available, and their approximate resolutions. Followed
# by spectral and spatial pixel sizes for each (arcsec/pixel), and finally
# by the x,y zeropoints for the instrument aperture.
DISPERSERS = {
{40lpmm, 800, ORDERS1, EXPTIMES40, FILTERS40, 0.61, 0.61, -0.55, 7.62}
{"150lpmm", 3000, ORDERS2, EXPTIMES150, FILTERS150, 0.595, 0.625, -0.55, 7.62}
{"echelle", 1500, ORDERS3, EXPTIMESECH, FILTERSECH, 0.41, 0.90, -0.03, 9.95}
}

In the lookup tables that define on-chip exposure times as a function of filter and estimated magnitude, the top row lists the magnitude selections. These are also listed in an array that defines the choices in the drop down OT menu for magnitude. The names of the magnitude ranges must match in the two tables for the exposure time estimation to work. You can add both a finer magnitude scale or in the case of CGS4 more wavelengths (IRCAM and UFTI use filter names).

If the user selects a magnitude range in the instrument component then the lookup table is used to determine the on chip exposure time. The number of co-adds is being determined by a simple algorithm, which is of the form :
exposure time x coadds = a fixed total
where the fixed total can depend on a small number of other instrument parameters - such as the value of the exposure time, or a filter. In other words its recommending an onchip exposure time and then suggesting a number of coadds that roughly correspond to the web page advice that if you are doing short exposures you should do enough to add up to a few seconds.

In the case of CGS4 the on-chip exposure time in the look-up tables is for the 1 pixel wide slit, and the OT applies a "rule" that if the user has selected the 2-pixel wide sllit these times are halved. This is true also for exposure times for the flats and arcs.

The idea was to start with very simple algorithms for exposure times, and see how useful they are /what the user reaction is. There are a number of ways of doing this more accurately - either by having more complex or configurable rules, or perhaps by tables of coadds embedded with the exposure times. If you wanted to apply a factor for expected seeing or anything like that then big complex tables are not the answer and its a case of thinking of better rules.

It is a current feature of the OT that you cannot change rules through the .cfg file , only the parameters they use.

The following configuration files are available:

cgs4.cfg - configures the CGS4 component

cgs4calunit.cfg - configures the CGS4 calibration unit component

ufti.cfg - configures the UFTI component

ircam3.cfg - configures the IRCAM component,

drrecipe.cfg - configures the data reduction recipe choices for all the instruments.

The ot.cfg and skycat.cfg files, which are found in the same directory, are used to configure the core OT, and should not be changed by non-experts. They do not follow the friendly format rules described above.

Maintaining the Libraries

The libraries are also kept in CVS with the OT code, and must be in a "library format" file called "name.lib", where "name" is the same as you want the name to be on the OT drop down "open" menu, and the file extension must be ".lib"

Library format files are created by using "new library" instead of "new program" in the File ... menu. Their format differs in the way folders are used, and because they are internally tagged as being a library. This means that the OT does not try to save changes in the original location but instead writes a local copy - thus ensuring that users can neither overwrite the UKIRT libraries, nor make themselves a private copy which can be opened using the same menu item as the UKIRT version. (They can however save a local copy to their disk and open it as if it were a science program, if they want ).

The best way to make changes to an existing library is to open as normal. Then make the changes to it that you want and save it - remembering to keep the ".lib" extension. At this point you will have a local copy of the library and can ask Malcolm or another member of the USG to install it as the working version.

To create a new library from scratch use "new Library" and then create observations in it , just as you would a science program. Remember to save it as a ".lib" file, with the name being the name you want to see on the drop down menu. The reason the names have to match is that, just like a science program, a library carries its name internally and thats the name which is displayed on the "menu bar" of the library when its opened. Since the library choices appear in a single drop down menu along with "open ..." and "new", having a lot of separate ones is probably not a good idea.

Note that if there are major changes to the OT either because of a bug fix or an additional feature then the library sequences will need to be updated to ensure that they get the new feature or bug fix in them properly. E.g. suppose you added a new item to the instrument and it had a default value set in the instruments .cfg file - the library contents would not have this additional item if they were created before it was fixed. To update them open the component affected by the change. If the change is one that does not "show" on the screen then change the value of the item it relates to. This will force the component to pickup the new attributes. At the moment this is a very manual process - however we believe that most such changes have now been made. The only change left that will have this effect on the library are changes to support the definition of different instrument apertures when IRPOL (or the FP?) is in use. It shouldn't be an issue that keeps happening once the system is stable and full commissioned.