% origin: ftp://www.ast.cam.ac.uk/pub/lpinfo/manuals/ldss_manual.tex 26nov96
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% LDSS-2 Observer Manual                 
% ----------------------
%
% This version was produced on 26 Aug 1992 by Jeremy Allington-Smith
% while at LPO 
% Substantially re-written in August 1993 by Steve Maddox
%
% This file is the LATEX source for the LDSS-2 Observer Manual. 
%
% The paste-in figures are available separately as masters of the correct 
% size for photocopying, cutting to size and gluing in. Each figure master
% is labelled with the figure number. Make sure to renumber these if extra 
% figures are added. Caretaker of these is currently Steve Maddox
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentstyle[11pt]{article}
\setlength{\topmargin}{-10mm} 
\setlength{\textheight}{240mm}
\setlength{\textwidth}{160mm}
\setlength{\oddsidemargin}{0mm}
\parskip 10pt
\parindent 0pt
\pagestyle{headings}

\begin{document}

\begin{center}
\LARGE{\bf LOW DISPERSION SURVEY SPECTROGRAPH LDSS-2}\\

\vskip 2.0cm 
\LARGE{\bf Observer Manual}
\end{center}

\vskip 3.cm
\begin{center}
\bf{ The Durham-RGO LDSS-2 team}\\
\end{center}

\begin{center}
{\bf \today }
\end{center}

\vfill

{\it This document is intended to tell observers how to prepare and
carry out observations with LDSS-2. 
It also contains information about operations which would not normally
be carried out by observers but which are included for information and
as a guide for support astronomers. 
}

\vskip 2.0cm 

\newpage

\phantom{.} 
\vskip 5.0cm 
\begin{center}
\begin{tabular}{lll}
\multicolumn{3}{c}{\bf LDSS-2 team}\\
\\
Project Manager         & Dave Gellatly           & RGO         \\
Project Scientist       & Jeremy Allington-Smith  & Durham      \\
Mechanical assembly     & John Webster            & Durham      \\
Optics                  & Sue Worswick            & RGO         \\
Control system          & Graham Shaw             & Durham      \\
                        & John MacLean            & RGO         \\
                        & Philip Taylor           & RGO         \\
LEXT software           & Nial Tanvir             & Durham      \\
Mask manufacture        & Mike Breare             & La Palma    \\
\end{tabular}
\end{center}

The LDSS-2 team gratefully acknowledge the support of Richard Ellis and Karl
Glazebrook (Durham), Keith Taylor (AAO), Paul Jorden, Paddy Oates and Robert
Laing (RGO) and the technical staff in Durham (under Billy Hogg and Tom
Jackson), RGO and La Palma and the staff astronomers and telescope operations
staff on La Palma.

This manual was first draughted by J.Allington-Smith and 
subsequently revised and updated by S.Maddox. 

\vfill

\newpage

\tableofcontents

%\vspace{5mm}
%RELATED DOCUMENTS
%\begin{itemize}
%\item LDSS-2 Technical Description
%\item LDSS-2 Drawings and parts list
%\item LEXT Reference Manual
%\item LEXT Installation Manual
%\end{itemize}

\newpage
\section{The LDSS-2 Instrument}
\label{sec-overview}
\subsection{Overview}
LDSS-2 is a common-user wide-field multiaperture spectrograph mounted
at the Cassegrain focus of the 4.2m William Herschel Telescope. 

{\it LDSS} stands for `Low Dispersion Survey Spectrograph'. 
LDSS-2 is the second such instrument. 
The first, known as LDSS or LDSS-1, is a non-common-user instrument at
the AAT. 
LDSS-2 excels at obtaining spectra of large numbers of faint objects.
Its high throughput and excellent sky subtraction lead to spectacular
performance at very faint limits while its relatively large field of
view and multiobject capability provide a large multiplex advantage
for statistical projects.

LDSS-2 is similar to LDSS-1 but is easier to operate, having a greater
level of automation. 
It also has a different optical design to cope with the WHT's f/11
Cassegrain focal ratio and to provide better images to exploit the
superior seeing on La Palma. 
The optics of LDSS-2 form a focal reducer based on the design of
Charles Wynne and Sue Worswick, and can be used for direct imaging
over an $11'$ field of view. 

LDSS-2 operates as follows. 
The telescope is focussed onto a multiaperture mask held in an
8-position wheel. 
The light then passes through various apertures cut in the mask and
enters the collimator which converts the input f/11 beam into parallel
light, before passing it through either a filter and/or a grism. 
The light is then focussed by the camera onto an external detector
with a final focal ratio of f/2. 
The camera can be moved along the optical axis slightly to allow the
images to be optimized for different wavelengths of interest. 
Removable Hartmann masks are provided in the filter and grism wheels
to aid focussing. 

Four grisms are provided of which 3 can be mounted in the grism wheel
at the any one time. 
These cover a range of spectral resolution $200 < R < 1000$, where $R
\equiv \lambda/\Delta\lambda$. 
Up to 7 filters can be mounted in the filter wheel at once. 
Three broad-band filters (the BVR Harris  set as used by NOAO) are
provided together with  3 other filters designed for use in
spectroscopic mode to suppress unwanted orders. 

By using clear positions in the aperture and grism wheels, LDSS-2 can
be used to give direct images in the chosen filter passband over a
very wide field of view. 
It thus doubles as a high throughput, wide-field imager.
This capability is essential for target acquisition and allows
astrometry for mask manufature to be obtained in near real-time. 


Fig.~\ref{fig-schematic} shows a schematic of LDSS-2 and how it
relates to the telescope system and Fig.~\ref{fig-optics} shows the
main elements of the optical system (excluding the reconfigurable
components). 
The main properties of LDSS-2 are summarized in
Table~\ref{tab-summary}. 

\begin{figure}
\vspace{220mm}
\caption{Schematic of LDSS-2}
\label{fig-schematic}
\end{figure}

\begin{table}
\caption{Summary of LDSS-2}
\label{tab-summary}
\begin{center}
\begin{tabular}{||l|l||}
\hline
\hline
\multicolumn{2}{||l||}{Instrumental properties} \\
\hline
Image scale at f/11 telescope focus     & 4.51 arcsec/mm \\
Image scale at f/2 camera focus         & 24.6 arcsec/mm\\ 
Collimator field of view                & 11.5 arcmin diam\\
Image size (90\% encircled energy)      & $<$ 25--30$\mu$m imaging\\
                                        & $<$ 40$\mu$m spectroscopic\\
Design wavelength range                 & 370--750 nm\\
Dispersions                             & 4 grisms: 10--47nm/mm\\
Peak efficiency of main optics          & 84\% at 600nm\\
Aperture wheel                          & 8 positions (7 masks + 1 clear) \\
Filter wheel                            & 8 positions (BVR + 1 clear)\\
Grism wheel                             & 3 grism positions + 1 clear + 2 Harts\\
Access doors                            & 2 doors, remotely locked\\
\hline
\hline
\multicolumn{2}{||l||}{Tektronix CCD detector} \\
\hline
Format                                  & 1024 $\times$ 1024 \\
Pixel size                              & 24 $\times$ 24 $\mu$m \\
Image scale                             & 0.59 arcsec/pixel\\
Detector field of view                  & 10.1 $\times$ 10.1 arcmin\\
Gain 					& 1.3 e/ADU \\
Read noise				& 4 ADU rms \\
Bias 					& 2300 ADU\\
\hline
\hline
\end{tabular}
\end{center}
\end{table}

\begin{figure}
\vspace{70mm}
\caption{Main optics of LDSS-2, showing (from left to right) the Cassegrain
focal surface, collimator, pupil plane, camera and detector window. Some rays
corresponding to angles on the sky up the full field of view are shown.}
\label{fig-optics}
\end{figure}

%The next two sections of this manual describe the instrument itself 
%and the LEXT software package in more detail. 
%Then the rest of the manual is organized into sections dealing with: 
%what you need to do to plan your observations with LDSS-2
%(Section~\ref{sec-plan});
%what you need to do when you arrive at the WHT before you start
%observing (Section~\ref{sec-before});
%how you carry out the observations (Section~\ref{sec-observe});
%and how to reduce the data (Section~\ref{sec-reduce}).
%Each section includes a checklist to help you remember what to do. 

\newpage 
\subsection{Aperture Masks} 

The multiaperture masks consist of a number of slits (typically
300$\mu$m wide = 1.5 arcsec) cut in a brass disk. 
The masks may be made at the telescope using a specialized
manufacturing facility which provides masks of very high quality which
can be made close to the time of observation. 
If arranged with technical staff, masks can be made in `real-time'
from coordinates supplied from an analysis of a direct image taken
with LDSS-2. 
To allow accurate sky subtraction for each object, it is 
best to use slits at least 5-10'' long so that there is plenty of 
sky either side of the object spectrum. 
In principle this means that there is space to fit 60-100 spectra on
the detector, but the distribution of objects on the sky means that
this maximum is not achieved in practice.
A typical field will have space for about than 30-40 spectra. 

The masks must be positioned flat in the focal plane of the telescope
so that images are in focus at all positions over the mask. 
This means that the masks can not be tilted to allow any form of slit
viewing. 
The acquisition of each field uses fiducial holes in the mask as
described in Section~\ref{sec-acquire-multislit}. 

In some cases, you may wish to use LDSS-2 with a longslit. 
Normally a traditional longslit spectrograph (e.g.  ISIS/FOS-2) would
be preferred for single object observations since these offer
adjustable slit-jaws that are inclined to permit slit-viewing.
However there may be occasions where you need to mix multiaperture
and longslit work, especially for flux calibration where you might
observe a spectrophotometric standard through a longslit. 
Here you have two choices: 
\begin{itemize}

\item Treat your longslit observation as a multiaperture observation where 
there happens to be only one slit. In this case, you would design and 
manufacture individual masks for each field with fiducial holes to allow
the telescope to be precisely aligned with the target field.

\item Use a longslit mask that has already been manufactured 
(see below). 
Since this will not have fiducial holes, 
you will need to use a variant of the usual target acquisition technique.

\end{itemize}
Target acquisition procedures are discussed in 
Sections~\ref{sec-acquire-multislit} and \ref{sec-acquire-longslit}.

In addition to the multiaperture masks that are custom-made for each target
field, there are masks already manufactured that have special functions.

\label{sec-specialmasks}
\begin{description} 

\item{\bf Matrix mask:} 
A regularly spaced square grid of holes used for positional calibration and
distortion mapping. The pitch is 10 arcsec. See Section~\ref{sec-distort} for 
further information.

\item{\bf Focus mask:} 
This consists of three well-spaced parallel slits, each of dimensions $0.32 
\times 90$mm ($1.4 \times 405$ arcsec). This is required for the
Hartmann tests to check focus, rotation and tilt. See Section~\ref{sec-focus}
for further information.

\item{\bf Standard longslit mask:}
A single, centrally placed longslit for traditional longslit spectroscopy. 
Dimensions are $0.32 \times 50$mm ($1.4 \times 225$ arcsec).
{\it Note that this (and all the other masks) is not inclined 
so cannot be used with the slit-viewing TV system.}

\item{\bf Wide longslit mask:} 
For spectrophotometry so that all the light from the object will go down 
the slit. Dimensions are $1.2 \times 45$mm ($5 \times 200$ arcsec).

\item{\bf Very wide longslit mask:}
Even wider than the wide longslit for really bad seeing or for easy
acquisition. Dimensions are approximately $15 \times 200$ arcsec. Note that
the edge quality is poor. 

\end{description}

\subsection{Grisms and Filters} 

LDSS-2 has four grisms, of which 3 can be mounted in the
grism wheel at the any one time.
These grisms give a choice of three spectral resolutions as listed in
Table~\ref{tab-grisms}. 
The normal configuration is to have the Low, Medium/Blue and High
dispersion grisms in the wheel, with the remaining 3 places taken by 
the Hartmann masks HU and HD, and a clear position. 

Up to 7 filters can be mounted in the filter wheel at once. 
Three broad-band filters (the BVR Harris  set as used by NOAO) are 
supplied for direct imaging. 
For information on the Harris prescription BVR filter set, see NOAO
Newsletters 11, 12 and 14.
Three other filters are available which have been designed for use in
spectroscopic mode for spectroscopic order 
selection and wavelength isolation. 
All these filters have been antireflection coated, and are specified
to be flat to 2$\lambda$ with surfaces parallel to 1 arcmin.
Their overall thickness is held to +0.1mm, -0.2mm. 
These are detailed in Table~\ref{tab-filters}, and the throughputs
plotted in Appendix~\ref{app-filterthroughput}.

Additional filters in the A\&G unit can be used using the ICL commands 
MAINFILTC and MAINFILTND, but these give an unvignetted field of only
9 arcmins.  
RGO also have some neutral density filters which can be installed in
the LDSS-2 filter wheel. 
% where are these...?
Note that separate neutral density filters are provided in the
comparison lamp system. 

Observers may supply their own filters. 
The specification is that the diameter must be 100mm ($\pm$0.1mm) and
the thickness less than 8mm.
In the case of user-supplied filters, staff should be notified in
advance to give time for any additional spacers to be manufactured.

\begin{table}[htbp]
\caption{Grisms} 
\label{tab-grisms}
\begin{center}
\begin{tabular}{||l|c|c|c|c|c|c||}
\hline
\hline
Grism    & ruling  &blaze &central & peak      &dispersion &  nominal   \\
name     & density &\multicolumn{2}{c|}{wavelength}                             
                                   &efficiency &           & resolution \\
         & (/mm)   & (nm) & (nm)   &           &(\AA/pixel)& (\AA)      \\
\hline
Low      &  150    & 550  & 550    & 0.82      & 11.3      & 28.3 \\
Med/Blue &  300    & 500  & 550    & 0.76      & 5.3       & 13.3 \\
Med/Red  &  300    & 600  & 550    & 0.74      & 5.3       & 13.3 \\
High     &  600    & 500  & 420    & 0.64      & 2.4       & 6.0  \\
\hline
\hline
\end{tabular}
\end{center}
%\end{table}
%\begin{table}
\caption{Filters supplied}
\label{tab-filters}
\begin{center}
\begin{tabular}{||l|l|l||}
\hline
\hline
Name    & Prescription                  & Function           \\
\hline
PB      & 1mm BG12, 2mm BG39, 1mm GG385 & Harris broadband B \\
PV      & 2mm GG495, 2mm BG39           & Harris broadband V \\
PR      & 2mm OG570, 2mm KG3            & Harris broadband R \\
\hline
S1      & 3mm GG375                     & blocks 2nd order   \\
S2      & 3mm GG420                     & blocks 2nd order   \\
S3      & 1mm BG25, 1mm BG39, 1mm WG280 & transmits passband around 400nm\\
\hline
\hline
\end{tabular}
\end{center}
\end{table}

% where are these...?
%
% N1     & 5mm BK7                      & neutral density ND0.5 \\
% N2     & 5mm BK7                      & neutral density ND1.5 \\
%

\subsection{Performance of LDSS-2}
\label{sec-perf}

The throughput of the instrument is very high, peaking near
60\% for a wide wavelength range as shown in Fig.~\ref{fig-efficiency}
which summarizes the performance measured in the laboratory.
The whole system including the atmosphere, telescope and 
detector efficiencies gives an
overall throughput of around 20\%, as shown in
Table~\ref{tab-thru}. 

\begin{figure}
\vspace{220mm}
\caption{Laboratory measurements of the efficiency of, (a) the main optics
(camera and collimator), (b) the grisms and (c) the CCD as labelled (courtesy
of Paul Jorden and Paddy Oates (RGO).}
\label{fig-efficiency}
\end{figure}

\begin{table}
\caption{ Summary of throughput for LDSS-2 with the Med/Blue grism and the
Tektronix 1024 CCD.} 
\label{tab-thru}
\begin{center}
\begin{tabular}{||c|c|c|c|c|c|c|c||}
\hline
\hline

Wavelength (nm) & Optics  & Grism   & CCD    & Atmosphere & Telescope & 
Total & Measured \\
\hline
  370   &   -    &  0.32  &  0.40  &  0.69  &  0.72  &   -   &   0.17 \\
  400   &  0.58  &  0.52  &  0.58  &  0.76  &  0.72  &  0.10 &   0.08 \\
  450   &  0.73  &  0.67  &  0.63  &  0.85  &  0.72  &  0.19 &   0.16 \\
  500   &  0.77  &  0.71  &  0.63  &  0.89  &  0.72  &  0.22 &   0.20 \\
  550   &  0.76  &  0.78  &  0.67  &  0.91  &  0.72  &  0.26 &   0.21 \\
  600   &  0.70  &  0.84  &  0.69  &  0.92  &  0.72  &  0.27 &   0.22 \\
  650   &  0.64  &  0.80  &  0.70  &  0.95  &  0.72  &  0.25 &   0.19 \\
  700   &  0.57  &  0.68  &  0.69  &  0.97  &  0.72  &  0.19 &   0.14 \\
  750   &  0.48  &  0.51  &  0.64  &  0.98  &  0.72  &  0.11 &   0.09 \\
  800   &  0.43  &  0.37  &  0.56  &  0.99  &  0.72  &  0.06 &   0.05 \\
\hline
\end{tabular}
\end{center}
\begin{center}
\begin{tabular}{||l|l||} 
\hline
Data: & \\
\hline 
Optics          &Lab measurements by RGO \\
Grism           &Lab measurements by RGO and Milton Roy for Med/Blue grism \\
CCD             &Laboratory measurements by RGO \\
Atmosphere      &RGO Technical note by D. King assuming 1 airmass\\
Telescope       &Assumes 2 reflections each of 85\% efficiency \\
Total           &Total throughput estimated from the above data \\
Measured        &Throughput derived from observations of spectrophotometric \\
                &standard BD +25 3941 slit by Graham Shaw (Durham) - these \\
                &were done with a wide slit to include all the light \\
\hline 
\end{tabular}
\end{center}

Note: For the Med/Red grism, the predicted and measured throughputs at 
600nm are 0.28 and 0.23 respectively. This is in good agreement with the
results for the Med/Blue grism.

\end{table}

These figures mean that in an 1800 second integration with the medium
grism, a galaxy with $b = 24$ will produce 63 detected photons per
pixel in the wavelength direction near 450nm.
The corresponding counts from dark sky will be 178 detected photons
per pixel, so the sky noise dominates the read noise.
Assuming that all of the light from the object goes through the
slit and is spread over two pixels in the spatial direction, the 
signal to noise will be 3 per pixel in the wavelength direction. 
In practice it has been found that a total integration time of 4 hours
will give signal to noise adequate to measure redshifts for 80\% of a
sample of field galaxies with $23 < b < 24.$ 

Note that acquiring a field is a relatively complex and time-consuming
process, and even with the aid of the LEXT package will take about
20-30 minutes for each new mask.
This overhead means that it becomes inefficient to use the instrument
for total integrations much shorter than 60 minutes. 

\newpage
\section{LEXT} 
\label{sec-lext}


The LEXT software package is an integral part of LDSS-2, in that it
enables the complex operations required to observe with multislit
masks to be carried out quickly and efficiently. 
The program performs three essential functions: it allows the observer
to design the masks; it enables rapid acquisition of the target fields
by calculating the telescope offset required to map the slits onto the
targets; and it simplifies the data reduction.
It also offers many general data processing tools.
The present version has been developed for LDSS-2 but should work
equally well for LDSS-1.
The original LDSS-1 version was written by Richard Hook 
with modifications by staff at AAO.

LEXT is a Starlink-compatible program which runs on a workstation at
the telescope but can also be used at Starlink nodes. 
Thus you can use it at your home Starlink node to design the masks
before the observing run and afterwards to reduce your data. 
The complete package includes the executable image, source code, help
files, LEXT procedures and DCL command procedures (for VMS) or
make files (for UNIX) to maintain the software.
The software is predominantly written in Fortran, and depends on several
Starlink ADAM and FIGARO subroutine libraries.  
Refer to the {\it LEXT Installation Guide} for details of installation. 

It should be noted that LEXT is resource-hungry and will probably need
special quotas. 
Extended use for long periods (for example at the telescope) may
eventually cause problems with virtual memory resources since the DSA 
library, which LEXT uses, appears to be a little careless on occasions
about freeing virtual memory. 
If this happens, the solution is to exit from LEXT and restart. 
For this reason, and as a normal wise precaution, you should make sure
that important intermediary data sets are saved to external disk
files. 

The following section gives a general introduction to the LEXT package. 
More specific information about using LEXT is given in:
Section~\ref{sec-maskdata} for preparing masks;
Section~\ref{sec-distort} for calculating image distortion corrections;
Sections~\ref{sec-acquire-multislit} and \ref{sec-acquire-longslit}
for acquiring fields; and Section~\ref{sec-reduce} for reducing data.
These sections should act as a user guide, and 
hopefully contain the essential
information required to run LEXT for most observing programs. 
A more comprehensive description of the functions available in
LEXT is presented in the {\it LEXT Reference Manual},
(Appendix~\ref{app-lext}). 
Much of this information is also available in the large on-line HELP
library which can be accessed from within the package.

\subsection{Startup and basic concepts}

LEXT is a monolithic program which is essentially a tool-kit to
support multiobject instrumentation. 
Although experienced users can gain the most from its powerful
features, inexperienced users can carry out sophisticated
target acquisition operations with ease by making use of several 
special {\it procedures} written especially for LDSS-2.
There are procedures to carry out all the essential functions of LEXT, 
and for most observers they will provide the easiest way to use LEXT. 
A list of the most useful procedures is given in Table~\ref{tab-proc}. 

Several logical names and symbols must be set up to run LEXT and there
must also be some start-up files in your LEXT directory. 
The details of what is required are given in the LEXT manual. 
At the telescope, you will access LEXT from the account LEXTOBS, most
conveniently run from the LPVS3 VAXstation. 
% ie a different one to the icl progs 
This account automatically sets up the relevant logical
names and symbols, and LEXT can be invoked from DCL by simply typing:
\begin{quote}
\$ {LEXT}
\end{quote}
After some startup messages, you should arrive at a command line prompt:
\begin{quote}
LEXT -- IMAGE 1 $>$
\end{quote}
From here you can invoke any of the LEXT functions; a good one to start with 
being:
\begin{quote}
LEXT -- IMAGE 1 $>$ {\bf HELP}
\end{quote}
The on-line help facility uses the Starlink portable HELP facility which is
different in some respects from the VMS HELP facility. In particular, if 
you request help on a command {\it and} its qualifier on the command line,
you should leave a space between them. For example: {\bf HELP MAKEFF /PLOT}
will work but {\bf HELP MAKEFF/PLOT} will not. Alternatively you can
type {\bf HELP MAKEFF} and then type {\bf /PLOT} in response to the
HELP facility prompt for the MAKEFF topic.

LEXT operates in two modes: { IMAGE} mode for handling image data such
as acquisition images and the 2-d spectra; and { LIST} mode for
handling tables of data, such as a list of object positions.
There are several special types of LIST used by different LEXT
functions. 
For example a { MASK} list contains details of the mask configuration
and a { BOXES} list holds information on the predicted extent of the
spectra for a particular observing configuration.

The user can toggle between working in LIST and IMAGE mode simply by
typing {\bf LIST} or {\bf IMAGE}. 
The current mode is displayed within the command line prompt.
LISTs and IMAGEs can be read in, using the { READ} command, to
internal {\it slots}. 
There is a {\it stack} of slots for IMAGEs and one for LISTs.
Subsequent processing takes place on these slots, and when they
require saving they can be written back to disk files with the 
{WRITE} command.

There are a  number of LEXT commands which simply deal with the
bureaucracy of the stack system. 
For example { DIRECTORY} shows the currently used slots in the
stack, { NEXT}, { BACK} and { USE} allow the user to move the
current slot pointer.
The relevance of this is that many other commands work, by default, on
the current slot.
However, many commands will search the stack for LISTs of the right
type and warn you if there is more than one list of the correct type
present.
%The biggest problem that inexperienced users are likely to have is in
%adapting to the stack system and making sure that they are `pointing'
%at the right slot for the particular operation.

Many of the simple commands (see the on-line HELP for full details)
can be used on both LISTs and IMAGEs but with different results. 
For example, in LIST mode, typing:
\begin{quote} 
LEXT -- LIST 3 $>$ { \bf READ ALIST}\\
LEXT -- LIST 4 $>$ { \bf ADDC}
\end{quote}
will first read in a list called ALIST and will then prompt the user
for a constant to add to a given column of the LIST (which is also
prompted for) in the current slot.
Note that, in this example, we start by pointing at LIST 3.
The slot pointer is changed to 4 as ALIST is read into the next
available slot which happens to be 4.
The old data values will be over-written.
In IMAGE mode, typing:
\begin{quote}
LEXT -- IMAGE 2 $>$ {\bf ADDC 6.3}
\end{quote}
will add 6.3 to all the data values in the current IMAGE held in slot 2.
Notice that here we have specified the parameter on the command line,
which is an alternative to allowing the program to prompt.

There are also a selection of more sophisticated commands to perform
LDSS-2 specific tasks.
Many of these require standard information, such as the pixel scale,
the dispersion of the grism etc.
This information is stored in a large set of internal parameters,
which are then used as required by each routine.
A list of some of the most important parameters is shown in
Appendix~\ref{app-set}.
To see what the current settings are type: 
\begin{quote}
LEXT -- LIST 2 $>$ {\bf SHOW/ALL}
\end{quote}
This works in both modes, as do all the remaining examples in this section.

Internal parameters may be changed individually using the command 
\begin{quote}
LEXT -- LIST 2 $>$ { \bf SET {\it parameter} {\it value}}
\end{quote}
The currently SET parameters may be output to an external ASCII format
file using the command { SAVESET}. By default the saved file is 
called LEXT.SET, but any name can be specified on the command line. 
Files with can be read back by simply typing their name, e.g. to
set the parameters in MYFILE.SET type: 
\begin{quote}
LEXT -- LIST 2 $>$ {\bf MYFILE.SET}
\end{quote}
These files are examples of LEXT {\it procedures}, which are
basically lists of LEXT commands to be executed one after another 
(see the example file in Appendix~\ref{app-set}). 
In the case of LEXT.SET all these commands are simply to SET internal
parameters. 

There are also several other procedures which have been written to
facilitate the tasks of mask design, field acquisition etc. 
These reside in a directory with logical name LDSS\_PROC and are
invoked by typing the procedure name. 
LEXT searches LDSS\_PROC as well as looking in the current directory
for the specified procedure file. 
Thus both the procedures RUMBA.PROC in LDSS\_PROC and RUMBA.PROC in
the current directory could be invoked by typing: 
\begin{quote}
LEXT -- IMAGE 4 $>$ {\bf RUMBA}
\end{quote}
If both procedures were present, LEXT would preferentially use the one 
in the current directory. 

Several procedures are discussed in the appropriate sections of this
manual, including PREDICT\_SPECTRA, EDIT\_MASK, OPTIMIZE\_MASK and
DRAW\_MASK to help in designing masks, and FIND\_TWEAK to help acquiring
fields with the telescope. 
A list of procedures is shown in Table~\ref{tab-proc}. 
%Some of these create new LEXT.SET files which you may need to save 
%for later use. In general, there will be a separate LEXT.SET file for each 
%possible observing and mask configuration. Refer to the LEXT Reference
%Manual for details of the procedure language. 


\begin{table} 
\label{tab-proc}
\begin{center}
\begin {tabular} {|l|l|} \hline
Procedure     & Action\\ 
\hline
SET\_GRISM & sets parameters for the different grisms \\
COORDS\_MASK 	& Creates a MASK list from LDSS image coordinates \\
PREDICT\_SPECTRA & Calculates the predicted extent of the spectra on
                   the detector  \\ 
                 & and plots the boxes \\
EDIT\_MASK 	& Allows interactive adjustment of slit parameters in
a MASK list \\
OPTIMIZE\_MASK 	& Attempts to maximise the slit lengths for each
                   object \\
DRAW\_MASK       & Draws a plot of slits and holes on a mask\\
PLOT\_SPEC	& Plots the predicted extent of the spectra on the
                   detector \\
ANALYZE\_MATRIX  & Maps the LDSS distortion using an image of
                    the matrix mask\\
ANALYZE\_MASK    & Used to measure the exact positioning of 
                    a target mask \\
FIND\_TWEAK	& Calculates small adjustments to centre the 
                  fiducial stars \\ 
                 & in their holes\\
\hline
\end {tabular}
\end {center}
\caption { Some useful LEXT Procedures} 
\end{table}

\newpage

\subsection{Preparation of mask data}

\label{sec-maskdata} 

The multiaperture mask in the focal plane of LDSS-2 must have an
accurately positioned slit for each target object, and also 3 or more
larger holes to allow accurate alignment of the mask and the target
images.
LEXT has facilities which make it relatively simple to design a mask either
from direct images of the target field or from previously measured
image positions.
Once the design of a mask has been completed, LEXT writes out a file 
which describes the position and size of the slits and fiducial holes. 
Observatory staff can then use the file to manufacture the mask 
with a computer controlled milling machine.

{\bf Note that it is essential to save the catalogue files and
have them accessible to the LEXT package at the telescope so that the
fields can be acquired. }

\subsubsection{Creating the input catalogue}
\label{sec-catalogue}

In order to design masks which will allow the targets to be acquired
accurately, you must provide good astrometric data for each potential
target and for a number of fiducial stars that are required to help
acquire the target field.
Specifically, you must provide:
                                                                         
\begin{itemize}

\item Positions for each potential {\it target object}. 
These should be accurate relative to each other to a small fraction of
the slit width.
If the random positional errors are large then a large fraction of the
useful light from the targets will be lost. 

\item Positions for {\it fiducial stars} which will be used to align
the telescope with the target field. 
These should be accurate relative to the positions of the targets to a
fraction of the slit width.  
At least 3 of these are required, preferably 4 or 5. 
There is an optimum brightness range for the fiducial stars: 
if they are too faint, they will be hard to see in the direct
exposures required for target acquisition; 
if they are too bright, the acquisition algorithm will not be able to
determine their positions securely and they may lead to charge
bleeding during spectroscopic exposures which may obscure the spectra
of the programme objects. 
Stars of between 15 and 17th magnitude in V work well. 
%Although the precise magnitudes are not important, it is best to
%choose a set of stars with closely similar magnitudes so that a single
%acquisition exposure will be able to locate all the stars. 

\item A position for a single, bright fiducial star used for locally
recalibrating the telescope pointing model, the {\it pointing
recalibration star}. 
The star must be bright enough to be easily seen by the telescope
direct TV system, and it's position must be known accurately 
relative to the positions of the targets and other fiducial stars.
This star  should be as close as possible to the target field and,
usually one of the fiducial stars within the field can be used. 


\end{itemize}

The common coordinate system for these objects should be aligned with
the celestial coordinate system to an accuracy of about 0.5$^{\circ}$
otherwise the rotation could be large enough to make the fiducial
stars miss the holes in the mask. 
The {\it absolute} position of the field centre is not important since
the pointing model will be locally reset but it should be good enough
so that the pointing recalibration star can be easily identified with
the direct TV system, i.e. $\leq 10$ arcsec. 

Coordinates derived from CCD exposures and scans of photographs should be
converted carefully to celestial coordinates using astrometric standards
to avoid errors due to incorrect calibration of the pixel scale
or field rotation. 
Coordinates derived from direct images taken with LDSS-2 can be used
directly since the the same coordinate system is used throughout.

All these positions are entered into a {\it catalogue file} with a
name of the form {\it name}.CAT. 
The file must also contain global information about the target field. 
Detailed instructions on the file format and examples are given in 
Appendix~\ref{app-cat}.
The most important global parameters are:
\begin{itemize}
\item Position of the field centre
\item Equinox
\item Epoch
\item Position angle of the slits
\end{itemize}
The entry for each object (both target and fiducial objects) must 
contain: 
\begin{itemize}
\item The ID of the object
\item The celestial position (RA and Dec)
\item A {\it weight} which, if positive, indicates the importance of
the target for subsequent optimization of the mask or is zero for
fiducial stars 
\end{itemize}
A number of other parameters relating to the slit configuration can also
be entered for each object to override the default values derived from
LEXT's internal parameters. 
These slit-related entries may be modified during subsequent
processing by LEXT.

The catalogue file can be read into LEXT using the command
\begin{quote}
{ \bf READ/CAT {\it name}}
\end{quote}
where {\it name} is the first part of the catalogue file name ({\it
name}.CAT). 
The representation of a catalogue file inside LEXT is a { MASK}
list.
Initially this contains the same information as in the catalogue file
with additional default values for slit parameters supplied from the
values of some of the LEXT internal parameters.
These will probably be altered during the mask design phase. 
The command { WRITE/CAT} will output to a disk file the same
information as you input (plus any subsequent changes) with extra
information about the mask configuration.

\subsubsection{Generating relative astrometry from LDSS-2 images}

It is possible to generate the astrometric information from positions
measured on a direct image taken with LDSS-2. 
This is most likely to be of use when you are at the telescope and
wish to improve on astrometry obtained by other means. 
The main complication with data obtained this way is that the optical
distortion in LDSS-2 must be accounted for in transforming from the
detector focal plane to the telescope focal plane. 
This means that the procedure should not be used with image data
obtained with other instrumentation unless the distortion is
recalibrated within LEXT. 

This method is discussed here although  it is unlikely that you will
be in a position to do this before you get to the telescope. The main
steps are as follows. 

\begin{itemize}

\item Take a direct image with LDSS-2 though a filter for which you 
have already worked out the distortion correction from a matrix mask 
exposure (see Section~\ref{sec-reduce-distort}). 
You will need to record the position of the field centre and the
position angle used for the original direct image since this
information will be used for re-acquiring the field for spectroscopy.

%\item Measure the positions of the target objects in the LDSS image. 
%The LEXT command MAP finds lists of peaks in an image, and CURSOR/GFIT 
%can then be used to fit Gaussian profiles to the peaks and so provide 
%accurate positions. 

\item Use LEXT procedure COORDS\_TO\_MASK to generate a MASK list. 
COORDS\_TO\_MASK can take input either as a list of coordinates
produced by a previous { WRITE} command or an LDSS-2 direct image.
If an image is used as input, the coordinates are derived
interactively in the procedure using LEXT's graphical
editing/selection capability.  
The relevant distortion correction data derived from matrix mask
observations must be available (see Section~\ref{sec-reduce-distort}).
The output is a MASK list containing the relative positions of
the targets. 
Optionally a field centre in celestial coordinates may be provided. 
If so, the MASK list produced will include the assumed RA and Decs of
the positions in addition to the relative sky coordinates in arcsec. 

\item Generate a catalogue file from the MASK list and edit as appropriate.
This { MASK} list is the internal representation of a {\it catalogue} file. 
You can then either proceed with the mask design 
or output the MASK list to a catalogue file with { WRITE/CAT} for
further processing. 


\end{itemize}

\subsubsection{Designing the masks}

Once you have created an astrometric catalogue file, 
LEXT provides facilities to design and optimize the slit positions and 
sizes for the actual mask. 
The main stages here are:

\begin{enumerate}
\item Set the lext parameters which describe the dispersion and
wavelength range relevant for the grism that you intend to use.
\item Display where the direct images of the targets will fall on the
detector surface to identify obvious overlaps  
\item Edit the MASK list (graphically) to remove supernumary targets
\item Display where the spectra will be on the detector to identify remaining
overlaps 
\item Edit the MASK list again to fine-tune the slit parameters 
\item Optimize the slits to maximize the slit length for each object 

\item Display once more to verify the optimized slit parameters and,
if necessary, edit again to fine-tune the parameters of individual
slits 

\end{enumerate}

Finally, you will need to output a file containing the manufacturing 
instructions as described in the next section. 

This can all be done with standard LEXT functions but it will probably
be easier to use the LEXT procedures SET\_GRISM, PREDICT\_SPECTRA,
EDIT\_MASK, OPTIMIZE\_MASK and DRAW\_MASK as described below. 


\begin{figure}[htbp]
\setlength{\unitlength}{3.1mm}
\begin{center}
\begin{picture}(40,40)(-2,-4)
\thicklines
\put(26,2) {\framebox(8,4){WRITE/MAN}}
\put(26,8) {\framebox(8,4){\shortstack{OPTIMIZE\\\_MASK}}}
\put(26,14){\framebox(8,4){\shortstack{EDIT\\\_MASK}}}
\put(26,20){\framebox(8,4){\shortstack{PREDICT\\\_SPECTRA}}}
\put(26,26){\framebox(8,4){ READ/CAT }} 
\put(26,32){\framebox(8,4){\shortstack{Create input\\catalogue}}}
%
\thinlines
\put(26,34){\vector(-1,0) {3}} 
\put(14,32){\framebox(9,4){\shortstack{{\it Catalogue}\\{\it file (.CAT)}}}}
\put(18.5,32){\line(0,-1) {3}} 
\put(18.5,29){\vector(1,0) {7.5}} 
%
\put(26,26.5){\vector(-1,0) {3}} 
\put(14,23){\framebox(9,4) {\it MASK list}}
\put(23,23.5){\vector(1,0) {3}} 
%
\put(26,20.5){\vector(-1,0){3}} 
\put(14,17){\framebox(9,4){ \shortstack{ {\it Plot and } \\ {\it DRCT list} }}}
\put(23,17.5){\vector(1,0) {3}} 
%
\put(26,14.5){\vector(-1,0){3}} 
\put(14,11){\framebox(9,4){ \shortstack{ {\it New MASK and } 
\\ {\it DRCT lists } }}}
\put(23,11.5){\vector(1,0) {3}} 
\put(14,13){\line(-1,0) {2}} 
\put(12,13){\vector(0,1) {12}} 
%
\put(26,08.5){\vector(-1,0){3}} 
\put(14,5){\framebox(9,4) {\it New MASK list }}
\put(23,5.5){\vector(1,0) {3}} 
\put(14,7){\line(-1,0) {3}} 
\put(11,7){\vector(0,1) {18}} 
%
\put(14,-4) {\framebox(9,4){\shortstack{{\it Manufacture}\\{\it file (.MFR)}}}}
\put(18.5,3){\line(1,0){7.5}}    \put(18.5,3){\vector(0,-1){3}}
%
\put(0,32){\dashbox(9,4){{\it LDSS-2 image}}}
\put(4.5,32){\vector(0,-1){5}}
\put(0,23){\dashbox(9,4){\shortstack{ COORDS\_TO \\ \_MASK }}}
\put(9,25){\vector(1,0){5}}
%
\put(-2,1.5){\dashbox(40,29.5)[bl]{\shortstack{~~LEXT\\~\\~}}}
%
\end{picture}
\end{center}
\caption{Summary of the generation of mask data from an input catalogue (or
optionally from an LDSS-2 image) using LEXT procedures.}
\label{fig-catmask}
\end{figure}

\begin{description}

\item{\bf SET\_GRISM.}  This simply reads a .SET file corresponding to
the relevant grism. 

\item{\bf PREDICT\_SPECTRA.}
This plots the predicted position of the direct images of the targets
and the position of the currently defined slits as they would appear
on the detector. 
Each target is shown as an open circle with the current slit assigned
to it superimposed. 
The fiducial stars are shown as open circles within larger circles
which indicate the size of the fiducial hole. 
Each target is labelled with the ID number from the catalogue file. 
Optionally, the location of the spectra will also be shown but this
can be confusing if you have a lot of supernumary targets at this
stage. 
The user can decide whether to display the whole detector surface or
just the area in which the targets are located. 
The input is either a user-specified catalogue file  (see
Section~\ref{sec-catalogue}) which will be read into a MASK list or an
existing MASK list (which may have been modified already). 
Fig~\ref{fig-predict} shows an example of the output. 
The coordinate system used by LEXT is shown in Fig~\ref{fig-coord}. 
The procedure also produces a new list of type DRCT, which, together 
with the MASK list is updated by the EDIT\_MASK procedure. 

\begin{figure}[htbp]
\vspace{150mm}
\caption{An example of the output from LEXT procedure { 
PREDICT\_SPECTRA} showing the predicted positions of the direct images of 
the target objects and their corresponding slits.}
\label{fig-predict}
\end{figure}

\begin{figure}[htbp]
\setlength{\unitlength}{1mm}
\begin{center}
\begin{picture}(100,80)
\thicklines
\put(0,0){\makebox(10,10)[tr]{\bf (0,0)}}
\put(10,10){\line(1,0){80}}
\put(10,10){\framebox(80,80){~}}
\put(15,15){\makebox(0,0)[bl]{\shortstack{{\bf LEXT}\\{\bf IMAGE}}}}
\put(50,10){\vector(1,0){0}}
\put(50,5){$\boldmath x$}
\put(10,50){\vector(0,1){0}}
\put(5,50){$\boldmath y$}
\put(49.5,20){\framebox(1,60){~}}
\put(47,83){\bf Slit}
\put(50,50){\vector(-1,0){20}}
\put(25,45){\bf Blue}
\put(50,50){\vector(1,0){20}}
\put(65,45){\bf Red}
\put(65,53){\bf Dispersion}
\put(50,50){\vector(-3,1){20}}
\put(56,73){\bf N}
\put(50,50){\vector(1,3){7}}
\put(25,57){\bf E}
\put(55,65){\vector(-4,1){6}}
\put(55,60){\bf PA}
\end{picture}
\end{center}
\caption{The LDSS-2 coordinate system showing the relationship with the sky
when the slit is at a non-zero, positive position angle. This assumes that
the image has been read into LEXT in the correct orientation.}
\label{fig-coord}
\end{figure}

\item{\bf EDIT\_MASK.} This uses the plot created by the procedure {
PREDICT\_SPECTRA} to {\it graphically} edit the MASK list by pointing
to the appropriate direct image of the target with the cursor and
deleting or editing it by pressing the appropriate number on the
keyboard. 
If the target is deleted (press 1),  it is removed from the plot (the
label will remain). 
If the target is to  be edited (press 2), the user is prompted for the
parameters describing the  current slit. These are: 
\begin{itemize}
\item Displacement of slit in Y (pixels): A positive value here will move the
whole slit upwards
\item Length of slit (pixels): Set the value you require
\item X position of object (pixels): you should not normally change this
\item Y position of object (pixels): you should not normally change this
\item Y extent of object (pixels): changing this may affect how the slit is
subsequently optimized
\end{itemize}
In each case, the current value is offered as a default. 
The initial values of the global slit parameters are set internally
(see below). 
After this, the display is updated to indicate the alterations. 
You can edit as many targets and their slits as you like, finishing by
hitting key 4 while the cursor is within the display area. 
This procedure updates both the MASK and DRCT lists so that a subsequent {
PREDICT\_SPECTRA} will show the new configuration. 

\item{\bf OPTIMIZE\_MASK.} This allows the user to optimize the mask
design by increasing the length of the slits up to the point where
there is an overlap with a neighboring slit. 
It is important to realize that this optimization will not extend
beyond the currently displayed region of the detector unless the user
specifies a larger area. 
As well as updating the MASK list, this procedure creates a new list
of type BOXES. 
Note that the fiducial objects must be given weight zero, otherwise 
the position of the holes may be changed by the procedure. 
%(The main LEXT function used in this procedure is GROW). 

\end{description}

These procedures can be repeated in sequence until the optimal
configuration is obtained.  
The whole process is summarized in Fig.~\ref{fig-catmask}. 
It is possible to modify these procedures for your own use; they can
be found in the directory LDSS\_PROC. 
Alternatively, you can use any of the specialized LEXT {\it functions}
for the same purpose: PLOT/DIRECT, PLOT/BOX, GROW, CURSOR/EDIT. 

{\it It would be wise to save intermediate versions of the MASK list using
WRITE/CAT in case anything goes wrong.}

Once the mask design has been finalized, a file containing the 
manufacturing instructions for the observatory's mask manufacturing 
facility can be generated using the command:
\begin{quote}
{\bf WRITE/MAN {\it file}}
\end{quote}
This will produce a file named {\it file}.MFR which can be sent to the
observatory for use in physically making the masks.

The procedure DRAW\_MASK produces a drawing of the mask which (if
reproduced on a suitable high resolution plotter) could be used for 
alternative fabrication methods. 
An example is shown in Fig.~\ref{fig-maskplot}.
This output can be used to double check the target distribution and the 
final mask.

\begin{figure}[htbp]
\vspace{160mm}
\caption{An example of a plot of a mask produced with LEXT procedure { 
DRAW\_MASK}}
\label{fig-maskplot}
\end{figure}

\subsection{How to get the masks made}

There are two methods that have been used to physically make the masks. 
The mask manufacturing facility operated by the observatory; 
and an industrial photoetching technique (masks have been this way for
LDSS-1).

You are {\it strongly} advised to use the observatory facility rather than
alternative methods since:

\begin{itemize}

\item It produces high quality slits 

\item The lead time is much reduced (as little as 30 minutes provided that
the necessary technical staff are available)

\item The positions of slits are reproducible (i.e. two masks made
from the same data should be identical) since the masks are machined
within their cells 

\item The masks are stiff so that they won't sag under when mounted in
the instrument.

\end{itemize}

You should only need to consider alternative methods if the
observatory facility is not available or if you require a very unusual
slit configuration that cannot be provided by the observatory (eg very
narrow slits).
In this case you will be entirely responsible for getting the masks
made at your own expense.


\subsubsection{Observatory mask manufacture facility}

A numerically controled Bridgeport INTERACT-4 milling machine is used to
cut the slits and acquisition holes in a brass disk mounted on a special jig
on the X-Y machine table.
The cutting head consists of a cutting tool held in a chuck on a
rotating spindle which moves in the Z direction.
The slits have a V-shaped profile which avoids defocussing at the slit edge. 
The nominal width is 320$\mu$m which corresponds to about 1.5 arcsec on the
sky.  
In principle, the width of the slits can be varied by altering the depth
at which  the cutting head is set, however there is no guarantee that the
quality of the slit edge would be optimal for these other slit widths.
The slits have rounded ends with radius equal to half the slit width. 
A reproduction of a slit made with INTERACT-4 is shown in Fig~\ref{fig-slit}.
The mask is machined as a unit within its cell so that no positional
uncertainty is introduced by mounting the mask in the cell at a later
stage.

Curved slits can be made by connecting short slits between a number of
user-specified points. 
However, this will not, in general, result in a constant slit width
in the dispersion direction. 
{\it Please note that the interface specification for INTERACT-4 (as used
in the .MFR files) does not have provision for specifying curved slits
so it would be necessary to make special arrangements with the
observatory.}

To get the masks made, check with the observatory for details of when
they want the files and the desired physical format of the data.
They will require the .MFR file produced by LEXT using the {WRITE/MAN}
command.
Since this is in ASCII format, it may be E-mailed to the observatory
or sent by any other means appropriate to the transfer of ASCII data.

The elapsed time to make a mask depends on the availability of trained
staff at the observatory and reference should therefore be made to the
technical staff via your Support Astronomer.
The system has been designed with the aim of producing masks within 30
minutes of generating the .MFR file.

\begin{figure}[htbp]
\vspace{70mm}
\caption{An enlargement of a slit made with INTERACT-4. The width is 320 $\mu$m.}
\label{fig-slit}
\end{figure}

\subsubsection{Alternative methods}

A company which has produced masks for LDSS-1 and LDSS-2 is:

\begin{quote}
Photofabrication (Services) Ltd.\\
Chemical Milling and Graphic Services,\\
14, Cromwell Rd, St Neots, \\
Cambridgeshire PE19 2HP,\\
Telephone: (0480) 75831 Fax: 75801
\end{quote}

(Contact: J. McGarrey).
In the past, they have worked from either high quality plots of the masks
required or from data describing the positions of the slits (and fiducial
holes), fixing holes and the outer diameter of the mask.

In general, they will only be able to supply adequate quality slits in {\it
thin} stainless steel. This means that there is a risk that the mask will sag
when mounted in a cell, especially if the mask contains long slits spanning a
significant fraction of the mask diameter. Since the masks will not be made
as an integral unit with their cells, there will be a positional 
uncertainty in the way in which the masks are fixed into the cells.

\newpage
\section{Control systems}

\subsection{Overview} 

There are several different systems which the observer needs to
know about and operate, as summarized below. 
In general these are the same as for observing with any other
instrument such as ISIS but with the addition of the LEXT software
package running on a separate computer.
More detailed descriptions are presented in the relevant sections, and
there are also separate manuals for the systems not specific to
LDSS-2, 

\begin{description}

\item {\bf Instrument Control System:} This is the control system for
the instruments and related sub-systems. 
It consists of a number of ADAM D-Tasks which handle communications
with the instrument sub-systems and a user interface running ICL which
accepts simple commands.
The observer interacts with the system via a VAXstation which also
runs a multipage MIMIC display to show the status of the telescope
and instrumentation.
The following functions may be controlled:
\begin{itemize}
  \item Instrument control (see Section~\ref{sec-control} for LDSS-2)
  \item Data acquisition and detector configuration. 
  \item Acquisition and Guidance unit (comparison lamps/filters and autoguider
        probe positioning) 
\end{itemize}

\item {\bf Detector Memory System (DMS):} This controls the detector
system and is run from a window on a Sparcstation in the console area. 
It is operated by the observers.
The main functions are:
\begin{itemize}
  \item Monitoring of the CCD 
  \item Inspection of the raw CCD data through interaction with an
        image display 
  \item Hartmann tests for focus/tilt and rotation checks 
        (see Section~\ref{sec-focus})
\end{itemize}

\item {\bf LEXT software:} This runs on a dedicated VAXstation in the
control room. 
The system is operated by the observers and runs in an 
account called {\bf LEXTOBS}. 
See Section~\ref{sec-lext} for further information. 

\item {\bf Telescope Control System (TCS):} This system is used to control
the telescope and associated sub-systems. 
It is run through a VMS-style user interface by the Telescope
Operator.

\item {\bf Acquisition TV system:} This is a Forth-based system controlled
by the Telescope Operator.

\item {\bf Autoguider Control System:}
The CCD autoguider is run by a FORTH based system which is controlled
either by commands from the ICL interface, or through a terminal
interface to the system, usually used by the Telescope Operator.
The operation of the CCD autoguider, and the commands available from
both interfaces, are described in more detail in the ISIS User's
manual.
Control of the Autoguider probe positions is through the ICL interface,

\item {\bf Data Archiving:} 
Data are formatted and saved to disk on the system computer
by the Data Acquisition system. 
Data are recorded on disk in .NDF format, and should be archived to tape
(usually on a Digital Audio Tape), using the procedures FITSINIT and
WRITE\_FITS.

\end{description}

\subsection{ICL and LDSS-2 start-up}
\label{sec-control}

The LDSS-2 control system runs under ICL on the instrument control
computer. 
The commands specifically for LDSS are  summarized in
Table~\ref{tab-commands}, and some other useful commands are shown in
Table~\ref{tab-iclcommands}.
The following steps are necessary to start up the system, and 
you will probably need to do this every day before starting to observe. 
It would be very wise to do this during the afternoon while there are
technical staff around to correct any problems.

\begin{table}
%adapted from PBT's command summary table from WHT-LDSS4
\caption{Summary of LDSS-2 Instrument Control ICL Commands}
\label{tab-commands}
\vspace{5mm}
\begin{tabular}{||l|c|l||}        
\hline
\hline
                &                   &\\
Command         &  Parameter        & Description \\
                &                   &\\
\hline
\multicolumn{3}{||l||}{\it Routine operation}\\               
\hline
{\bf LAPERTURE} & {\it position}    & Move aperture wheel to specified 
{\it position} = 0-7\\
{\bf LFILTER}   & {\it position}    & Move filter wheel to specified 
{\it position} = 0-7 \\
                &                   & \hfill and adjust focus by corresponding offset\\
{\bf LGRISM}    & {\it position}    & Move grism wheel to specified 
{\it position} = 0-5\\
{\bf LFOCUS}    & {\it position}    & Move camera focus to specified 
{\it position} = 0-767\\
{\bf LDOOR}     & {\it state}       & Lock ({\it state = 1}) or unlock 
({\it state} = 0) access doors\\
                &                   &\\
\hline                              
\multicolumn{3}{||l||}{\it Definition of wheel contents}\\               
\hline
{\bf LAPERTURE\_SETUP} &            & Define contents of aperture wheel\\
{\bf LFILTER\_SETUP}   &            & Define contents of filter wheel and focus offsets\\
{\bf LGRISM\_SETUP}    &            & Define contents of grism wheel\\
                &                   &\\
\hline
\multicolumn{3}{||l||}{\it Wheel loading}\\
\hline
{\bf LDSS\_CLAMP}   &{\it wheel}    & Clamp 
{\it  wheel} = aperture/grism/filter\\
{\bf LDSS\_UNCLAMP} &{\it wheel}    & Unclamp
{\it  wheel} = aperture/grism/filter\\
{\bf SEND LDSS OBEY} &              & Initialize 
{\it mech} =  APERTURE\_WHEEL etc. \\
\hfill {\it mech} {\bf GINIT} & {\it mech} & \hfill from unclamped position\\
                &                   &\\
\hline
\multicolumn{3}{||l||}{\it Initialization}\\
\hline
{\bf LAPERTURE\_INIT} &             & Initialise aperture wheel\\
{\bf LFILTER\_INIT}   &             & Initialise filter wheel\\
{\bf LGRISM\_INIT}    &             & Initialise grism wheel\\
{\bf LFOCUS\_INIT}    &             & Initialise focus mechanism\\
                &                  &\\
\hline
\multicolumn{3}{||l||}{\it Startup}\\
\hline
{\bf LDSS\_INIT}      &            & Initialise {\em all} LDSS mechanisms.\\
{\bf LFOCUS\_SETUP} &         & Define focus reference value\\
                &                  &\\
\hline
\multicolumn{3}{||l||}{\it Software setup}\\
\hline
{\bf LDSS\_BEGIN}     &            & Startup LDSS software.\\
{\bf LDSS\_LOAD}      &            & Load LDSS D-task\\
{\bf LDSS\_DEFINE}    &            & Load all LDSS ICL procedures\\
                &                  &\\
\hline
\hline
\end{tabular}
\end{table}

\begin{enumerate}

\item 
First make sure that both the system computer and the VAXstation used
to provide the user interface are running.
Then log on to the VAXstation using the OBSERVER account and start up
ICL by simply typing {\bf ICL}.
This will give you a menu of instrument combinations from which you
choose LDSS. 
During the course of the setup, you will be asked to supply the
reference focus {\it position} with respect to which all focus {\it
offsets} are made (see commands LFILTER etc. below). 
The {\it position} must be given as an integer in the range: 0 -- 767.
If in doubt, set it to the centre of the allowed range, i.e. around 380.
When this has finished you should have the ICL$>$ prompt. 
(If for some reason the TCS was not running when ICL was started up, 
you will have to start up the relevant tasks with the command 
TEL\_LINK\_TO\_TCS.)

\item 
Normally all the LDSS-2 mechanisms are initialized automatically
during the course of the startup 
procedures but you may need to know how to initialize LDSS-2
mechanisms in the event of problems or after loading a wheel. 
There are two ways to initialize LDSS-2 mechanisms depending on
whether the wheels are located in a clamped position or not. 
After normal use they will be in such a position, but if the wheels
have been loaded up recently, it is possible that they will be in an
unclamped position. 
The significance of being in an unclamped position is twofold: (1) the
position is undefined and (2) the wheel might freewheel if the
telescope is not parked at the zenith which could lead to damage to
some wheel-mounted components. 
The two ways of initialization are: 

\begin{itemize}

  \item[(a)] If you are sure that each wheel is in a clamp position, 
  type {\bf LDSS\_INIT}. This will initialize each wheel
  in turn. On the LDSS page of the MIMIC, you should see all mechanisms turn 
  from red to blue to green as each is initialized.

  \item[(b)] If you are {\it not} sure that each wheel is in a clamp
  position, you will need to initialize each wheel separately. Wheels
  which {\it are} in the clamp position may be initialized using {
  LAPERTURE\_INIT}, { LFILTER\_INIT} or {LGRISM\_INIT}. Wheels
  which {\it are not} in the clamp position {\it must} be initialized
  with:  
  \begin{quote}
     {\bf SEND LDSS OBEY {\it mechanism} GINIT}
  \end{quote}
  where {\it mechanism} is one of APERTURE\_WHEEL, FILTER\_WHEEL or 
  GRISM\_WHEEL. 
You must make sure that the telescope is in the zenith position
otherwise there is a risk of the wheel losing registration. You can
monitor progress by watching the MIMIC display. 

\end{itemize}

\item Define the contents of each wheel using:

\begin{description} 

  \item{LAPERTURE\_SETUP} for the aperture wheel. You will be asked for the
  name of the mask to be associated with each position in the wheel.

  \item{LFILTER\_SETUP} for the filter wheel. You will be asked to
  supply the filter name and the focus {\it offset} from the reference 
  position, i.e. if you specify a focus offset of 0, the focus used
  will be the same as the reference value specified in LDSS\_BEGIN or
  LFOCUS\_SETUP {\it unless} you alter the focus independently using
  {\bf LFOCUS {\it position}}. 

  \item{LGRISM\_SETUP} for the grism wheel. You will be asked for the
  name of the grism to be associated with each position in the wheel.

\end{description}

\end{enumerate}


Once initialized, each {\it wheel} may be moved to a new position 
using  the commands {\bf LAPERTURE {\it position}},  {\bf
LFILTER {\it position}} or {\bf LGRISM {\it position}}, where  {\it
position} is the position desired as given on the MIMIC. 
In principle, the {\it name} of the position as listed in the relevant
{\bf ...\_SETUP} commands may be used, e.g. {\bf LAPERTURE
4C3729A\_L1} but caution needs to be exercised since if the {\it name}
is the same as a parameter name defined internally by ICL an error may
result. 
It is safest to use the position number.

The camera {\it focus} may be changed using {\bf LFOCUS {\it
position}} where {\it position} is an integer in the range 0 -- 767
which gives the desired focus. 
In normal use, the focus will be changed automatically using the focus
{\it offsets} stored by { LFILTER\_SETUP} and the fiducial focus
set with {LDSS\_BEGIN} and/or {LFOCUS\_SETUP}. 

The doors are controlled with {\bf LDOOR {\it state}} where {\it state} is 
either {\bf 1} for {\it locked} or {\bf 0} for {\it unlocked}.

In each case the selected mechanism is indicated on the MIMIC by highlighting
the selected position or displaying the chosen value.

\subsection{Data acquisition } 
\label{sec-data}

The detector and data acquisition are controlled via ICL from the same
VAXstation that controls the instrument. 
The most common commands are listed in Table~\ref{tab-iclcommands}. 

Data are formatted and saved to disk on the Vax 4000 system computer
by the Data Acquisition System, which is described in detail in ``The
Data Acquisition System'', by G.T. Rixon and S.W. Unger.
In ICL, normal integrations are started using the command RUN. 
On completion a RUN will read the data into the DMS, and then
automatically copy it to a file in .NDF format on the VAX in a new
directory for each night of observing, e.g.
DISK\$WHTDATA:[OBSDATA.01-JAN-1992].
These files can be examined from any of the data reduction VAXes.  Of
particular importance when observing with LDSS, they can be read by
LEXT running on LPVS3.

The DMS stores only the most recent readout, whereas a new VAX file is 
created for each run. 
The file names are generated using the automatically updated run
number.  
For test and set-up frames which you don't want to save, it is
possible to use the command GLANCE, which does an integration, 
but writes the data only to the DMS; no VAX file is 
created and the run number remains unchanged.

The data should be archived to tape (usually on a Digital Audio Tape),
using the procedures FITSINIT and WRITE\_FITS.  These procedures can be
run from any Vax in the cluster which is connected to the relevant
peripheral device, but the normal procedure is to use the OBSERVER
account on the data reduction Vax LPVE.
It is the responsibility of the observer and the support astronomer to
produce the FITS format archive tape, or D-tape; the observers copy,
or C-tape, can be produced either in FITS format or using the VMS
BACKUP utility by the observers, or as a direct copy of the D-tape by
operations staff.


Data in any of the DMS buffers can be also be transferred to the
Sparcstation connected to the DMS, but this is not done automatically.
The Sparcstation is useful for some set-up procedures where the IRAF
package can be used to inspect the data, so it is worth setting it up
to get data from the DMS.  To do this you must use the mouse on the
Sparcstation to select the DMS buffer being used by LDSS.  The buffer
number being used should be written on the whiteboard in the WHT
control room (note that it may not be called LDSS in the DMS window on
the Sparcstation).  Then, once an integration has been read into the
DMS buffer, the mouse on the Sparcstation can be clicked on the
relevant button to copy the DMS frame into an IRAF file.  There are
several options for naming the IRAF file, including one which takes
the currently active run number.  In this option it is important to
realize that if you get the data from the DMS after you have started
the next run, the IRAF file will have the name corresponding to the
run in progress, not the run that has just completed which corresponds
to the data in
the DMS. 

\begin{table}
\caption{Some useful basic ICL Commands}
\label{tab-iclcommands}
 \vspace{5mm}
\begin{tabular}{||l|c|l||}        
\hline
\hline
                &                   &\\
Command         &  Parameter        & Description \\
                &                   &\\
\hline
\multicolumn{3}{||l||}{\it Data acquisition } \\
\hline
{\bf RUN LDSS } & {\it type } {\it n} & integrate for {\it n} secs, 
store data in DMS and \\ 
 & &  copy it to a file on the VAX. \\ 
 & & The parameter {\it type} specifies the image type which \\
& & can be FLAT, BIAS, ARC, TARGET, DARK \\ 
{\bf GLANCE LDSS } & {\it type } {\it n} & integrate for {\it n} secs 
and store data in DMS \\ 
{\bf KEEP } &  & save the last glance to the VAX, using \\
 & & the next run number \\ 
{\bf ABORT LDSS } & & stop current integration and don't save any data \\ 
{\bf FINISH LDSS } & & stop current integration and save the data \\ 
{\bf WINDOW LDSS } & & change the readout window of the ccd \\ 
{\bf DISABLE\_WINDOWS } & & reset the readout window of the ccd \\ 
\hfill {\bf LDSS } & & \\
                &                   &\\
\hline                              
\multicolumn{3}{||l||}{\it Calibration Lamps and Filters } \\ 
\hline
{\bf AGCOMP } & &  move mirror to view calibration lamps \\ 
{\bf AGMIRROR OUT } &   & move mirror to view the sky  \\
{\bf COMPLAMPS } & {\it lamp} & turn on calibration lamp. The parameter {\it lamp} \\ 
                &     & can be W, CUAR, FEAR, OFF \\
{\bf COMPFILTA } & {\it filter } & put filters in front of calibration
lamps. The parameter  \\
{\bf COMPFILTB } & &  {\it filter} can be either the filter position number 
{\it 1 -6 }, \\ 
&& or the name of a filter (eg {\it GG395}) \\ 
{\bf MAINFILTC } & {\it filter} &  put 9' filters in main beam, ie
both sky \\ 
&& and calibration beams. The parameter \\
{\bf MAINFILTND } & &  {\it filter} can be the position number or the
filter \\ 
&& name (eg {\it ND3.0}) etc. \\
                &                   &\\
\hline
\multicolumn{3}{||l||}{\it Autoguider and Acquisition TV}\\
\hline
{\bf AUTORADIAL } & {\it r}    & position autoguider probe in r \\ 
{\bf AUTOTHETA } & {\it $\theta $ } & position autoguider probe in $\theta$ \\ 
{\bf AUTOFILT } & {\it filter } & put filter in autoguider beam \\ 
{\bf FIELD} & & make the autoguider scan for a star \\ 
{\bf FOLLOW} &  {\it state}  & make the autoguider start ({\it state} = ON) \\
 & & or stop ({\it state} =OFF) following the star\\
&&  (abbrev FON or FOFF)\\ 
{\bf ACQINT} & {\it time} & set the autoguider acquisition time in
millisecs\\ 
{\bf GUIINT} & {\it time}& set the autoguider guiding time in
millisecs.\\ 
                &                   &\\
{\bf TVFOCUS}  & {\it value} & set the acquisition TV focus to {\it
value} \\
{\bf TVFILT } &   {\it filter} & put a filter in front of the TV  \\
{\bf TVSCALE } &   {\it scale} & set the scale at the TV camera to
4.5  \\ 
& & or 12 arcsecs/mm. {\it scale} can be 5 or 12 \\ 
\hline
\hline
\end{tabular}
\end{table}
\subsection{Acquisition and Guidance unit} 

The acquisition and guidance unit contains the autoguider probe and
the comparison lamps for calibration data. 
The calibration lamps, filters and comparison mirror and the
autoguider probe  are controlled by ICL commands in the same way as
the instrument.  
The most commonly used commands are listed in Table~\ref{tab-iclcommands}. 

The autoguider probe must be positioned by commands from ICL, but the
the CCD autoguider itself can be controlled either by commands to the
Autoguider D-task from the ICL interface, or through a terminal
interface to the FORTH based autoguider control system. 
The terminal interface is usually used by the Telescope Operator. 
The operation of the CCD autoguider, and the commands available from
both interfaces, are described in more detail in the ISIS User's
manual. 

The acquisition TV is controlled by a Forth-based system and is
normally run by the Telescope Operator. 


\newpage
\section{Setting up the Instrument} 
\label{sec-before}

This section deals with the the things you need to do after you arrive
at the telescope but before you start observing. 
It details the procedures you need to go through and the systems you
need to interact with to ensure the instrument produces high quality
data. 
Most of these checks will have been carried out by your support 
astronomer. 

\subsection{Checklist}

\begin{itemize}
\item Check that the detector is correctly installed, cooled and functions electrically
\item Install the test masks and initial programme masks in LDSS-2
\item Check that the required filters and Hartmann masks are installed
\item Check that the required grisms are installed
\item Check focus, tilt and rotation by Hartmann tests
\item Take distortion exposures of the matrix mask through each filter
\item Do the positional calibration of masks
\item Take dispersed flatfields through each mask for each grism 
\end{itemize}

\subsection{Detector }

LDSS-2 should work with any standard La Palma detector system. 
For the purposes of this document, it is assumed that the Tektronix
1024 CCD which was used during commissioning will be used. 
Table~\ref{tab-summary} gives the parameters for this CCD.


It is wise to carry out some checks to ensure that the CCD is 
working as expected. 
These can be carried out using the DMS to inspect test images and 
calculate simple statistics. 
The DMS is currently run from a window on the Sparcstation, and there
are also menu options accessed with the mouse attached to the DMS
display. 
Also data in any of the DMS buffers can be transferred to the
Sparcstation (see Section~\ref{sec-data}). 
This allows image inspection using more sophisticated software 
such as IMEXAMINE and other IRAF routines. 

The ICL computer should be used to set up the correct windowing so
that the required part of the CCD is read out. 
Some CCDs also have a fast readout mode which reduces the readout time
at the expense of increased noise. 
Normally you will need the full CCD area and the slow readout mode to
minimize noise, but there are times during certain setup operations
when it is useful to have a small window and/or fast readout so
that the total elapsed time to readout the CCD is reduced. 

The following aspects of the CCD detector need to be checked. 

\begin{itemize}

\item {\bf Noise levels:} Take a bias frame (zero exposure) and do
statistics on the image using the DMS menu functions. The noise level
recorded should be close to the expected readout noise (see
Table~\ref{tab-summary}). 


\item {\bf Uniformity and cosmetics:} A bias frame should not show significant 
structure. Ramps over one dimension of the chip probably indicate the 
presence of dark current. If you see this, first check that the CCD is at 
the correct operational temperature. You can also check for anomalous rows 
or columns and individual pixels. These can also be a symptom of incorrect 
operating temperature since traps are temperature dependent.

\item {\bf Charge transfer efficiency:} The most practical way of checking 
this at this stage is to examine cosmic ray events. By taking cuts 
through them in the X and Y directions (use DMS functions X-CUT, Y-CUT, X-PROF,
Y-PROF), you can see if there is any evidence for trailing or asymmetry in
the charge distribution. If so, this may indicate problems with charge
transfer efficiency but first check several cosmic ray events since some
events are intrinsically asymmetric! A better check would be to examine
unblended lines in a wavelength calibration exposure
(Section~\ref{sec-wavecal}).

\end{itemize}

Throughout the night, be sure to check the temperature of the CCD from time
to time and make sure that the dewar has been filled at the start of the 
night.

\subsection{Aperture masks}
\label{sec-masks}

The aperture masks for the programme should have been manufactured
well before the start of the run, and should be installed during the
afternoon before the first night of observing. 
The focus and matrix masks (see Section~\ref{sec-specialmasks}) are
required for some setup operations.
{\it Loading the aperture wheel is a task for qualified personnel only.} 
However, it is useful to know the general procedure and the observer
may need to perform some of the non-critical items in this sequence

\begin{itemize}
\item Take the telescope to the zenith

\item Unlock the doors using {\bf LDOOR 0}

\item Unclamp the aperture wheel using {\bf LDSS\_UNCLAMP APERTURE}

\item Go out to LDSS-2 with new masks and open the doors

\item Manually release the spring clamp and turn the aperture wheel
by hand to the desired unloading/loading position, letting the clamp
relocate to hold the wheel in the new position

\item Remove the old mask by turning each of the three spring-loaded
clips and lifting out the mask. 
Take care not to touch the underside of the mask, since this could
damage the slit edges. 

\item Place the new mask in the holder so that it seats down flat; the
three locating points on the cell are such that it will fit
properly only in the correct orientation and the right way up. 

\item Make sure that the mask cell is held tightly against the
locating points while you lift and turn the three clips to hold it in
place. 
Check that the cell has been clamped firmly up against the locating
points by trying to slip a piece of paper between the cell and each of
the three pins (this is the most difficult part).

\item Once satisfied that the mask is correctly installed, unclamp the
aperture wheel and move it ready to change the next mask, making sure
to note which mask is in which position 

\item Close the doors and return to control room taking old masks with you

\item Lock the doors using {\bf LDOOR 1}

\item Reinitialize the wheel from an arbitrary position using \newline
{\bf SEND LDSS OBEY APERTURE\_WHEEL GINIT}

\item Use {\bf LAPERTURE\_SETUP} to redefine the contents of the wheel.

\end{itemize}

\subsection{Filters }

The standard filters for use with LDSS are listed in 
Table~\ref{tab-filters}. 
Observers may supply their own filters.  
The specification is that the diameter must be 100mm ($\pm$0.1mm) and
the thickness less than 8mm.
{\it Filters should only be installed by qualified personnel.} 
In the case of user-supplied filters, staff should be notified in
advance to give time for any additional spacers to be manufactured.


\subsection{Grisms}

The choice of grisms is summarized in Table~\ref{tab-grisms}. 
Three of the four may be mounted in the grism wheel at any time. 
Two of the remaining three positions in the wheel are taken by the
left and right Hartmann masks, and the final position is empty. 
{\it Changing a grism is an operation that should only be carried out
by qualified personnel.}

\subsection{Rotation, tilt and focus} 
\label{sec-focus}

The detector should be mounted on LDSS-2 and set to the correct back
focal distance and orientation by technical/support staff. 
The detector position and orientation is determined with the aid of three
micrometer heads which  measure the distance between reference surfaces
attached to LDSS-2 and the detector. 
A fourth micrometer head measures the rotation about the optical axis.
This set of four micrometer readings uniquely defines the
correct position of the detector. 
Thus, once these numbers have been determined, it should be possible
to reposition each detector correctly without having to redetermine
the correct position using optical tests each time it is  interfaced
to LDSS-2. 
However, in practice it is necessary to check that the positioning is
correct every time a detector is interfaced to LDSS-2. 

The optical system and detector must be aligned so that 

\begin{itemize}

  \item the optimum {\it focus} position is within range of the focus 
   adjustment on the camera 

  \item the detector is not {\it rotated} with respect to the slit and 
   dispersion directions (i.e. the columns/rows of the CCD are aligned with 
   the slit/dispersion direction)

  \item the detector is not {\it tilted} with respect to the focal surface
   (i.e. the focus is uniform over the full extent of the detector)

\end{itemize}

To check the alignments, direct images of the focus mask illuminated
by the Tungsten calibration lamp are analysed using routines on the
DMS. 
When satisfied with these adjustments, the best focus must be determined
for both spectroscopic observations and for direct imaging.  
For spectroscopy the focus must be chosen to give the best compromise
over the full spectral range required. 
For photometry the focus should be optimized to give the best images
for a particular filter. 
  
The optimum order to do these tests is as follows:
\begin{enumerate}
\item Set LDSS-2 to use the focus mask with white light illumination
  and the filter that you will use to determine the reference focus
  position 
\item Set the camera focus to the default value (LFOCUS 380).
\item Check the rotation of the detector (single exposure with no 
Hartmann mask selected) 
\item Setup the sampling windows for the DMS Hartmann routines. 
\item Check that the focus is not out of range (Hartmann test)
\item Check the tilt (Hartmann test)
\item Determine the best overall focus for the reference filter (Hartmann test)
\item Determine the best focus for the other filters that you will be using
(Hartmann test)
\end{enumerate}

The following sections deal with the determination of rotation, tilt
and focus in more detail. 

\subsubsection{Rotation}

If the rows and columns of the CCD are not parallel to the dispersion
and slit directions, both the acquisition of the target fields and the
subsequent reduction of the data are complicated.
Therefore the rotation between the detector and the optical system
must be checked, and adjusted if necessary. 

The rotation of the CCD with respect to the focal plane can be checked
by measuring the X position of the ends of the slit on an image of the
focus mask or a long slit with the grism wheel in the clear position.
This should be illuminated with a white light source from the
calibration system (i.e. a Tungsten lamp) with appropriate neutral
density obtained using the ND filters in the comparison system. 
Note that some DMS routines are confused by pixel values $>$32000, so
ensure that the maximum count is less than this.
Typical exposures through a ND5 filter should be roughly 10s in V, and
5s in R. 
The X position of each end of the slit image can be measured with the
DMS routine X-FIND.

The amount of rotation found in a particular exposure depends on 
BOTH the rotation of the detector with respect to the LDSS-2 optical
coordinate frame AND any rotation introduced by incorrect installation
of the mask. 
It has been found that it is possible to reinstall a given mask to an
rms accuracy of 0.014$^\circ$ which, for the Tektronix 1024 CCD, is
equivalent to 0.24 pixels (0.14 arcsec) over the full extent of the
detector.
The {\it maximum acceptable} rotation error is much larger than this,
but it is not difficult to align the CCD such that the slope of the slit
image is less than 0.5 pixels from top to bottom.  
If the slope is greater than this, then the CCD mounting ring should 
be rotated with respect to LDSS.

The CCD mounting ring is fixed to the mounting ring on LDSS by seven
6mm Allen screws which pass through curved slots in the CCD mounting
ring into the spectrograph mounting ring.
{\bf There are two further Allen screws which hold the LDSS mounting
ring to LDSS, these lie on a line through the centre of the mounting
ring, and are recessed more deeply than the seven other screws. These
two screws should not be loosened.}
If the seven screws are loosened the cryostat and mounting ring can be
rotated by a small amount, the limit is set by the length of the slots
in the CCD mounting ring.
There is a micrometer gauge fixed to the CCD mounting ring, which can
be brought against a block which is fixed to the LDSS mounting ring to
give a measure of the relative position angle of the two rings.
The cryostat should be rotated by backing off the micrometer;
loosening the screws; rotating the cryostat manually; tightening at
least three of the screws; then measuring the position angle with the
micrometer. The micrometer gauge should not be used to push the
cryostat around.

A 1 pixel slope from end to end of the slit will require a movement of the
cryostat position angle equivalent to around 0.1mm on the micrometer. The
direction of the shift will depend upon which CCD on-chip amplifier is being 
used, and so will have to be established by trial and error.


\subsubsection{Hartmann tests}

The best method for determining focus is to use Hartmann masks. 
These work by blocking off alternate halves of the pupil. 
If the optics are perfectly focussed onto the detector, the image of a
point source will be the same when either Hartmann mask of a
complementary pair is employed. 
The size of the relative image shift between each Hartmann pair is a
measure of how far away the best focus is. 
A number of routines are available on the DMS to calculate the
Hartmann shifts from pairs of exposures employing alternate Hartmann
masks. 

LDSS-2 is equipped with Hartmann masks located in the filter and
grism wheels (Table~\ref{tab-hartmann}). 
They have the same mounting arrangement as the filters so that they
can be mounted anywhere in the filter wheel or in the round holes in
the grism wheel.

\begin{table}[htbp]
\caption{Hartmann masks}
\label{tab-hartmann}
\begin{center}
\begin{tabular}{||l|l|l||}
\hline
\hline
Name    & Description   & Normal location \\
\hline
HL      & Left 		& grism wheel position 2 (blocked half towards hub)\\
HR      & Right         & grism wheel position 4 (blocked half towards rim)\\
HU      & Up            & filter wheel position 1 (blocked half on door 2 side)\\
HD      & Down          &  filter wheel position 2 (blocked half on door 1 side)\\
\hline
\hline
\end{tabular}
\end{center}
\end{table}

Up/down etc. refers to the half of the aperture which is obscured in the
coordinate system of the detector. Up = positive Y direction, Left =
negative X-direction etc. (+X is the red end, +Y is north on the sky for PA=0).
See Fig.~\ref{fig-coord} for details of the coordinate system.

Although the Hartmann masks may be mounted in any available position within
the filter and/or grism wheel, there is a particular arrangement which is
strongly recommended. HL and HR should be mounted in the grism wheel so 
that they can be used to provide information in the dispersion direction for 
a particular filter. If desired, HU and HD could also be mounted in the filter 
wheel to provide information in the cross-dispersion direction in conjunction 
with a pin-hole mask and grism.

To do Hartmann tests for focus determination in the dispersion direction, 
you will need to use the  {\it focus mask} (Section~\ref{sec-specialmasks})
which consists of three  parallel long slits. 
This should be illuminated with white light from the calibration
system with appropriate neutral density obtained using the ND filters
in the comparison system.  Note that some DMS routines are confused by
pixel values $>$32000, so ensure that the maximum count is less than
this in your focus images.
Typical exposures through a ND5 filter should be roughly 10s in V, and
5s in R. 

The DMS focus routines require sampling regions to be defined within 
each image. 
The regions are set up with the following DMS commands, typed in the
DMS window on the Sparcstation: 
\begin{quote}
25 50 75 VERT 1 SET-LINE\\
FOCUS
\end{quote}
The first command defines three  positions in the Y-direction (i.e.
along the slit) where the direct image of the slits will be sampled. 
On Figure~\ref{fig-hart-layout} these positions are labelled A,B, and
C. 
They should be well spaced to sample the full length of the slits
symmetrically about the fields centre. In the example given these
positions are 25\%, 50\% and 75\% of the extent of the detector in the
Y-direction which suits the length of the slits quite well. 
The second command allows the user to interactively define where the
three slits are in the X-direction. 

Make sure that the exposure in the DMS was taken with
the HL mask in beam, and enter the DMS command FOCUS-LEFT. 
This will determine the centroid of the slits averaging over the
X-direction at the specified Y positions. 
Then put the HR mask in the beam, take another exposure and type
FOCUS-RIGHT in the DMS window. 
This will again determine centroids for the slits and compare to
the HL values to give Hartmann shifts for each of the three
positions on the three slits. 
This gives a total of 9 Hartmann shifts which  sample the on-axis
position and 8 off-axis positions symmetrically disposed  around it.
Fig.~\ref{fig-hart-layout} shows the geometry of the situation, and
Table~\ref{tab-hart-example}(a) shows some typical results for the
case where both the focus and tilt are wrong. 
Experience has shown that the Hartmann shifts have an associated
uncertainty when measured in this way of about $\pm$0.1. 
Note that you must use the FOCUS command before FOCUS-LEFT and
FOCUS-RIGHT for each pair of Hartmann images. 

\begin{figure}[htbp]
\setlength{\unitlength}{0.5mm}
\begin{center}
%\fbox{
\begin{picture}(200,200)(-40,-40)
\thicklines
\put(-40,-40){\framebox(200,200){~}}
\put(0,0){\makebox(0,0){\Huge{$\circ$}}}
\put(60,0){\makebox(0,0){\Huge{$\circ$}}}
\put(120,0){\makebox(0,0){\Huge{$\circ$}}}
\put(0,60){\makebox(0,0){\Huge{$\circ$}}}
\put(60,60){\makebox(0,0){\Huge{$\circ$}}}
\put(120,60){\makebox(0,0){\Huge{$\circ$}}}
\put(0,120){\makebox(0,0){\Huge{$\circ$}}}
\put(60,120){\makebox(0,0){\Huge{$\circ$}}}
\put(120,120){\makebox(0,0){\Huge{$\circ$}}}
\put(0,-10){\line(0,1){140}}
\put(60,-10){\line(0,1){140}}
\put(120,-10){\line(0,1){140}}
\put(0,-20){\makebox(0,0)[b]{1}}
\put(60,-20){\makebox(0,0)[b]{2}}
\put(120,-20){\makebox(0,0)[b]{3}}
\put(-10,-2){\dashbox(140,4)[l]{~}}
\put(-10,58){\dashbox(140,4)[l]{~}}
\put(-10,118){\dashbox(140,4)[l]{~}}
\put(-15,-2){\makebox(0,0)[b]{A}}
\put(-15,58){\makebox(0,0)[b]{B}}
\put(-15,118){\makebox(0,0)[b]{C}}
\put(0,-40){\vector(1,0){0}}
\put(0,-35){$ \boldmath x$}
\put(-40,0){\vector(0,1){0}}
\put(-35,0){$ \boldmath y$}
\end{picture}
%}
\end{center}
\caption{Schematic diagram of an image showing the the slits in the focus mask
(1-3) and the sampling windows chosen for the Hartmann tests (A-C). The
resultant Hartmann shifts indicate the focus value at the 9 points marked by 
circles.}
\label{fig-hart-layout}
\end{figure}

\subsubsection{Tilt}

If the detector surface is tilted with respect to the focal surface of
the camera, images will not be in focus over the full field of view. 
The tilt of the detector can be changed by adjusting three capstans
labelled A, B and C on the dewar. 
To check for tilt you need to carry out a Hartmann test with the HL
and HR Hartmann masks using the DMS routines FOCUS-LEFT and
FOCUS-RIGHT after the appropriate exposure. 
Make sure you run FOCUS first. 
The slight curvature of the camera focal plane will mean that there
will be a small difference in focus between the centre of the field
and the outer positions. 
However the pattern of Hartmann shifts should be symmetrical about the
on-axis position. 
It will not be exact because the detector may not be precisely centred
on the optical axis. 

Some typical results for the case where both the focus and tilt are
wrong are shown in Table~\ref{tab-hart-example}(a). 
Table~\ref{tab-hart-example}(b) shows the situation after correction
for both focus and tilt. 
You should aim to achieve similar figures after correcting for tilt
although a constant will be added to the values shown if you have not
yet corrected the focus. 

\begin{table}[htbp]
\caption{Examples of Hartmann shifts (a) when out of focus and with uncorrected
tilt and (b) when in focus with tilt corrected}
\label{tab-hart-example}
\begin{center}
\begin{tabular}{||l|ccc||}
\hline
\hline
\multicolumn{4}{||c||}{(a) Uncorrected}\\
\hline
        & Left  & Centre& Right \\
\hline  
Top     & -1.69 & -1.97 & -2.07 \\
Centre  & -1.70 & -1.96 & -1.94 \\
Bottom  & -1.33 & -1.47 & -1.56 \\
\hline
\hline
\end{tabular}
\hspace{10mm}
\begin{tabular}{||l|ccc||}
\hline
\hline
\multicolumn{4}{||c||}{(b) Corrected}\\
\hline
        & Left  & Centre& Right \\
\hline  
Top     & 0.03  & 0.00  & 0.08 \\
Centre  & -0.11 & -0.17 & 0.01  \\
Bottom  & 0.02  & 0.10  & 0.14  \\
\hline
\hline
\end{tabular}
\end{center}
\end{table}


\begin{table}[htbp]
\caption{ Example of Hartmann shifts with tilt, and orientation of
capstans under CCD. } 
\label{tab-hart-example2}
\begin{center}
\begin{tabular}{||l|ccc||}
\hline
\hline
\multicolumn{4}{||c||}{ }\\ 
\hline
        & Left  & Centre& Right \\
\hline  
Top     & 0.28 &  0.08 & -0.3 \\
Centre  & 0.10 & -0.30 & -0.5 \\
Bottom  & 0.20 & -0.20 & -0.3 \\
\hline
\hline
\end{tabular}
\hspace{10mm}
\begin{tabular}{||ccc||}
\hline
\hline
\multicolumn{3}{||c||}{ }\\ 
 A & & C \\
 \phantom{123} & \phantom{123} & \phantom{123} \\
 & & \\
 & B & \\
\hline
\hline
\end{tabular}
\end{center}
\end{table}

% --- see Table~\ref{tab-hart-info}.
%If the Hartmann shifts are as shown in Table~\ref{tab-hart-example2}
%then the capstan screws on the CCD must be adjusted, turning screw A 
%half a turn clockwise, and screw C half a turn anticlockwise. 

The amount by which you need to move the capstans is indicated by an
empirical relationship between Hartmann shift and the physical
displacement of the camera.
As an example consider the values in Table~\ref{tab-hart-example2}.
These show a differential shift from left to right of 0.5 pixel, in the
sense that the right hand values are negative.
Assuming the exposures taken with the grism wheel in position LH were
analysed with FOCUS-LEFT, and those taken with the grism wheel in
position LR by FOCUS-RIGHT; then this shift can be corrected by
rotating capstan A 0.5 turn clockwise, and capstan C 0.5 turn
anticlockwise.
To correct a differential shift of 0.5 pixels from top to bottom, in
the sense that the lower values are positive, requires that capstan B
is rotated 0.6 turn anticlockwise, and A and C each 0.3 turn clockwise. 
To lower the correct LFOCUS position by 300 units requires that all
three capstans are rotated 0.5 turns clockwise.


\begin{table}[htbp]
\caption{Information on focus and tilt correction}
\label{tab-hart-info}
\begin{center}
\begin{tabular}{||l|l||}
\hline
\hline
Pitch of capstan screws on detector interface           & 640$\mu$m/turn      \\
Micrometer readings {\it decrease} as detector is {\it lowered} & \\
&\\
Relationship between Hartmann shift and camera position & 0.93 shift/100$\mu$m\\
To correct a {\it positive} Hartmann shift, {\it lower} camera &\\
&\\
Relationship between LFOCUS units and camera position   & 1.0 units/$\mu$m    \\
To {\it raise} camera, {\it increase} LFOCUS value      &\\
&\\
Relationship between LFOCUS units and Hartmann shift    & 108 units/1.0 shift \\
To correct a {\it positive} Hartmann shift, {\it decrease} LFOCUS &\\
&\\
Target LFOCUS for reference filter                      & 380 \\
%Approximate ratio of capstan separation & \\
%to the left-right separation of Hartmann positions & 12 \\
\hline
\hline
\end{tabular}
\end{center}
\end{table}

\subsubsection{Focus}

The optimum focus is a function of wavelength since LDSS-2 has a
dioptric optical system in which the lenses introduce longitudinal 
chromatic abberation that cannot be perfectly corrected.
Also the camera focal surface is not quite planar and there is some
chromatic distortion which increases with off-axis angle, so there will
be some slight degradation of focus as you go off axis. 
It is therefore necessary to determine the best focus for
each filter that you wish to use. 
This will give you the best focus for direct imaging in the
appropriate band and will also indicate the focus value to choose in
spectroscopic mode.
For example, if you want your spectra to have the best (spatial) focus
at 6000\AA, you would be wise to choose the focus appropriate for the
V filter which has a central wavelength around 5600\AA.
For this reason, it would be wise to determine the optimum focus for
the B, V and R broad band filters even if you do not plan to use all
of these for direct imaging.

If LDSS is focussed for best imaging at V, then the image spread
at B due to longitudinal colour terms is 125$\mu$m, and at R it is 30$\mu$m.
The spatial resolution of the instrument when used in spectroscopic
mode over a wide wavelength range is severely wavelength dependent.

The camera focus is adjusted using the command LFOCUS on the
instrument control system.
A Hartmann test with a given filter selected, should produce Hartmann
shifts close to zero, but these numbers will never all be zero
because of the residual curvature of the camera focal surface.
The observer has to choose
whether to optimize the focus for the on-axis position or for the whole field.
An example of satisfactory Hartmann shifts is given in
Table~\ref{tab-hart-example}(b). 
Each shift has an associated uncertainty of about $\pm 0.1$.

The relationship between Hartmann shift and the units used by LFOCUS is shown
in Table~\ref{tab-hart-info}. Thus a Hartmann shift of +1.5 can be corrected by
{\it reducing} the focus by about 160 units. 

Examples of focus values obtained for the broad band filters are shown in
Table~\ref{tab-hart-filter}. The offsets can be loaded into the instrument
control system using the LFILTER\_SETUP command so that they will be
automatically applied when the appropriate filter is selected using the command
{\bf LFILTER {\it filter}}.

\begin{table}[htbp]
\caption{Typical LFOCUS values for broad band filters}
\label{tab-hart-filter}
\begin{center}
\begin{tabular}{||lcc||}
\hline
\hline
Filter  & LFOCUS value  & offset from PV        \\      
\hline
PB      & 135 (110)          & -250  (-255)      \\
PV      & 385 (365)          & ~~~0              \\
PR      & 355 (305)          & ~-30  (-60)       \\
\hline
\hline
\end{tabular}
\end{center}
\end{table}

From all these data, it can be seen that if Hartmann shifts are more
positive than +1.2 units or more negative than -3.5 units when LFOCUS
is set at 380 for the V filter, then there is a risk that the optimum
focus will be out of range of the camera focus drive for some
passbands.  

\subsection{The optical centre of LDSS } 

For easy target acquisition it is important to determine the optical
centre of LDSS-2 in the LEXT coordinate system. 
By convention this is taken as the position of the centre hole in the
matrix mask (Section~\ref{sec-specialmasks}).
To determine this position, take a direct exposure through the mask
with a calibration light source and then use the CURSOR/GFIT command
in LEXT.  
Though it is possible to use the DMS or Sparcstation to
determine the LDSS-2 centre, it is then necessary to convert this to
the coordinates as measured by LEXT --- they are not the same and will
depend on the options used with the LEXT {\it READ} command. 

\subsection{Distortion } 
\label{sec-distort}

The optical system produces small radial distortions amounting to
approximately 2\% of the radius at the field edge. 
This is important if you want to derive coordinates for mask
manufacture since these must refer to the focal plane of the telescope
which, to first order, is undistorted. 

The distortion map is obtained using the {\it matrix mask} (see
Section~\ref{sec-specialmasks}) which contains small holes spaced on a
regular square grid.  
The mask should be observed without a grism with white light from the
calibration system (plus neutral density filters to avoid saturation
of the CCD). 
It is important that this should be done with a broad-band filter so
that the image of each hole is not blurred by chromatic distortion
effects.  

Exposures should be taken through each broad-band filter (or custom
filter) that you intend to use so that the chromatic component can be
accounted for although this may be small enough for you to
ignore.

The exposures should be analyzed using the LEXT
procedure ANALYZE\_MATRIX which does the following: 

\begin{itemize}

\item Reads the user-specified matrix mask image which would normally
be the raw data from the directory DISK\$WHTDATA:[OBSDATA.{\it~date}] 

\item Reads a user-specified file containing the positions in mm of the 
holes in the matrix mask. For the matrix mask in use in 1992, this file
is {\bf MATRIX\_MM} (.DST or .SDF) in the directory {\bf LDSS\_PROC}.

\item Predicts the location in the image plane of the matrix mask
holes and calculates the hole centroids in the actual image. 
A comparison of the two is displayed as vectors joining the predicted
and actual positions (multiplied by a large factor for clarity).
%An example is shown in Fig.~\ref{fig-matrix-vectors}. 
At this stage, bad vectors can be edited out graphically.

%\begin{figure}
%\vspace{160mm}
%\caption{An example of optical distortion vectors derived from a matrix
%mask image using procedure {\bf ANALYZE\_MASK}. The vectors are
%multiplied by a large number for clarity.}
%\label{fig-matrix-vectors}
%\end{figure}

\item New values are calculated for: the position of the matrix mask
centre in pixels; the rotation of the mask (clockwise) with respect to
the detector in degrees; and the focal reduction factor between the 
telescope focal plane and the detector focal plane (approximately
11/2).
You can then choose to use these values of the global parameters in
preference to the original values and optionally store them in a new
.SET file for subsequent use.

\item A bicubic spline is fitted to the distortion data and stored in 
files FTRANS and BTRANS {\it or} in file names set earlier using the
commands {\bf SET FTRANS {\it ftrans\_file}} and {\bf SET BTRANS {\it
btrans\_file}}. These files contain the FORWARD and BACKWARD
transformations respectively.

\end{itemize}

If the matrix image is too far from the nominal position, the
automatic centroiding may fail. 
The simplest remedy is to manually set the parameters X\_CENTRE and
Y\_CENTRE to approximately the correct values.  
Then re-run ANALYZE\_MATRIX. 

The new global parameters, and BTRANS and FTRANS files are required to
generate mask data from direct LDSS-2 images using the LEXT procedure
COORDS\_TO\_MASK.

\subsection{Positional calibration of masks}
\label{sec-poscal}

Mounting the aperture masks is not a straightforward operation and it
is possible for a mask to be installed so that the centre of the mask
is shifted with respect to the centre defined by the matrix mask.
If the masks are not made with the milling machine at the telescope,
it is probable that the centre of the mask will be a considerable
distance away from the correct position.

It is therefore desirable (essential in the case of masks not made by the 
on-site facility) to calibrate the positions of the masks. 
This can be done by taking a direct exposure through the appropriate
mask with white light from the calibration system, using the same
filter as for the master distortion exposure that you wish to relate
everything to.

The LEXT procedure {\bf ANALYZE\_MASK} will calculate the relationship
between the mask positions in the exposure and the predicted position
from the catalogue file.
This information will be stored in a new .SET file which can be
used subsequently for all target acquisition operations with this
mask.


\newpage
\section{Observing procedure}
\label{sec-observe}

By now you should have set everything up and be ready to go. This is how you
carry out the observations.

\subsection{At the start of the night}

Before you acquire the first of your targets, you need to do the
following.

\begin{itemize}

\item {\bf General system setup}

Before dinner, ensure the DMS, CCD system, autoguider and system computer 
are running properly (see Section~\ref{sec-control}). 

\item {\bf Setup the CCD readout mode}

The CCD should be set up with the correct windowing so that the required
part of the CCD is read out. Some CCDs also have a fast readout mode which
reduces the readout time at the expense of increased noise.
Normally you will need the full CCD area and the slow readout mode to
minimize noise. 

\item {\bf Setup up the Telescope Control System}

Check with your Support Astronomer and Telescope Operator that the
correct version of the TCS software has been loaded. 
The TCS needs to know that the instrument being used is LDSS-2 so that
it sets up the correct coordinate transformation matrices internally -
in particular it needs to know the offset between the zero points of
the LDSS-2 and telescope rotation systems, i.e. which telescope
rotator position puts the LDSS-2 slit direction at PA=0. 
Normally this would be done by a command such as INSTRUMENT LDSS.

\item {\bf Determine the telescope rotator centre}

As part of the normal startup duties, the Telescope Operator will
determine the rotator centre of the telescope. This is the projection of
the centre of rotation of the Cassegrain rotator on the sky. 
To determine this, a bright star is selected and the rotator moved
through 180$^\circ$. 
The rotator centre is at the middle of the line joining the before and
after positions of the star on the direct TV. 
The Telescope Operator will write in the log the position
of this centre in terms of the {\it TV coordinate system}. It is vital to
realize that {\it this coordinate system is changed if the reverse scan
switches on the TV system are altered} to make the TV image invert
left-right or up-down so make sure that the same switch settings on
the TV system are used throughout. 

This is an important step since the field of view of the telescope, by default,
will rotate around the rotator centre. If the rotator centre is incorrect, 
stars will appear to gyrate in position with the sidereal period when the 
rotator is tracking the sky. 

\item {\bf Refine the telescope pointing model}

Another standard startup procedure for the Telescope Operator is to
determine an update for the global telescope pointing model by a
sequence of observations of positional reference stars. 
This is initiated with the TCS command CALIBRATE. 
An alternative option is to use a previous pointing model
(CALIBRATE/LAST) but this is not recommended, especially for the first
night that LDSS-2 has been put on the telescope.  
In general, it is always best to go through the positional calibration
sequence in case something has changed from the previous night. 
The more time you spend now to get the telescope pointing right, the
less problems you will have later on acquiring your fields. 
The Telescope Operator will examine the residual
pointing errors. They should be within accepted bounds. 

Now check that this all works correctly by acquiring a positional reference
star to make sure it comes in close to the rotator centre.

\item {\bf Focus the telescope onto LDSS-2}

The telescope must be focussed onto the plane of the mask which is
coincident with the input focal surface of LDSS-2.
You will already have setup, or checked the best {\it internal} 
focus for LDSS-2 using Hartmann tests (Section~\ref{sec-focus}). 
Make sure that the {\it reference} filter which you used to setup
the reference focus value is selected and check that the correct focus
value is in operation ({\bf LFILTER {\it filter}} should be all you
need to do).

Then set the focus to the approximate value using records of previous
satisfactory values.
The Telescope Operator should be able to find these in the log.
The telescope should be pointing at a field
with stars of about 14th magnitude (with the field of view of LDSS
a random patch of sky will do). 

The telescope can then be focussed onto the detector using the ICL
procedure FOCUSIMAGE. 
At the ICL interface type:-

FOCUSIMAGE

The procedure will ask a number of questions, then do a number of short
exposures, stepping the telescope and the telescope focus between each,
and finally read out the CCD frame. 
The star images can then be analysed for
the smallest image, and thus the best focus position, using any of the
following options: the X-FIND and Y-FIND procedures on the DMS; 
imexamine in IRAF on the Sparcstation; or LEXT on the Vaxstation. 
As a guide to the parameter values: the initial focus
should be set to about 0.3 mm below the estimated focus for this
instrument; the focus step should be about 0.1mm; and the telescope step 
around 20 arcseconds. The procedure inserts a double length telescope
step between the first and second focus positions.

At this stage it would be a good idea to adjust the direct TV focus to
give the sharpest images for this telescope focus value so that you can
assess the seeing and/or focus easily by examining the images on the direct
TV system. 
The TV focus is changed from the ICL VAXstation using the command
TVFOCUS. 

\item {\bf Determine the LDSS-2 centre}

It is necessary to relate the LDSS-2 centre as measured from the matrix
mask to the position of the rotator centre. 
So far the Telescope Operator has determined the rotator centre with
respect to the TV coordinate system and it is necessary to relate this
to the LDSS-2 coordinate system. 
This is accomplished by putting a brightish star on the rotator centre
as accurately as possible. 
Then take a short direct image with no mask 
and measure the centroid of the star, preferably using CURSOR/GFIT in
LEXT. 
The position of the star gives you the position of the telescope
rotator centre. 

\item {\bf Setup the acquisition reference position}

The acquisition reference position is the point on the TV system display 
that the Telescope Operator uses for acquiring a target. After acquiring
the target blindly (using GOCAT etc..), the Telescope Operator will use the
handset to position the target onto the acquisition reference point. 

The acquisition reference position should be the centre of field rotation.
Ideally it should correspond to the LDSS centre (as determined above)
rather than the physical rotator centre determined initially. The amount
of mismatch that can be tolerated is determined by the size of the
reference star holes in the mask. If the offset is much less than the hole
size (default 10 arcsec diameter), say 2 arcsec, you can use the rotator
centre as the acquisition reference position. 

If the offset is larger than this, it is probably worthwhile asking 
the Telescope Operator to set an APERTURE OFFSET on the TCS. 
This will set the telescope to point at the correct LDSS centre, and
more importantly, if the position angle is changed, the field will
rotate about the aperture centre rather than the real (physical)
rotator centre.
The TCS command used is 
\begin{quote}

ENTER APERTURE 0 $\Delta x$ $\Delta y$

\end{quote}

where ($\Delta x$,$\Delta y$) is the offset {\it in TV system
coordinates}.  
To determine how the TV system and LDSS-2 coordinates are related, ask
the Telescope Operator to use the Handset in RA-Dec mode to move the
telescope by the RA and Dec offset calculated from the position of the
rotator centre in the LDSS-2 coordinate system. 
The handset display will then give the equivalent offset in APOFF
coordinates. 
It this which the TCS needs as the last two arguments of the ENTER
APERTURE command.  
It's best to do all this at PA=0 to avoid confusion.

This position defines both the LDSS-2 centre and the acquisition
reference position, and the Telescope Operator should mark it on the
TV system display with a cursor so that there is  a visual reference
mark on which to acquire your targets.

\end{itemize}

\subsection{Direct imaging}

The procedure for direct imaging observations is the same as for ordinary 
imaging instruments.

\begin{itemize}
\item Select the position angle required on the telescope rotator
\item Acquire your target on the acquisition reference position using the 
direct view TV.
\item Find a guide star and start autoguiding
\item Select the required filter
\item Expose
\end{itemize}

\subsection{Target acquisition with a multiaperture mask}
\label{sec-acquire-multislit}

Acquisition of the target fields, although harder than for longslit 
spectrographs with slit-viewing optics, is quite straightforward and
usually reliable. 
The LEXT procedure FIND\_TWEAK is essential for the acquisition, and 
requires copies of the catalogue files used to produce the masks. 
The special case of acquisition with a longslit (without
fiducial holes) is dealt with in Section~\ref{sec-acquire-longslit}.

\subsubsection{Standard technique}

The standard procedure is summarized in Fig.~\ref{fig-acquire}.

\begin{figure}
\begin{center}
\setlength{\unitlength}{5mm}
\begin{picture}(16,44)(-4,0)
\thicklines
\put(0,4){\framebox(8,2){\shortstack{Spectroscopic\\exposure}}}
\put(4,8){\vector(0,-1){2}}
\put(0,8){\framebox(8,2){\shortstack{Another mask image\\to check}}}
\put(4,12){\vector(0,-1){2}}
\put(0,12){\framebox(8,2){\shortstack{Apply telescope\\offset}}}
\put(4,16){\vector(0,-1){2}}
\put(0,16){\framebox(8,2){\shortstack{Determine telescope\\offset}}}
\put(4,20){\vector(0,-1){2}}
\put(0,20){\framebox(8,2){\shortstack{Direct exposure\\through mask}}}
\put(4,24){\vector(0,-1){2}}
\put(0,24){\framebox(8,2){Start autoguiding}}
\put(4,28){\vector(0,-1){2}}
\put(0,28){\framebox(8,2){\shortstack{Acquire guide star\\with autoguider}}}
\put(4,32){\vector(0,-1){2}}
\put(0,32){\framebox(8,2){\shortstack{Blind offset to\\target field}}}
\put(4,36){\vector(0,-1){2}}
\put(0,36){\framebox(8,2){\shortstack{Acquire pointing\\recalibrator}}}
\put(4,40){\vector(0,-1){2}}
\put(0,40){\framebox(8,2){Select position angle}}

\put(4,27){\line(-1,0){8}}  \put(0,27){\vector(-1,0){0}}
\put(-4,27){\line(0,1){12}} \put(-4,33){\vector(0,1){0}}
\put(-4,39){\vector(1,0){8}}

\put(4,4){\line(0,-1){1}}
\put(4,3){\line(1,0){8}}    \put(8,3){\vector(1,0){0}}
\put(12,3){\line(0,1){16}}  \put(12,11){\vector(0,1){0}}
\put(12,19){\vector(-1,0){8}}

\put(4,11){\line(-1,0){8}}    \put(0,11){\vector(-1,0){0}}
\put(-4,11){\line(0,-1){4}} \put(-4,9){\vector(0,-1){0}}
\put(-4,7){\vector(1,0){8}}

\end{picture}
\end{center}
\caption{Standard target acquisition procedure}
\label{fig-acquire}
\end{figure}

\begin{enumerate}

\item {\bf Select the required position angle}

The first thing to do is to select the position angle that you require
which should obviously be the same as you specified when designing the
mask. The Telescope Operator will use the TCS command ROT/SKY to set
this up. If the TCS has been setup correctly for LDSS-2, it will put the
telescope rotator at the angle which puts the LDSS-2 {\it slits} at the
position angle requested. 

\item {\bf Local calibration of the pointing model with a fiducial star}

The acquisition procedure requires the telescope to point to an
accuracy that is a small fraction of the size of the reference
star holes in the mask. 
Since there may be an offset between the coordinate system of the
telescope (FK5) and that of the target positions, it is very wise to
{\it locally} refine the pointing model by moving the telescope to a
star near (or in) the target field which has astrometry from the same
solution as your target objects --- the pointing recalibration star
defined in Section~\ref{sec-maskdata}. 
This star should be loaded into the TCS catalogue and acquired 
using GOCAT, and then  moved using the handset onto the acquisition
reference position marked on the TV display. 

\item {\bf Blind offset to the target field}

The TCS command {\bf BLIND\_OFFSET {\it target}} will move the telescope to the
position of {\it target} on the assumption that the position of the
original star is perfectly known. In other words it locally refines the
pointing mode. In all likelihood the telescope will move to {\it target}
with sub-arcsecond accuracy, provided that the local reference star was
very close to the target field. Usually this reference star will be one of 
the reference stars in the target field.

\item {\bf Acquisition of the guide star}

Now that you are on the target, it is time to find a guide star. 
The simplest way is to use the GSS software on LPVS3 which will
provide a list of suitable stars with the required guide 
probe positions. 
Once a star is found, don't start guiding yet but repeat the blind
offset sequence (i.e. GOCAT to your positional reference star, centre
up and do the BLIND\_OFFSET again) to make sure that telescope has not
wandered while you were finding the guide star.
Start guiding immediately you have done the blind offset, and as soon
as you are sure that the autoguider is tracking the star, ask the
Telescope Operator to make the telescope use the autoguider output for
tracking corrections.

\item {\bf Direct exposure through mask}

Now take a direct image of the sky through the mask with no grism  (a
broad band filter is desirable but not essential).
The image should show the reference stars in the appropriate holes in
the masks, in general offset from the centres of the holes.
If no stars can be seen: check the acquisition procedure so far ---
are you still autoguiding? --- is the mask correct?
An image of the target field without the mask will verify the field
identification if in doubt.
Measurements of the positions of the reference stars can be compared
with the location of the holes in the masks to check for errors.

\bigskip 

\item {\bf Determination of the telescope offset required} 

The image can now be analyzed using LEXT procedure FIND\_TWEAK
${\boldmath n}$ where ${\boldmath n}$ is the number of fiducial holes. 
This works out how much the telescope should be moved to place the
fiducial stars bang in the middle of the fiducial holes.
Read the comments as you go along for information about the things
that happen.
The main stages are: 

\begin{itemize}

\item Read in the acquisition image to analyze (if not already read 
in). Note that the correct read option must be used to get the correct 
image orientation. READ/1 worked last time, but it will depend upon
which CCD on-chip amplifier is being used. 
\item Read in the Catalogue file
\item Calculate the geometric centre of the holes. A threshold needs 
to be defined. Usually the defaults are acceptable. 
\item Display the regions surrounding each hole in turn with the
calculated centres marked. You will be prompted for the display thresholds.
Normally the defaults are acceptable although you may need to define levels
sensibly for the first hole. 
\item Calculate the centroid of the fiducial stars.
\item Redisplay each hole with the centroid marked. Again the display 
levels are prompted for but can usually be defaulted.
\item Display the full image area with the vectors joining the hole 
centres and the star centroids shown (multiplied by a large number).
\item Edit these vectors graphically if desired, following the 
instructions given. If one vector is discrepant you may wish to remove 
it otherwise exit from the routine by pressing 4.
\item Output the $x$ shift, $y$ shift and rotation 
($\Delta x$,$\Delta y$,$\Delta \theta$) in units of (arcsec, arcsec, degrees) 
required to move the stars to the centres of the holes. {\it Note these
numbers down.} (Usually they will be less than 5 arcsec in $x$ and $y$ and
0.5$^{\circ}$ 
in rotation.) 
\end{itemize}

\item {\bf Application of the telescope offset}

Give the offsets to the Telescope Operator who should use the TCS command:
\begin{quote}

{\bf TWEAK $\boldmath \Delta x$ $\boldmath \Delta y$ $\boldmath \Delta \theta$}

\end{quote}
to move the telescope {\it while the autoguider is still locked on and 
the telescope continues to receive guiding signals}. 
During the set up procedures the Telescope Operator should have used
the TCS command INSTRUMENT LDSS to enter the correct orientation for
the offsets.
%The values $\boldmath \Delta x$ and $\boldmath \Delta y $ are the
%shifts in arc seconds which will move the images onto the slits.
%At position angle 0 degrees, positive values move the images in
%the positive x and y directions, which means the images move west and
%north, so the telescope moves east and south. 
%The angle offset $\boldmath \Delta \theta$ is the position angle 
%rotation required so that a positive value rotates the images
%clockwise. 

{\bf Important note: At present, the TWEAK has to be broken down into
steps of no more than 0.5 arcsec in $x$ and $y$ and 0.1$^\circ$ in
$\theta$.}
This is because the autoguider may lose lock if the telescope moves by
amounts larger than this.
The procedure is to break down the TWEAK into increments of this size
and apply each one, waiting a few seconds to allow the autoguider to
catch up.
It would be wise to watch the autoguider display carefully to try and
see if it loses lock. 
If it does, you could try (a) reducing the increment size and/or (b)
selecting a brighter guide star.
You should also take care that the guide star is not so near the edge
of the autoguider field that it moves outside the area in which the
autoguider can track it when the TWEAK is applied.
%Ultimately this procedure should be automated.

\bigskip 

\begin{tabbing} 
Example: \= TWEAK 1.3 0.7 0.4 should be applied as follows:\\
\\
\> TWEAK 0.5 0.5 0.1\\
\> TWEAK 0.5 0.2 0.1\\
\> TWEAK 0.3 0.0 0.1\\
\> TWEAK 0.0 0.0 0.1\\
\end{tabbing}

Doing the TWEAK with the autoguider in {\it closed-loop} should ensure that no
positional errors occurs during the offset. If you need to apply a large 
TWEAK that cannot be done in closed-loop (for example, because the guide star 
would move outside the autoguider detector area), you can use TWEAK with the 
autoguider off ({\it open-loop}). However you would then need to take
another direct exposure after restarting autoguiding to check the position
of the targets before doing a smaller closed-loop TWEAK.

\item {\bf Acquisition check}

In general, this procedure will be sufficient to acquire the target field 
to an accuracy of around 0.1 arcsec but it must be checked. After 
performing the TWEAK, take another  direct image through the mask. Before 
analyzing it, it is usually safe to put the grism in and start a spectroscopic
exposure while the second direct exposure is analyzed. If there is a 
residual TWEAK to be done, this can be applied during the spectroscopic 
exposure (in closed-loop). If there is a large error in position, the
exposure can be aborted and the whole procedure repeated. If this happens, 
you should first try and work out what has gone wrong.

\end{enumerate}

From time to time, during a long sequence of spectroscopic observations on
the same field, you may wish to check the acquisition. To do this, simply
take a direct image of the sky through the mask and use FIND\_TWEAK
to check  that the stars are still centred in the holes.
Any fine adjustments can be made during the spectroscopic exposures. 

\subsubsection{Further refinements to acquisition}

If you doubt your astrometry, or the location of the mask is
uncertain, you can use another LEXT procedure  REFINE\_TWEAK to
correlate the target objects found in a direct image of reasonable
depth ($>$ 60s depending on the detector) with an image of the mask
illuminated with white light or sky.
This necessitates taking two extra exposures (a) a white light (or
sky) mask image before the first of the direct images of the mask
against the sky and (b) an image of the sky with no mask after the
initial TWEAK.
The residual TWEAK found using REFINE\_TWEAK can be applied
during the subsequent spectroscopic exposure.
Note that you must first have done a positional calibration of the mask
using ANALYZE\_MASK (Section~\ref{sec-poscal}) to determine the fine
details of the mask mounting before you run REFINE\_TWEAK. 

\subsection{Target acquisition with a longslit}
\label{sec-acquire-longslit}

You need to consult this section only if you are using one of the supplied 
longslit masks (Section~\ref{sec-specialmasks}). If you are using a 
multiaperture mask that contains one (long) slit {\it which also has fiducial 
holes custom-made for the target field}, then you should use the 
multiaperture acquisition procedure in Section~\ref{sec-acquire-multislit}.

The procedure here is as follows:

\begin{itemize}
 
\item[(a)] Follow steps (1)--(4) in the standard multiaperture acquisition
sequence (Section~\ref{sec-acquire-multislit}).

\item[(b)] Take a direct image through the slit with white light (or sky)
illumination (You may have prepared one earlier).

\item[(c)] Take a direct image of the sky with no mask.

\item[(d)] Use LEXT to work out the position of the target(s) and the
position on the longslit where you wish to place the target (for example, 
using LEXT function CURSOR/GFIT. 

\item[(e)] Calculate the distance you need to move the {\it target} to put
it on the slit {\it in arcsec} ($\Delta x$,$\Delta y$) in the LEXT
coordinate frame. For example, if $x$-positions measured on the Tektronix
CCD (in pixels) are 567.4 for the slit and 578.2 for the target, the offset
is $\Delta x = (567.4 - 578.2) \times 0.59 = -6.4$ arcsec. 

\item[(f)] If you also want to adjust the position angle of the 
slit to place it accurately on two or more targets, you need to calculate 
the angle offset $\Delta \theta$ in {\it degrees} which is {\it positive} if you
need to move the line joining the targets {\it clockwise} to align them
with the slit direction. For example, if you want to place the slit on two
targets with positions (571.9,606.9) and (570.7,315.6) , $\Delta \theta = -
(180/\pi) \times (571.9-570.7)/(606.9-315.6) = -0.24^{\circ}$. 

This assumes that the slit is precisely aligned with the columns of the
detector. If it is not for any reason, you will need to include this
misalignment in the angle calculation.
Note that this also assumes that the targets are
roughly symmetrically disposed about the centre of the field. If this is
not the case, a small lateral displacement might be introduced when the
angle is changed. To cure this you would need to solve for $\Delta x$ and
$\Delta \theta$ together rather than independently. 

\item[(g)] Move the telescope using the command
\begin{quote}

{\bf TWEAK $\boldmath \Delta x$ $\boldmath \Delta y$ $\boldmath \Delta \theta$}

\end{quote}
as described in step (7) in the standard multiaperture acquisition sequence
(Section~\ref{sec-acquire-multislit}). 
Note that if you BLIND\_OFFSET from a pointing recalibration star
(step (2) of the standard multiaperture acquisition sequence) the
TWEAK is likely to be small


\item[(h)] Repeat steps (c) and (d) to check that the target field is now 
correct. If not, repeat steps (e) to (g).

\end{itemize}

Complications may arise if the size of the required telescope offset is
large because: 
  \begin{itemize}

  \item the effect of optical distortion will need to be accounted for
  (Section~\ref{sec-distort})
  in which case it will be necessary {\it either} to undistort the
  coordinates of the slit and target (or the images themselves; 
  Section~\ref{sec-reduce-distort}) {\it or} to
  do the offset in two steps so that the last one is a small offset to
  account empirically for the effects of distortion. 

  \item the telescope offset can only be done in open-loop in which
  case the offset should be done in two steps: an initial open-loop TWEAK 
  followed by a small closed-loop TWEAK after the position of the target 
  has been redetermined.

  \end{itemize}
Putting these two effects together, it is probably better to do the offset in 
two steps rather than to attempt to calculate the size of the distortion 
and do it in one.


\subsection{Calibration exposures}

To calibrate your data, you will need to carry out the following types of
exposure. The reduction of the calibration data is covered in 
Section~\ref{sec-reduce}. Distortion mapping exposures have already been 
covered in Section~\ref{sec-distort}.

\subsubsection{Flatfielding}

Flatfielding spectroscopic data is not a straightforward procedure and it is
recommended that observers experiment to find the optimum method that
suits their data best. It should be noted that the optimum method will depend
strongly on the nature of the detector, particularly if the CCD is subject
to fringing.

It is important to distinguish between the different methods by which the
detector is illuminated. For direct images through a filter, each part of the
detector is illuminated with the same (limited) range of wavelength, whereas in
spectroscopic observations, a particular point on the detector is illuminated
by essentially monochromatic radiation whose wavelength depends in a
complicated way on the position of the slit and on the grism used. 

The point of flatfielding is to remove sensitivity variations in the detector
(and/or optics) but these variations are likely to be wavelength dependent. If
the detector is a dye-coated CCD or is thinned, there is the additional
possibility of fringing effects caused by interference within the thin layer of
the dye or depletion region. If such patterning is present, it may also be
dependent on the slit width since increasing broadening the slit will
increase the range of wavelength seen by a given pixel which may wash out
the fringes. For this reason, it is strongly recommended that you take
both types of flatfield described below.

{\bf (a) Direct flatfields}

This is the same procedure as used for normal imaging data. 
Direct images are taken though the desired filters of a uniform source
of illumination from (i) a calibration system which carefully mimics
the telescope optical system, (ii) blank fields at dawn or dusk, when
the signal level in the sky dominates the contribution from point
sources.
Experience suggests that the last method is best. 
If fringing is present, this may not flatfield out because the range
of wavelengths present in the flatfield exposure does not match the
wavelengths seen in real on-sky exposures, which is usually dominated
by a few discrete night-sky emission lines.
A possible solution here is to construct a `true' sky flatfield by
median filtering a stack of your on-target observations to remove
discrete sources.

The images are processed to produce a flatfield by subtracting the
bias level (using the bias strip or a separate bias exposure if it is
believed that the bias frame has structure) and dividing through by
the mean signal level in the exposure to provide a flatfield with mean
signal level of unity.

{\bf (b) Dispersed flatfields}

Here it is important to simulate the conditions under which the
exposure to be flatfielded is taken as closely as possible.
A flatfield should be taken for each mask/filter/grism combination
with a continuum light source. Ideally this should provide high signal
level at all wavelengths of interest but few light sources do this.

It is normal to use the Tungsten lamp (with appropriate neutral
density) in the calibration lamp system. 
It would be a good idea to experiment with the different colour
filters provided in the calibration system to try and equalize the
illumination level at all wavelengths.
Nevertheless, it may be necessary to take two exposures for each
combination, one which avoids saturating the CCD anywhere and gives a
high signal level at the peak of the illumination (in the red) and
another which either overexposes the level where the signal level is
highest so as to produce acceptable signal in the faint areas or one
in which a filter is used to block regions of the spectrum where the
signal is high --- the broadband B filter is well suited for this. The
resultant exposures may be combined in some suitable way for further
processing.

Twilight sky can also be used to obtain flat-field frames. 
These have the advantage that the light path is identical to that of
the actual observations. 
However, it may be difficult to obtain flat-fields for every mask
because the sky rapidly changes in brightness during twilight. 
This means there are only short periods of time when it is possible to
obtain useful twilight flatfields: just after sunset and just before
sunrise. 
Also absorption bands in the atmospheric spectrum make the signal
to noise in the flatfields highly dependent on wavelength. 
Therefore, even if twilight skys are taken, Tungsten flats are also
worth obtaining since they will have a more uniform signal to noise.  

It should be noted that because of flexure of the instrument during
the course of a long exposure, dispersed flatfields should strictly be
taken after every long exposure or at least once during the course of
the sequence of exposures rather than before the start of observing
when the telescope is usually at the zenith. Whether you choose to do
this depends on how carefully you want to do the flatfielding.

\subsubsection{Wavelength calibration}
\label{sec-wavecal}

The relation between wavelength and position on the detector is not
linear and it is necessary to determine this relationship
through observations of wavelength calibration sources. The presence
of optical distortion means that there will be small differences
in this relationship between different spectra in the field so it is
important to derive this relationship separately for each slit in the
mask.

In addition, in common with all spectrographs, the instrument flexes
slightly as the telescope tracks across the sky. The main
manifestation of this is a slight shift in the position of spectral
features during very long exposures. In general, it is good idea to
break long exposures into several shorter sections of 1000--2000s to
allow cosmic ray events to be removed, and this also allows the
gradual shift in the wavelength-position relation to be monitored by
taking exposures of wavelength-calibration light sources.

The {\it worst} shift in the position of a spectral line on the
detector that was measured during flexure tests at RGO was found to be 
6$\mu$m for a change of attitude of 15$^\circ$. Measurements at the
telescope confirm the test results.  This amounts to about 0.25
pixel/hour in the {\it worst} case.

Wavelength calibration is quite difficult because of problems in
finding a suitable arc lamp which provides enough unblended lines over
the full spectral range of LDSS-2. 
After much experimentation, it was found that a CuAr lamp was the best
even though the lines in the blue are very faint.
As for the dispersed flat-fields, it may be worth using a colour
filter to attenuate the red lines, or perhaps use a long exposure for
the blue lines and a short exposure for the red.
In order to aid the observer, an atlas of emission line
identifications has been prepared (see Appendix~\ref{app-wavelength}).
Note that some of these lines have wavelengths which have been
determined empirically.

\subsubsection{Flux calibration}

To put extracted data onto a scale of flux density, it is necessary to
observe spectrophotometric flux standards. There is a compilation of
suitable stars in a folder in the control room. Ideally, the standard
should be observed through each slit in a mask since it is possible
that the instrument sensitivity might be a function of position within
the field. Since this is a time consuming and difficult operation, it
is more sensible to use a single observation 
either through one slit in the mask (although it will then be
necessary to calculate an offset for the telescope to put the target
on the desired slit) or through a longslit. Two longslit masks
are provided (see Section~\ref{sec-specialmasks}): one has a normal slit
width (1.5 arcsec) as used by default with INTERACT-4 masks; while the
other has a much wider slit of 10-20 arcsec designed for
spectrophotometric observations where it is necessary to get all the
light in the slit.

\newpage
\section{Reducing your data}
\label{sec-reduce}

This section gives a basic description of the LEXT functions that you
will need to reduce your data. 
A more detailed description of LEXT is given in the {\it LEXT
Reference Manual} (Appendix~\ref{app-lext}) and detailed descriptions
of individual functions are available in the extensive on-line HELP
facility.

\subsection{Distortion correction}

\label{sec-reduce-distort}

\subsubsection{Effects of distortions} 

The optical system of LDSS-2 produces small radial distortions
amounting to approximately 2\% of the radius at the field edge. We may
distinguish two types of distortion: 

\begin{itemize}

\item Non-chromatic distortion which is the amount by which the
centroid of an image of a point source deviates from the position
predicted in the absence of distortion.
Generally the prediction is made by adopting the reduction factor
appropriate for the centre of the field (given roughly by the ratio of
the telescope to camera focal ratios $= 11/2 = 5.5$). This amounts to
a maximum of 2\% of the radius at the field edge. 

\item Chromatic distortion which is the amount by which the centroid
of an image of a point source varies with wavelength. 
The largest distortion predicted from ray-tracing is 20$\mu$m ($=0.5$
arcsec) at about 3 arcmin off axis.

\end{itemize}

For spectroscopic observations, the effect of these distortions can be
accounted for by the extraction routines in LEXT. 

The {\it non-chromatic} distortion will manifest itself as an
additional non-linearity in the dispersion (in addition to that caused
intrinsically by the grism) which will depend on the location of the
spectrum in the field. 
The normal way to reduce LDSS spectroscopic data is to use a
wavelength calibration exposure (Section~\ref{sec-wavecal}) to
determine the non-linear pixel-to-wavelength conversion separately for
each spectrum. 
If the spectra are then resampled correctly, this source of distortion
will be exactly accounted for. 
However, this effect can introduce a small error if an object is
positioned far from the centre of the slit in the cross-dispersion
($y$) direction. 
In this case there will be a $y$ offset between the object and the
centroid of the slit which is where the wavelength calibration was 
determined. 
Since the wavelength calibration depends on position, this introduces 
a small error. 

The non-chromatic distortion will also cause the centroid of the
spectrum in the cross-dispersion direction to vary with position in
the field, in addition to the variation in centroid caused by
differential (i.e. wavelength-dependent) atmospheric refraction. 
This is normally accounted for in the reduction by the extraction
software keeping track of the centroid shift as a function of
wavelength. 

The {\it chromatic} distortion merely adds additional distortion that
is also dependent on the wavelength of the light that falls at that
position. 
It can therefore be accounted for using the standard procedures
mentioned above.

For spectroscopic data, it is therefore not necessary to remove the 
distortion explicitly. 
Indeed it would be undesirable to attempt this since it would mean
resampling the data unnecessarily which always adds noise. 

\subsubsection{ Distortion mapping.} 

For imaging data, removing the distortion explicitly may be necessary
in order to derive coordinates for objects in true tangent-plane
coordinates. 
This is important if you want to derive coordinates for mask
manufacture since these must refer to the focal plane of the telescope
which, to first order, is undistorted. 

The distortion is mapped by taking an image through the matrix mask 
and then using the  LEXT procedure ANALYZE\_MATRIX
as described in Section~\ref{sec-distort}. 
This procedure calculates a set of spline functions which describe the
forward and backward transformations. 
Here, the forward transform means distorting from the mask (i.e.
telescope focal plane) to the detector focal plane, and the backward
transform means distorting from the detector focal plane back to the
mask.
By default the forward transform is stored in a file FTRANS, and the
backward transform in a file BTRANS. 

To apply the distortion corrections use the LEXT command DISTORT: 
\begin{description}
\item {\bf DISTORT} will apply a {\it forward} (mask to image) distortion
correction.
\item {\bf DISTORT/BACK } will apply a {\it backward} (image to mask)
distortion correction.
\end{description}

Since the distortion is wavelength dependent, there will normally be a 
different pair of transformations for each filter used. 
To change the file names used by DISTORT, use the commands {\bf SET
FTRANS} {\it ftrans\_file} and {\bf SET BTRANS} {\it btrans\_file}.

The distortions can be applied to {\it lists} or {\it images}. 
In the list case the data are treated as coordinates and the
distorted coordinates will be output to a new list. 
In the image case, the whole image is distorted. 
In most cases, it is faster to derive coordinates from the original
image and apply the distortion to the coordinates rather than to
derive coordinates from the image after a distortion correction.

It is important to note the distortion correction does not account for
the simple scale change between the telescope and detector focal planes.
In each case the distortion is done in the same units, so if you 
are distorting a list of positions in CCD pixel units, the distorted
values will also be in pixel units.
If you wish to transform between mask and detector units (i.e. to just 
change the scale) you should use the command TRANSFORM: 
\begin{description}
\item {\bf TRANSFORM F} for mask to image conversions (i.e. mm to pixels) 
\item {\bf TRANSFORM B} for image to mask conversions (i.e. pixels to mm).
\end{description}
This applies a linear transformation, using LEXT globals XPIX, YPIX,
X\_CENTRE, Y\_CENTRE, FRED and ROTATION.

\subsection{Flatfielding}
\label{sec-reduce-flat}

Flat-fielding multi-object spectra is a complex procedure, and LEXT
has a special routine MAKEFF which simplifies the process. 
LEXT has no specific facilities for dealing with undispersed
flatfields since they may be conveniently reduced with standard image
reduction software.  

The dispersed flatfields are prepared by fitting the variation in
signal level with wavelength separately for each slit and dividing the
fit into the actual signal at each column. 
This is not a simple procedure since the result is undefined for
regions which do not receive any illumination --- the interslit gaps. 
The region of validity of the resultant
flatfields must be carefully defined by the extent of the slit and the
range of wavelengths over which satisfactory levels of illumination
have been obtained in the contributing exposures. The resulting
flatfields should be applied only in these defined areas. 
The preparation of the flatfields is time-consuming using standard
software (e.g. Figaro) but the LEXT routine MAKEFF makes it a
relatively easy operation. 

The input data required is a {\it dispersed} flatfield obtained with a
multiaperture mask illuminated with white light. 
Care should be taken to ensure that the exposure has  high enough
counts to make Poisson noise negligible in comparison with the size of
the flatfield variations.  

MAKEFF generates a flatfield by obtaining for the specified boxes, a
smoothed representation of the data in each column and dividing it
into the data values for each pixel in that column. 
The default is for the mean value to be used but the smoothed value
can also be obtained from:  
\begin{itemize}
\item the median over a user-specified filter width (option /MEDIAN)
\item a Chebyshev polynomial fit (option /FIT)
\end{itemize}

The option /PLOT allows the user to observe what is going on. The range 
of boxes to be processed is specified on the command line, for example 
{\bf MAKEFF/PLOT/FIT 1-3 8-13}.

\subsection{Wavelength calibration}
\label{sec-reduce-wavecal}

In order to find the relationship between pixel position, in a given
spectrum, and wavelength we use one or more dispersed, multiaperture
images of standard wavelength calibration lamps. 
The procedure is to identify strong lines of known wavelength in each
spectrum and to use this information to fit a low order polynomial
relating pixel position to absolute wavelength.
In order to get a reasonably good fit, ten or more lines should be
identified, ranging over the whole spectral range.

The facility in LEXT for doing this is ARC. 
When invoked from the command line, the user enters a sub-package from
which a smaller number of ARC specific commands can be issued.
The reader is advised to refer to the on-line HELP for full details,
but here we consider the main steps.

Before entering ARC either the whole image, or the best box should be
displayed on the image display. 
On entering ARC the first command to try is {\bf HE}, which lists the
available commands (the full HELP must be accessed from the LEXT
prompt). 
The command {\bf CP} takes the user through several options which
determine the functioning of the algorithms used later, for example,
the size of the search box used in centroiding a spectral line. 
Once these have been set up, the next step is to use the {\bf CU}
option to interactively identify several lines in one spectrum. 
The cursor positioning is only to get a first approximation, and the
software then searches for the centre of the line within the fitting
box. 
For each line a value of the wavelength, usually taken from a table or
plot of standard lines, must be input. This information is all stored
in a LIST of type LIPOS. 

Once several lines have been identified, the {\bf FI} option is then
used to perform the wavelength fit to these positions.  
The user is prompted for the order of the polynomial and the results
are stored in a LIST of type COEFS. 
If this looks acceptable we are now in a position to perform the same
procedure for all the spectra in the image. 
This is done automatically with the {\bf FA} option, which uses the
earlier results as a template for searching for lines. 
Usually this routine will find all the lines identified in the first
spectrum, although the user should follow the progress, as shown
graphically on the image display, and go back later to any dubious
fits.  

The wavelength calibration coefficients thus derived, and stored in
the COEFS list, are then picked up automatically when using EXTRACT so
that the final spectra are wavelength calibrated. 
Of course, if you are intending to perform extraction in a future LEXT
session, then this list should be written to disk before exiting. 

\subsection{Flux calibration}

Observations of spectrophotometric flux standards may be conveniently
reduced using various functions in {\it Figaro} (try the VMS HELP
facility command HELP FIGARO TECHNIQUES FLUXING after initializing
Figaro).
There are no special facilities in LEXT to do this since this is not a
specifically multiobject technique.
The resulting flux calibration as a function of wavelength can either
be read into LEXT and used during extraction to flux the extracted
spectra or applied to extracted spectra outside LEXT.
Note that in the latter case, it will be necessary to ensure that the
correct subset of the fluxing function is applied to the each of the
extracted spectra.

\subsection{Spectrum extraction}
\label{sec-reduce-extract}

Once the data in the image frame has been preprocessed, and the
required subsidiary data are available, the multiple spectra can be
extracted and calibrated. 
The main routine for this purpose is called EXTRACT. 
This routine has a large number of options allowing most of the
sophisticated reduction processing to be preformed with the one
command, provided the necessary LISTs are present. 
The normal requirements would be a BOXES list, a COEFS list and an
FSPEC list. 

The minimum requirement is the availability of an appropriate BOXES
list to define the expected positions of the spectra and objects. 
This list should have been produced by running PREBOX on the main MASK
list for the field.  
The BOXES list itself can be updated in the light of the actual data
using the UPDBOXES command. 
This allows the user to interactively identify the spectrum and object
ranges from a summed spatial profile. 

The syntax of the EXTRACT command is to have the box numbers specified
on the command line: 
\begin{quote}
LEXT -- IMAGE 1 $>$ {\bf EXTRACT 2--5 6--10 15}
\end{quote}
or, if all spectra should be processed:
\begin{quote}
LEXT -- IMAGE 1 $>$ {\bf EXTRACT ALL}
\end{quote}
Prior to running EXTRACT the user must have set up a name for the
field with {\bf SET OBJECT {\it objectname}}. 
The extracted spectra are then written to 1D FIGARO spectrum files
with file names formed by {\it objectname\_boxnumber}. 
There are many options which can be specified with EXTRACT and full
details of all of these are given in the on-line HELP. 
Here we consider the most pertinent ones. 

By default EXTRACT subtracts the sky from behind the object and then
makes a gaussian weighted sum of the counts in the object rows. 
If a COEFS list is present in the LIST stack, which is produced by
ARC, then it is picked up automatically and used to resample the data
on a linear wavelength scale. 
If an FSPEC fluxing function is available, and either the /FLUX or
/DFLUX options specified, then the output spectrum will also be flux
calibrated. 
The FSPEC list itself must be obtained from an LDSS observation of a
standard star, whose spectrum is known from some other source. 

The level behind the object is estimated by fitting to the rows of the
spectrum which contain just sky. The user will probably want to specify the
/INTER option, at least the first time through the data, so as to
have some control over this. In fact polynomial fits are used, one to the
blocked spatial profile and another to the residuals in each column after
normalizing the blocked spatial profile. The idea is that the blocked
profile gives good signal to noise for gauging the slit profile and gross
features in the background, whilst the extra column fit can account for
column to column deviations which might occur, particularly close to bright
night sky lines. The user is prompted for the polynomial orders for both of
these fits. Obviously if either of these is given as zero, then the fit
becomes effectively either pure block fitting or pure column fitting. 

The gaussian weighting scheme used in the extraction has been found to give
fairly good results, although it can be over-ridden by the /OBJECT
qualifier. Alternatively the  HORNE routine can be used to provide
more sophisticated optimal extraction, although this requires an already
sky-subtracted image, such as can be produced by {\bf EXTRACT/ALTER}. 


\newpage

\appendix
\section{LEXT manual}
\label{app-lext}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%      $$$$$  $$$$$ $$$$$ $$$$$ $$$$$  $$$$$ $$  $$  $$$$ $$$$$
%      $$  $$ $$    $$    $$    $$  $$ $$    $$$ $$ $$    $$
%      $$$$$  $$$$  $$$$  $$$$  $$$$$  $$$$  $$$$$$ $$    $$$$
%      $$  $$ $$    $$    $$    $$  $$ $$    $$ $$$ $$    $$
%      $$  $$ $$$$$ $$    $$$$$ $$  $$ $$$$$ $$  $$  $$$$ $$$$$
%                                              
%              $   $  $$$  $   $ $   $  $$$  $
%              $$ $$ $   $ $$  $ $   $ $   $ $
%              $ $ $ $$$$$ $ $ $ $   $ $$$$$ $
%              $   $ $   $ $  $$ $   $ $   $ $
%              $   $ $   $ $   $  $$$  $   $ $$$$
%
% This document represents a more detailed description of the 
% facilities offered by LEXT than the LDSS USER GUIDE, falling short
% of a discussion of internal software matters.
%
% It is intended as a useful reference for the more experienced
% or ambitious LEXT user, who is already reasonably familiar
% with the basic observing procedure and reduction process.
%
% It is organised into functional sections (extensively cross-referenced).
%
% Slightly edited by Jeremy Allington-Smith
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\def\secs {$^{\prime\prime}$}
\def\ss {{\it slot}}
\def\Ss {{\it Slot}}
\def\st {{\it stack}}
\def\St {{\it Stack}}
\def\ty {{\it type}}
\def\Ty {{\it Type}}
\def\la {{\it label}}
\def\La {{\it Label}}
\def\sls {{\it slots}}
\def\Sls {{\it Slots}}
\def\sts {{\it stacks}}
\def\Sts {{\it Stacks}}
\def\tys {{\it types}}
\def\Tys {{\it Types}}
\def\las {{\it labels}}
\def\Las {{\it Labels}}

\begin{center}
\LARGE{\bf LEXT REFERENCE MANUAL}
\end{center}
\begin{center}
{\bf Nial Tanvir}
\end{center}

\begin{center}
\fbox{\fbox{\bf This DRAFT dated \today }}
\end{center}

{\it This document describes the LEXT software package developed to support
the LDSS-2 instrument at the WHT. It provides facilities to design 
multiaperture masks, acquire the target field and reduce the resultant 
data. }

{\it This version differs from the original AAT LEXT (originated by Richard
Hook) in several respects. Most notably, data access is now done using DSA
routines, and hence both the FIGARO/DST and NDF/SDF images are now
supported data formats. There are new routines to support the LDSS-2
convention for specification of masks, field acquisition procedure and data
reduction. In addition there are a large number of minor enhancements, such
as the propagation and use of FITS header information, improved arc-line
fitting, improved sky-subtraction, more examination and filter options.
Finally the LEXT procedure language has been enhanced to allow considerably
more powerful procedures.} 

\newpage 

\tableofcontents

\newpage


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Introduction}
\label {Intro}

LEXT is a software package designed to provide facilities
to aid the use of the {\it Low Dispersion Survey Spectrograph, LDSS-2}
instrument at the {\it William Herschel Telescope}.
It was written \footnote{Originally by Richard Hook, with enhancements
by several people, notably Mathew Colless and Keith Taylor}
for use with the LDSS multi-slit 
spectrograph, at the Anglo Australian Telescope.
It is intended primarily as an aid to observations in the areas
of mask preparation, target acquisition and
fast data reduction.
Nonetheless, it provides powerful tools for the extraction of
the spectra, and is designed to interface to the Figaro system
which offers extensive further facilities.
It is implemented to run under VAX/VMS
\footnote {A version of LEXT has also been produced which runs on a SPARCstation
with only slightly reduced functionality.}
and is partly incorporated into the STARLINK ADAM environment.

Thus, its functions can be considered to be in three categories:
\begin{itemize}
  \item simple, general purpose, data processing routines. eg. adding two
        images
  \item more sophisticated tasks which deal with the extraction and
        calibration of the multiple spectra from 2D images.
  \item tools which are rather specific to the LDSS system,
        such as multislit mask design, and target acquisition.
\end {itemize}

The detailed working of these commands is the subject of this document.
For a more general discussion of the common operations
and procedures, and examples of their use, the reader is recommended
to refer to the {\it LDSS-2  Observer Manual}.


Unlike many other software packages, such as FIGARO, LEXT is a monolithic
program. External {\it images} are read into the package and stored in a
stack, where they can be operated on {\it in situ}.
There is also a stack for tabulated information, called {\it lists},
which are used to store and communicate data such as slit positions etc.
(see Section~\ref{stack}).
A large number of internal parameters control aspects
of the interface, such as graphics pen colour, and store standard
instrumental data, such as the physical size of the detector pixels.
Many of the more sophisticated commands rely on the presence of
list information defining, for example, the approximate position
of the spectra within the image.
It is intended largely for interactive use, and provides no special facilities
for batch processing.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Description of the user interface}
\label{interface}

The prerequisites for running the package are outlined in the {\it LEXT
Installation Manual}. Assuming everything is correctly set up, the package
is invoked from DCL by typing: 
\begin{quote}
{\tt\$  LEXT}
\end{quote}
The startup file is executed (see section~\ref{startup} for description)
and several status messages are written to the screen. The main prompt then
appears: 
\begin{quote}
{\tt LEXT - IMAGE 1 >}
\end{quote}

LEXT is command language driven, with a fairly sophisticated interpreter.
The LEXT commands themselves, summarised in appendix~\ref{dictionary},
have the familiar DCL format of verb (or 
command), nouns (or parameters), and adverbs (or qualifiers).
The interpreter normally accepts the minimum unambiguous shortening for
commands and qualifiers.

If the necessary information is not supplied on the 
command line then it is prompted for through the parameter system.
When prompted the user can either supply the parameter value, or, if a
default is offered, press {\tt Return} to accept this . Alternatively the
user can type {\tt ?} to get a brief help description of the input
required, or type {\tt !} or {\tt !!} to exit the routine back to the
command line. Some routines, which are likely to be a long time in
execution, and which are reporting to the terminal, may be aborted using
{\tt Ctrl-C}, which should be trapped and returning you to the command line.
This does not apply to, for example, graphical displaying. 

The parameters are frequently slots which are the internal data storage
objects, as described in section~\ref{stack}. Slots are referenced  by
their number rather than the name of the object they contain. The command 
prompt includes the number of the slot currently in use and the current 
{\it mode}.

Most operations, by default, use the current slot as the source and the
first free slot as destination. Some operations are specific to either
list or image, whilst others may apply to both (eg. {\tt COPY}). 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection {LEXT procedures}
\label {procs}

LEXT has the facility of running commands from {\it procedure} files
similar to DCL command files. These must consist of an ordered sequence of
LEXT commands as they would have been entered on the command line,
interspersed with control commands, which all begin with a colon. 

The procedure file is invoked by typing its name on the command line. In
rare cases where there might be confusion of the name of a procedure with
one of the LEXT built-in commands, then the user can make it clear to the
program that a PROC is desired by prefixing the name with {\tt <}. The
default file extension is {\tt .PROC}. If the procedure file is not found
in the default directory, then it is searched for in the directory pointed
to by {\tt LDSS\_PROC}. The individual command lines are optionally echoed
to the terminal depending on the state of the internal control parameter
{\tt ECHO}. Any necessary information not supplied within the procedure
will be prompted for in the normal way. 

If the procedure is interrupted, by a bad error status, {\tt Ctrl-C}
interrupt trap or answering {\tt NO} to the {\tt OK?} prompt,
then it can be resumed by typing {\tt CONTINUE} as a subsequent command.
The only restriction on this is that no other {\it procedure} file should be 
run in the mean time.

A procedure can be generated using a utility started by the {\tt PROC}
command. This takes a file name as an argument, into which the procedure
commands are to be saved. On entering this facility the prompt changes and
the user types in each line of their procedure. A simpler method is to use 
a text editor to generate the file via {\tt EDIT} or {\tt \$EDIT}.

The available procedure commands are:
\begin{itemize}
\item {\tt :LABEL <label>} to label a line
\item {\tt :GOTO <label>} to switch control to a new line determined by the 
      label
\item {\tt :ONERR <label>} causes the procedure to jump to the specified 
      label if an error occurs. It will remain in effect until cancelled 
      with {\tt : ONERR} with no label specified.
\item {\tt :LOOP <number>} will come back to this point at the next {\tt 
      :BACK} command. It does this {\tt <number>} times in total.
\item {\tt :BACK} ends a loop. Within a loop the current value of the loop
      counter can be used as an input parameter by denoting it {\tt \$\$\$}
\item {\tt :QUERY} simply prompts for {\it Yes or No}. If the response is
      {\it Y} then it executes the next line, if {\it N} the next line is 
      skipped.
\end {itemize}

Procedures can take arguments which are simply used to replace any
instances of {\tt \$<n>} in the procedure, where {\tt <n>} is the number of the 
argument in the list. For example:
\begin{quote}
{\tt LEXT - LIST 7 > MOBY dick}
\end{quote}
will execute procedure {\tt MOBY} and replace all occurences in that 
procedure of {\tt \$1} with {\tt dick}. Procedures may also be nested.       

An example of a procedure is shown in Appendix~\ref{app-proc}.

%%%%%%%%%%%%%%%%%% 

\subsection {Access to the operating system}
\label {DCL}

From the command line there is access to individual DCL commands
by issuing them prefixed with a
{\tt \$}, or {\tt OS}.
Thus:
\begin{quote}
\begin {verbatim}
LEXT - IMAGE mode > $ SHOW TIME
+ Creating DCL subprocess. Please wait...
  1-JAN-1999 12:52:48
\end{verbatim}
\end{quote}

Since DCL access is provided via a sub-process, DCL commands
which are intended to refer to the parent process,
such as {\tt SET DEFAULT}, will {\it not} work.
The subprocess , which is created the first time DCL is invoked,
takes a few seconds to start up, but remains running so that subsequent
commands are quicker.

\subsection {On-line HELP.}
\label {help}

There is an extensive HELP facility, based around the Starlink portable
help system. This is entered by typing {\tt HELP} from the command line.
There are detailed descriptions of all commands and options, as well as some
notes on more general matters, such as standard procedures. 

There is also single line help available for some parameters by typing 
{\tt ?} at the parameter prompt.

%%%%%%%%%%%%%%%%%%

\subsection {Ending a LEXT session}
\label {ending}

To finish a session in an orderly way, any of the standard commands will 
suffice, namely {\tt END}, {\tt EXIT} or {\tt QUIT}.
If any slots are flagged to be saved (see section~\ref{status}) 
then the user is returned to the prompt.
To finish fast, without checking for whether slots require saving, type
{\tt KILL}.

The use of {\tt Ctrl-Y} will also exit the program, but it is not recommended.
Should the program finish by either a {\tt Ctrl-Y} interupt, or due to
some other `dirty' exit, the images constituting the image stack
will remain in the directory LDSS\_STACK. If required, and assuming they
are uncorrupted, these should be copied or renamed appropriately.
The old image stack is deleted when LEXT is run again.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section {The internal data stack}
\label {stack}

LEXT recognises two fundamentally different data structures; the {\it list} 
and
the {\it image}. Lists are 2D tables of numbers, whilst images are arrays of
discrete pixel values. 

%%%%%%%%%%%%%%%%%%

\subsection {Lists}
\label {lists}

Much of the information required and generated by LEXT is tabular in nature.
This may be information about objects, spectral lines, mask parameters etc.
The generic name for these tables is the list.
Since they can contain different things, lists are distinguished by their
{\ty}.
The {\ty} is held within the list data structure along with a descriptive
{\la}, the details of the number of columns and entries in the list, and,
where appropriate, the column headers.

Some functions which can be performed on lists are {\ty} specific.
In many cases there should be one LIST of a particular {\ty}
corresponding to the particular observation being reduced.
In these instances routines which require a particular 
such LIST will search the stack for it, and will report
an error if they don't find precisely one.
An attempt to produce more than one list of certain {\tys} (eg. MASK)
will also result in an error for this reason.

LISTs which are created as output by LEXT commands, are usually given
their {\ty}, and also their {\la}, automatically.

The complete set of standard list {\tys} is given in
appendix~\ref{listypes}. 

\subsection {Images}
\label {images}

These contain the multiple spectra, and any further reduced data or
calibration frames. One might also have direct images for use with target
selection and astrometry. 

Images can be {\tt READ} into slots in the LEXT image stack.
When an image is read into LEXT, a copy of the disk image is made,
and it is this copy which is then worked on. For this reason, many of
the LEXT commands work on the data {\it in situ}. 
In order to save a modified image it must be written out again with
the {\tt WRITE} command.

Within the image structure, along with the data-array itself, is 
a descriptive {\la} and a {\ty}.
{\La} is a description of the contents, purely for user information.
The {\ty} is used by LEXT in certain instances which will be described
in the appropriate sections below.

\subsection {Creating lists and images internally}
\label {create}

LEXT can generate a list or image slot internally using the {\tt CREATE}
command. The slot is simply filled with a user supplied constant value. The
{\tt CREATE} command also has options which allow the creation of
particular forms of list, which are used in conjunction with distortion
mapping and fitting routines: 

% nrt - these could be moved to the relevant place which describes 
% nrt - what they're for.
% nrt - yes definitely.

\begin {itemize}
  \item {\tt /KNOTS} for use with {\tt SFIT}
  \item {\tt /GRID} which creates a simple list of grid coordinates, 
        of {\ty} MLIST, for use with distortion mapping
  \item {\tt /FIBOX} which creates a list of boxes (of user
        specified size) around each object position in the current list, 
        for use with {\tt FIT}. This option could be used, for example, 
        to find more precise centroids for the objects in an image.
  \item {\tt /MASK} is used to generate a FIBOX list such that the
        boxes are defined to encompass the images of the slits in
        a direct image. A MASK list must be present.
  \item {\tt /BOXES} uses a list which has been created with {\tt CURSOR}
        to generate a BOXES list in instances where no MASK list
        is available.
\end {itemize}

%%%%%%%%%%%%%%%%

\subsection {Mode of operation}
\label {mode}

LEXT works in two modes corresponding to the stack which it is currently
using. The user toggles between modes by use of the {\tt IMAGE} and
{\tt LIST} commands.

Many of the generalised functions can be performed on list or image data.
The interpretation of the commands depends on the current mode of 
operation.

%%%%%%%%%%%%%%%%%%

\subsection {Manipulating the data stack}
\label {stackops}

Internally LEXT holds images and lists in its own in a stack system. There
is a separate stack for lists and images. Each stack position is referred
to as a slot. The dimensions of the slots and stacks are defined in a
startup file (ie. the maximum size of both images and lists and the number
of image and list slots). If this is not present in the default directory
then the required values are prompted for. 

% Since a large stack will take up a large amount of virtual memory
% there is some advantage in keeping the stack sizes to a minimum.

The following commands allow stack examination and manipulation:
\begin {itemize}
  \item {\tt DIRECTORY} provides information on all the slots
        of the current mode.
  \item {\tt EMPTY} is used to clear a slot.
        By default this command works on the current slot, although
        a slot number or {\tt /ALL} may be given as a parameter.
        This command works irrespective of the state (protection) of the slot,
        and the data is lost. (In fact images erroneously deleted may be
        recovered as they should still reside in the LDSS\_STACK directory).
  \item {\tt COPY} copies a whole slot to another slot location.
        Only the {\la} is changed to one which reflects the fact that
        it is a duplicate.
        The destination slot must not be protected.
        In list mode an additional qualifier {\tt /COLUMNS} allows extra
        columns to be appended to the output.
  \item {\tt BACK} steps the slot pointer back one position (with wrap-around).
  \item {\tt NEXT} steps the slot pointer forwards one position (with 
        wrap-around).
  \item {\tt USE} allows specification of current slot number. Alternatively
        just typing the number of the required slot on the command line
        is acceptable shorthand. {\tt USE/TYPE} allows the specification
        of the slot {\ty} desired. Obviously this option will only work
        if there is just one slot of that type in the stack.
\end {itemize}


%%%%%%%%%%%%%%%%%%

\subsection{Slot status}
\label {status}

When the stack pointer is moved to a new slot its status, that is to say
its number, {\ty}, {\la}, and, in the case of an image, the filename, is
displayed. The {\la} is a full description of the contents of the slot, for
the benefit of the user. 

The command {\tt RELABEL} is used to change the {\la} on a list or image.
Sensible {\las} are generated automatically when a list or image is
created by a LEXT command. {\tt RETYPE} peforms a similar task to change
the {\ty}, although, since these may have semantic meanings to some
routines, this command should be used with care. 


%%%%%%%%%%%%%%%%%% 

\subsection {Slot protection}
\label {prot}

Each slot also has a state which offers three levels of protection: {\tt
occupied}, {\tt protected} and {\tt save}. The corresponding commands to
set this protection are: 

\begin {itemize}

  \item {\tt PROTECT} makes the slot `write' protected, so that the contents
        can't be modified, but may still be deleted.
  \item {\tt FREE} removes the protection from a slot, to leave it `occupied'.
        Any operation which is going to alter
        the contents of a slot requires the slot to be unprotected.
  \item {\tt SAVE} flags a slot to be saved on exit from the program.
        In fact, this is not an automatic procedure: the user simply
        returned to the main prompt and is informed
        which slots are flagged to be saved.
\end {itemize}

In each case the {\tt /ALL} qualifier can be used in list mode to apply to all
the {\ss}s in the {\st} rather than just the current.

%%%%%%%%%%%%%%%%%%

\subsection {Startup file}
\label {startup}

When LEXT is started it looks for a file called LEXT.STARTUP.
This file should contain the dimensions of the stacks and slots and the 
optionally the command {\tt INIT}, which actually makes the memory available
for the list data block.
{\tt INIT} is only required if the startup procedure contains further
LEXT commands, say, to automatically read in the list data files.
If LEXT.STARTUP is not present then defaults are used where applicable 
and the remaining values are prompted for.

The dimensions of the image slots and are {\tt SET} via the following
internal variables:

\begin{itemize}
  \item {\tt Nx} defines the number of image pixels in the X-direction.
  \item {\tt Ny} defines the number of image pixels in the Y-direction.
\end {itemize}

Further LEXT or DCL commands can be issued from the startup file
allowing the user to customise the session, and read in commonly required
data.
In the case of lists use, the command {\tt INIT} must first be used to
tell LEXT to create the necessary internal data storage.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section {Internal parameters and header information}
\label {internals}

LEXT stores a variety of internal parameters. Some of these hold
information about the instrumental/detector setup, whilst others control
interface options, such as the current pen colour. Many of the LEXT
commands make use of this information so it is important that it is set
correctly. Some of the internal parameters may correspond to information
contained in the FITS headers of the images. The user can ensure
consistency by using the {\tt SHOW} and {\tt SET} commands which are
detailed below. 

Certain of these parameters are set by a specific command, such as the
graphics device name, whilst others go through the {\tt SET} command. The
current mode can be set by either; thus: 
\begin{quote}
{\tt LEXT - LIST 1 > IMAGE}
\end{quote}
is the same as writing:
\begin{quote}
{\tt LEXT - LIST 1 > SET MODE IMAGE}
\end{quote}

%%%%%%%%%%%%%%%%%%

\subsection {Examining and saving parameter settings}
\label {show}

The
{\tt SHOW} command provides details of the current values
of some internal parameters, and is dependent on the current {\it mode}.
Several qualifiers enable access to more information:

\begin{itemize}
  \item {\tt SHOW/INST} displays the settings of the instrumental parameters
        listed below.
  \item {\tt SHOW/TELESCOPE} details the telescope parameters.
  \item {\tt SHOW/MASK} gives details of various mask parameters.
  \item {\tt SHOW/PLOTTER} gives the plotter settings.
  \item {\tt SHOW/HEADER} produces a formatted list of the FITS header items
        which are available for the current image.
        It may often be useful to use these to set the corresponding internal
        parameters.
  \item {\tt SHOW/ALL} shows all the LEXT internal parameters.
\end{itemize}

Some internal variables can be saved for future use by the {\tt SAVESET}
command. By default these use a file called LEXT.SET.
This file is written as a standard LEXT procedure file, and, hence,
can be easily invoked to re-set the values of the internal variables.
Being an ASCII file, it can also be easily edited outside LEXT.
For standard setups it would be sensible to give a more specific name to this
file.

The {\tt SET} command can be used to set the value of internal parameters.
Care should be taken to use the correct units when setting internal
parameters.

%%%%%%%%%%%%%%%%%%

\subsection {Interface options}
\label {intops}

The various interface options are each described in detail in their
appropriate sections. They are:

\begin{itemize}
  \item MODE: {\it list} or {\it image}.
  \item PEN: The colour on image displays, but has no meaning
        for hardcopies. 
  \item XST: X-coordinate of start region of interest.
  \item YST: Y-coordinate of start of region of interest.
  \item XEND: X-coordinate of end of region of interest.
  \item YEND: Y-coordinate of end of region of interest.
  \item ECHO: Decides if commands run within a procedure are
        displayed on the screen to the user.
  \item MARKER: The specification of symbols for hardcopy plots.
        These are defined in the PGPLOT manual, and are specified
        by a number in the range 0 to 127.
        The numbers after 31 are just the corresponding ASCII characters.
\end {itemize}

All of these can be changed with the SET command, although one further
interface option, the graphics device, can only be set with the specific
{\tt DEVICE} command.


\subsection {Instrumental parameters}
\label {instops}

Certain fixed parameters which specify details of the instrumental setup
are held internally by LEXT so that they can be accessed automatically by
any routine. 

These are:

\begin {itemize}
  \item CAMFIELD: the field of the camera in (mm)
  \item COLFIELD: the field of the collimator in (arcmin)
  \item DETECTOR: the detector ID (for information only)
  \item DISPERSION: the dispersion at the detector (\AA/mm) 
  \item FRED: the focal reduction factor between the focal (mask) plane 
        and the detector
  \item FTRANS and BTRANS: the files (.DST or .SDF) used for forward and 
        backward distortion correction --- set to {\tt NONE} if not 
        specified
  \item LAMBLAZE: the blaze (strictly the undeviated) wavelength 
        (\AA)
  \item LAMMAX: wavelength corresponding to the red extreme of the
        spectrum (\AA).
  \item LAMMIN: wavelength corresponding to the blue extreme of the
        spectrum (\AA)
  \item LAMZERO: the $x$ position of the zero-order images, expressed as a
        wavelength of the first order spectrum (\AA) 
  \item MISVAL: the magic value used to designate an invalid pixel
  \item OBJECT: the name of the current field. This is used to generate
        the names given to the files containing the extracted spectra.
  \item OBJECTEXTENT: the typical extent of an object on the sky 
        (arcsec).
  \item ROTATION: the rotation between the mask and detector coordinate 
        systems (degrees measured {\it clockwise} on the detector)
  \item TILT: the value of the inclination of the spectra within the
        boxes (degrees measured {\it clockwise}).
        This variable is used when plotting BOXES and in the weighting
        scheme used by {\tt SQUASH}, but is currently ignored
        in the extraction routines, which have other ways of dealing
        with small tilts.
        NB: TILT does not mean a tilt of the whole spectra relative
        to the detector, but only a tilt of the locus of the object.
  \item XCENTRE and YCENTRE: the ($x$,$y$) coordinate on the 
        detector which corresponds to the origin of the mask coordinate 
        system (pixel)
  \item XPIX and YPIX: the size of the detector pixels ($\mu$m)
  \item XSLIT and YSLIT: the default length of the slit in $x$ 
        and $y$ ($\mu$m)
  \item X\_FORMAT and Y\_FORMAT: the size of the detector (pixels)
\end {itemize}

These can also be assigned values with the {\tt SET} command, although some
can also be redefined as a result of certain LEXT operations such as LFIT. 

\subsection {Mask parameters}

These consist of some of the defaults used in mask design, and also the
field scale at the mask focal plane.

\begin{itemize}
  \item SCALE: the image scale at the focal plane of the telescope,
        ie. at the mask (arcsec/mm) (The scale at the detector is given by 
        SCALE $\times$ FRED)
  \item MAXSLITLEN: the maximum allowed length of mask slit 
          on the sky (arcsec)
  \item MINYMARGIN: the minimum allowed distance between the object
        and the ends of the slit (arcsec)
  \item MINYSEP: the minimum allowed separation between two slits 
        (arcsec)
  \item FIDUCDIAM: default diameter of fiducial holes (arcsec)
\end {itemize}

\subsection {Plotter parameters}
\label {plotops}

The following are classified as plotter specific items, used in generating
art-work for LDSS-1 masks at the AAT:

\begin {itemize}
  \item PENWIDTH: the line thickness for hard-copy plots
  \item PSCALE:   scaling factor for hardcopy plots
  \item ROH\_SEP: the separation between holes in a
        row-of-holes mask in the Y-direction (arcsec)
  \item ROH\_SIZ: the length of a row-of-holes in the Y-direction 
        (arcsec)
  \item SLITWIDTH:  slit width (arcsec)
\end {itemize}


%%%%%%%%%%%%%%%%%%

\subsection {Telescope parameters}
\label {telops}

The following are classified as telescope specific information:

\begin {itemize}
  \item GP\_X0: X-coordinate for the guide-probe origin (AAT specific).
  \item GP\_Y0: Y-coordinate for the guide-probe origin (ATT specific).
  \item DRZ: differential atmospheric refraction at the zenith
        such that \[ {\rm apparent scale} = {\rm actual scale} \times
        (1 + {\rm DRZ})\].
  \item LATOBS: the latitude of the observatory.
  \item SCALE0: the linear scaling factor from the sky to the mask (radians/mm)
        -- similar to Scale
  \item SCALE1: the non-linear term for more precise scaling -- should
                be zero at WHT.
  \item SCALE2: the power term for the scaling -- should be zero at WHT
\end {itemize}

The command {\tt SET FIELD} prompts the user to enter a description
of the field-centre coordinates, RA, DEC, EQUINOX, EPOCH and POSITION\_ANGLE.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 

\section {Data import and export}
\label {io}

As described in section~\ref{stack}, LEXT has two `internal' data structures,
the {\it list} and the {\it image}, although both
may be further distinguished  by their {\ty}.
Data can be read into, and written from, these internal {\ss}s in a
variety of ways.

The I/O is principally performed with the
commands {\tt READ} and {\tt WRITE}.
The same commands are used for both lists and images.
When a new file is read, it is stored in the first available slot and
its state is automatically set to `protected'.
Further modification of the data will require it to be {\tt FREE}d.

In IMAGE mode data access is performed via the Figaro DSA/DTA routines.
Thus it is possible to read and write both FIGARO DST/HDS files or STARLINK
NDF(SDF) files. The default is determined by the DCL logical name
FIGARO\_FORMATS which should be setup with DEFINE/JOB. For example, this
should be set to ``NDF,DST'', if NDF's were the default, but specific DST's
might need to be read. 

It is important that images are read in in such a way as to leave the
red end of the spectrum at the right, and with north up. All possible
transformations can be accomodated by use of the qualifiers {\tt /1}
up to {\tt /8}. At the time of writing the WHT Tektronix chip required {\tt /3},
which represents a rotation of $180^{\circ}$.

In list mode the default external representation is as a Figaro DTA/HDS
file. These files can be examined outside LEXT, with FIGARO EXAM or
STARLINK TRACE. These files are unique to LEXT and are not appropriate for
input into any other packages. 

Any list may also be written or read as an ASCII file by specifying the
{\tt /FORMATTED} qualifier. The number of columns in the file must be
specified in advance using {\tt SET NCOLUMNS}. A special option to allow
the list to be entered directly at the keyboard, use {\tt READ/FORMATTED
HAND}. 

Extracted spectra may be written into a FIGARO `SPEC' file by specifying
{\tt /SPEC}. These can then be used as input into FIGARO routines which
operate on 1D spectra. 

The command {\tt FPRINT} creates a formatted list of object information
from the POS and MASK lists. Specifically the positions and dimensions of
the slits on the mask, and the positions and magnitudes of the objects on
the sky. The MASK list, which may be a subset of the POS list, is used as
an index and each object is looked up in turn. 

The {\tt /CAT} qualifier, required to read and write the special object
list files is described in more detail below. {\tt /MANUFACTURE} is used to
output the WHT style of MASK design instructions into an ASCII disk file. 

A new list or image may be created and initialised with the command {\tt
CREATE}. If no qualifiers are present the new structure will contain only
an array of constants, and will have {\ty} TEMP. 



%%%%%%%%%%%%%%%%%%

\subsection {Object catalogues}
\label {catalog}

Catalogue files are the preferred medium for reading and writing
high-precision mask coordinates by LEXT.  They are read into LEXT with
the {\tt READ/CAT} command and written with {\tt WRITE/CAT}. They are text files
written in a free format using common astronomical conventions and are
thus easily generated from coordinate lists. Their default file type is
{\tt .CAT}, and they must have a maximum record length of 132 characters.  A 
catalogue written with {\tt WRITE/CAT} can later be read back into LEXT with 
{\tt READ/CAT}.
Internally the information from a catalogue is stored as a MASK list.

The lines in the file are either interpreted as containing keyword values,
object coordinates or a comment. Keywords are valid for the whole file.
Coordinate and keyword lines can be mixed in any manner throughout the
file. However, for the sake of readability, it is best to segregate the
keyword lines to either the top or bottom of the file. Keyword and
coordinate lines are distinguished by whether non-numeric characters are
present. Coordinate lines must only contain numerals, wild card character
{\tt *}, and optional comments at the end. If anything other than the
characters {\tt 0123456789+-.ED*! } are present, the line is interpreted as
being a keyword line. Characters to the right of an exclamation mark {\tt
!} are interpreted as a comment and are ignored. Lines that {\tt READ/CAT}
can not interpret are also ignored. 

\subsubsection {Coordinate entries}
\label {coords}

The format for a coordinate line is
\begin{quote}
$<$ID$>$\ $<$RA$>$\ $<$Dec$>$\ $[$Wt$]$\ $[$SL$]$\ $[$Offset$]$\ $[$X$]$\ $[$Y$]$
\end{quote}

The fields are:

\begin {description} 
%{}{\setlength{\leftmargin}{3cm}\setlength{\labelwidth}{2.5cm}}
  \item{\bf $<$ID$>$} Identification number of object. 
  \item{\bf $<$RA$>$} Right Ascension of object. RA is in hours of time, and
                   should be a sexagesimal string, that is standard hours 
                   minutes seconds (HH MM SS.SSS) format, although formats 
                   such as HH MM.MMMMM, or even HH.HHHH are also accepted. 
  \item{\bf $<$Dec$>$} Declination of object.  This is in degrees and should 
                    also be in sexagesimal format ($\pm$ DD MM SS.SS), 
                    although formats such as $\pm$ DD MM.MMMMM, or 
                    $\pm$ DD.DDDDDD are also acceptable.  The sign 
                    of the declination ($\pm$) is optional for northern 
                    objects but mandatory for southern objects. 
  \item{\bf [Wt]}    Weight for growing slits.  Larger weights mean slits grow 
                    faster.  Wt = 0.0 is reserved for fiducial stars used for 
                    aligning the mask.  A centred hole is placed at the mask 
                    position of such objects, while slits are used for other 
                    (WT $>$ 0) objects.  Negative weights should not be used, 
                    except for WT = MISVAL = -32767, which marks a ``deleted" 
                    object. 
% nrt - are -ve weights still out?
  \item{\bf [Sl]}    The slit length (or fiducial hole diameter).  The default 
                     units are arcsecs, although this can be changed 
                     with the MMUNit keyword. 
  \item{\bf[Offset]} The $y$ coordinate difference between the slit centre 
                     and object position: $[Offset] = Y_{\rm cen} - Y_{\rm 
                     obj}$.  The 
                     slits are drawn parallel to the $y$ axis, and therefore 
                     they have the same $x$ coordinate as the object.  The 
                     default units are arcseconds, although this can 
                     be changed with the MMUNit keyword. 
  \item{\bf [X]}     The $x$ coordinate of the object on the mask in mm. 
  \item{\bf [Y]}     The $y$ coordinate of the object on the mask in mm. 
\end{description} 
        
The fields in angle brackets ($<>$) are required, while those in square
brackets ([~]) are optional.  Fields are delimited by one or more spaces.
Defaults are assumed for blank fields, and were denoted by a word
starting with {\tt *}.  
{\tt X} and {\tt Y} are
written with a {\tt WRITE/CAT} but are ignored
by {\tt READ/CAT} which recalculates them from the positions and field centre
parameters. 

\subsubsection{Keyword entries}
\label {keywords}

The keyword lines are of the format
\begin{quote}
$<$keyword$>$ $<$value$>$
\end{quote}
and the currently recognized keywords are 

\begin{description}
%{list} {}{\setlength{\leftmargin}{3cm}\setlength{\labelwidth}{2.5cm}}
  \item{\bf LABEL}    * Acts as a label for the field.
  \item{\bf CENtre}   * The Right Ascension and declination of the field centre in 
                     sexgesimal format (as above). The coordinates must be in 
                     the same equinox as the coordinate list. 
  \item{\bf EQuinox}  * The equinox of the coordinate system used, in years.  This 
                     MUST NOT be prefixed by B or J (eg neither B1950 nor 
                     J2000 is understood; use 1950 and 2000 instead).
% nrt - should this be changed?
  \item{\bf EPoch}    * The epoch of observation, in years eg 1990.85.
  \item{\bf PA}         The APPARENT PLACE position angle of the mask in degrees 
                     measured from north towards the east.  This is equal to 
                     the positional angle of a slit at the field centre.
                     However, since all slits are parallel to the Y axis and 
                     sky coordinates are non-cartesian, there will be some 
                     rotation of position angles away from the field
                     centre.  Default = 0.0 (ie North-South slits).
  \item{\bf SLObj}      The slit length for objects with a blank slit length field.
                     Default is set by the LEXT global "MINSLITLEN" in arcsecs.
  \item{\bf SLFid}      The diameter of fiducial star holes which have a blank 
                     slit length field.  Default is set by the LEXT global 
                     "FIDUCDIAM" in arcsecs.
  \item{\bf WDEF}       The slit growing weight for objects with a blank weight 
                     field.  Default is 1.0
  \item{\bf OFFDefault} The offset of the slit centre from the object position 
                     along the Y axis, for objects with a blank offset field.
                     Default is 0.0
  \item{\bf MMUNit}     The scale in mm/units at the focal plane for slit lengths, 
                     and offsets used in this file.  This includes the values 
                     for SLO, SLF, and OFFD.  MMUN defaults to the mm/arcsec 
                     scale of the telescope (ie 1/6.7 for the f/8 focus of 
                     the AAT).  
\end {description}

Only the capitalized letters are required for the keywords (although they
do not have to be capitalized in the file). Extra letters beyond those
capitalized above are not considered, so that ``SLOPE", and "EQUATE" will
be interpreted as the "SLObj", and "EQuinox" keywords respectively. Keyword
lines marked with a * are required.  If they are not in the file values are
prompted for when the file is read by READ/CAT. 

\section {Mask manufacturing tools}
\label {masks}

There are facilities within LEXT to help prepare the parameters for mask
manufacture. These are described here, but for a discussion of their use in
practice, see the {\it LDSS-2 Observer Manual}. 

\begin {itemize}
  \item {\tt PREBOX}: this routine is used to transform a MASK list,
        which contains the specification of the mask, ie. the slits
        and fiducial holes, in units of mm at the mask, into a
        BOXES list which contains the details of where the spectra
        are expected to lie on the detector.
        This routine makes use of the internal variables which
        define the linear mapping from mask coordinates to detector
        coordinates. Also, if available, it automatically applies
        the field distortion, which is stored in either image or list
        form.
        In order to calculate the extent of the boxes it uses the
        internal variables LAMMIN, LAMMAX and LAMBLAZE.
  \item {\tt PREDIRECT}: this routine works similarly to {\tt PREBOX}
        except that it predicts the results of a direct (undispersed) image,
        storing the results in a DRCT list.
  \item {\tt GROW}: updates the BOXES list and, if available, the MASK
        list, by expanding the slit lengths in the $y$ direction,
        up to the point where they begin to overlap.
        The rate of growth of each slit depends on the weighting given
        to the object.

        This helps make maximum use of the detector area (which
        is, in fact, reported as a figure of merit).
        Several internal parameters, such as MAXSLITLEN, MINYSEP etc.,
        define the limits of this procedure.

        Zero-orders are also monitored and are not allowed to overlap
        with other objects, but are accepted if they impinge only on a sky
        spectrum. The position of an object within a spectrum is defined
        by the position of its centre and the internal variable OBJECTEXTENT.

        If the {\tt /CHECK} qualifier is
        specified then the MASK and BOXES lists are
        simply checked for possible overlaps, and the results reported.
        The lists are not modified.
  \item Several {\tt PLOT} options are useful for mask design.
        For example, {\tt /BOXES}, {\tt /MASK}, {\tt /FIELD} and {\tt /FIDUCIAL}
        and {\tt /DIRECT}.
        These are dealt with in detail in section~\ref{plot}, 
        which describes the {\tt PLOT} command.
  \item {\tt CURSOR/EDIT}: when applied to list slots of {\ty} BOXES
        or DRCT
        this can be used to interactively modify the heights (ie.
        slit lengths) and object positions of a given entry, or
        to delete an entry completely. If there is a MASK list
        available then this will be updated simultaneously.

        The default is for this routine to delete the box in which the
        cursor is when depressed. However, for very crowded fields this
        may get complicated and the {\tt /CORNER} option means that
        the bottom left hand corner is used instead.
\end {itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section {Target acquisition tools}
\label {targets}

Precise target acquisition is particularly crucial process for a multi-slit
spectrographs. This is because of the need to align the mask, within three
degrees of freedom, so that each object is positioned at the centre of its
intended slit. 

There will be several standard procedures to aid in this process.
Here will simply outline the specialised commands which may be used:

\begin {itemize}
  \item {\tt CREATE/MASK}: if there is a MASK list in the stack it is used to
        generate a new FIBOX
        list which consists of boxes defined so as to surround each slit in the
        mask. This is useful for finding the centroids of slits in a direct image
        of the mask. 
        This may be used in conjunction with {\tt FIT/LINE}.
  \item {\tt FIDUCIAL}: takes the output FIBOX list from {\tt CREATE/FIDUCIAL}
        and locates the centres of the fiducial holes.
  \item {\tt FIT/FIDUCIAL}: then locates the stellar centroids within the
        windows found by {\tt FIDUCIAL}.
\end {itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section {Mapping focal plane to detector coordinates}
\label {distort}

There are two stages to the mapping between the mask focal plane
coordiante system and the detector coordinates. The first is the linear
mapping of pixels at the detector to mm at the mask, and the second
is to account for the small optical distortion introduced into the
detector coordinates by the LDSS-2 optics.

Although generally small, field distortion is can be used for use with {\tt
PREBOX} and with mask manufacture from direct images. It is not used in the
extraction routines which have algorithms for following distortions
empirically. 

The important routines are:
\begin {itemize}
  \item {\tt LFIT} fits an optimised 5 parameter linear transform to a
        pair of list slots (ie. stretch, translation and rotation).
        The main function of this routine is to define the first order
        mapping from mask coordinates (in mm) to detector coordinates
        (in pixels). The coefficients are displayed.

        If the {\tt /STORE} qualifier is present then it is assumed that
        the fit defines the mapping of the mask coordinates onto the detector
        and resets the values of the relevant internal parameters accordingly.
        This allows the subsequent use of the {\tt TRANSFORM} command.
  \item {\tt SFIT} fits a bicubic spline to a pair of list slots.
        It thus maps the distortion between the two sets of points
        as a function of position.
        It uses a KNOTS list to define the fiducial points for which
        the spline parameters are calculated and stored.

        This routine can be used to define the distortion of a matrix
        mask image (which has been analysed by, say, {\tt MAP}), 
        compared to the expected image (see below).
        The fit is currently stored in an external transformation file.
        It can be subsequently used by the routine {\tt DISTORT}.
  \item {\tt CREATE/GRID} produces a list, according to user defined criteria
        of grid points such as would define a matrix mask.
  \item {\tt TRANSFORM} transforms the
        list coordinates between the mask ($mm$) and detector (pixels)
        systems and vice-versa. It produces a general, linear 
        transformation including rotation, translation etc.

        The transformation is defined by the internal variables
        ROTATION, XPIX, YPIX, FRED, XCENTRE and YCENTRE.
  \item {\tt EVALUATE} converts a transformation, as generated by SFIT,
        file into a 2D representation. Specifically the $x$ and $y$  shifts
        are stored in separate images which are given the {\ty} XSHFT
        and YSHFT.

        If these are available then they will be used by DISTORT in preference
        to the raw spline coefficients, since it saves on CPU time.
  \item {\tt DISTORT} applies a spline transformation, such as generated in 
        SFIT, to a list or image. By default a 
        fractional pixel interpolation
        scheme is employed, although this can be over-ridden by other
        qualifiers.
\end {itemize}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Data processing}
\label {process}

%%%%%%%%%%%%%%%%%%

\subsection {Simple Image processing}
\label {improone}

A range of useful image processing commands is available within 
LEXT. Namely:

\begin {itemize}

  \item {\tt ADDI}, {\tt SUBI}, {\tt MULI}, {\tt DIVI}
        for the combination of two images via the 
        pixel by pixel application of the specified binary operator.
        The result is stored in the next free slot.
  \item {\tt ADDC}, {\tt MULC}
        for the addition of, or multiplication by, a constant.
        The result overwrites the original.
  \item {\tt SMOOTH} applies 2D tophat (default),
        gaussian ({\tt /GAUSSIAN}) or median ({\tt /MEDIAN})
        smoothing to an image.
        The size and specification of the filter is prompted for.
        This routine operates on the current region unless over-ridden
        with the {\tt /ALL} option.
\end {itemize}

These might be used for basic calibration such as debiasing and flat-fielding
of the data.





%%%%%%%%%%%%%%%%%%

\subsection {Simple List processing.}
\label {lisproone}

As with image processing there is a range of commands which allow simple
operations to be performed on the contents of lists. With lists commands
act on either the whole list or just a specified column, as appropriate. 

In fact several of the commands are identical to those for images and the
context in which they operate depends on the current mode, namely {\it
list} or {\it image}. For example, if {\tt ADDC} is used when in list mode,
it will add a constant to a specified column within the current list. This
includes the {\tt SMOOTH} command which, in list mode, convolves the $y$
column with either a tophat or gaussian filter. 

Other commands available are:

\begin {itemize}
  \item {\tt CADD} adds the contents of one column, element by element, to 
        another column.
  \item {\tt SWAP} swaps two columns of a list slot.
  \item {\tt APPEND} appends the data in one list slot to 
        the end of another.
        This should be used with caution as LEXT does not check whether
        the list {\tys} are compatible.
  \item {\tt CCOPY} copies a list column to another 
        column in the same list, 
        or, by using the {\tt /DIFFERENT} qualifier, to another list slot.
  \item {\tt EDIT} allows the user to edit the contents of a list 
        directly through
        the STEVE editor. The new list thus created is put into a free slot
        and the user is asked to supply an appropriate {\ty} and {\la}.
  \item {\tt POLY} fits a simple (order 0 to 9) polynomial to a list slot 
        using the current $x$ and $y$ columns. Unless the {\tt /NONEW} qualifier
        is used, the
        coefficients are written to a list slot.
  \item {\tt MATCH} attempts to match the
        positions of elements in two different 
        lists. The second list is rearranged to 
        be in the same order as 
        the first, according to a nearest neighbour criterion.
\end {itemize}

\subsection {Examination and manipulation of data}
\label {manip}

\begin {itemize}
  \item The contents of a slot can be written out by use of the
        {\tt TYPE} command.
        In {\it image} mode, this types out a 5 by 19 subset at the requested
        coordinate position. The default is to centre the region on
        the coordinates given by X\_CENTRE and Y\_CENTRE, but the
        options {\tt /CURSOR} and {\tt /HAND} are also available.

        In list mode, 5 headed columns are printed
        with the range of lines being optional arguments. In this case there
        is also an optional qualifier {\tt SPECIFY} which accepts three other
        arguments which is interpreted as the start and end rows, and
        the first column from which the output
        is to begin.

        The {\tt /PRINT} option formats a temporary
        printronix file of this information, and submits it to the print queue.
  \item {\tt REPLACE} allows the user to data values of either type, to user
        specified numbers. Various qualifiers can be used such as {\tt /ENTRY},
        {\tt /ROW} etc.
  \item {\tt STATS} obtains statistics for list column or image data.
        (ie. mean, min, max, standard-deviation etc.)
  \item {\tt INVALIDATE} sets parts of a list or
        image to be flagged invalid.
        There are many options, such as use of cursor ({\tt /CURSOR}) and
        cutting out zero-order spectra ({\tt /ZERO}).
  \item {\tt CLEAN} removes the missing values from a list,
        or replaces them
        with user supplied values for an image. In the list case
        the column which is to be searched for invalids is prompted for.
\end {itemize}

%%%%%%%%%%%%%%%%%%%%%

\subsection {More sophisticated image processing}
\label {improtwo}

The following are several sophisticated image mode commands
for processes such as distortion mapping, bad data etc.:

\begin {itemize}
  \item {\tt FIT} looks at rectangular regions within an image to find the 
        positions of peaks.
        It works by finding a simple centroid, or, by use of {\tt /GAUSSIAN},
        by fitting a 2D gaussian, with some attempt at background subtraction.
        The {\tt /LINE} qualifier invokes a centroiding routine appropriate
        for a linear image such as an arc-line or the direct image of
        a slit.
        The output is stored in a CLIST.
        The regions themselves may be defined in a FIBOX list.

        If the {\tt /MASK} qualifier is specified then the FIBOX list
        is created from the positions defined in a MASK list, along
        with user defined extensions to the slit size, to be taken as
        the regions. This tool might be used to find the actual positions
        of the mask slits on a direct image, by looking in a region around
        where they are expected.
  \item {\tt MAP} searches a region of an image for peaks
        which are the stored in a list slot.
        A peak is defined as a local maximum, which is above a given
        threshold, and with all of its immediate neighbours also
        above the threshold.

        In some cases it might
        be useful to smooth the image first to minimise noise spikes.
        For example, {\tt MAP} could be applied to a matrix image and
        used in distortion mapping.
  \item {\tt RIDGE} maps the positions of ridge-like peaks in the current image.
        The user defines the direction of the ridges in the spectra
        (ie. vertical or horizontal centroiding), a threshold and
        a box width for centroiding.
  \item {\tt SUBSET} takes a subset of
        the current image, by default the current 
        region, and interpolates it to fill the next image slot.
  \item {\tt SQUASH} creates a profile of a specified BOX 
        by squashing the data in one direction. By default {\tt SQUASH}
        uses a specified box, and adds up the pixels in the $y$ direction,
        producing an XPROF list. 
        Further options are {\tt /X}, which produces a YPROF list, and
        {\tt /WEIGHT} which weights the
        summation according to the position of the object within the box.
  \item {\tt CUT} is similar to {\tt SQUASH} but works on the current region.
\end {itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section {Graphical output}
\label {graph}

Graphical representations of LEXT data can be output to any GKS device.
The device is selected with the command 
\begin{quote}
{\tt LEXT - IMAGE 3 > DEVICE} {\it devicename}
\end{quote}

The {\tt /FORMAT} qualifier allows the user to set options for the pen
colour, font type and number of plots per page.
If devicename is {\tt NONE} then any currently opened device is closed.
If the device is required to be cleared use the command {\tt ERASE}.

A device may be closed by using the {\tt CLOSE} command or by typing {\tt
DEVICE NONE}. This is required for hardcopy devices before the output can
be sent to a printer. It is not necessary to close a device before opening
a new one. 

The first output on any device draws up axes and a title, according to the
current region. Subsequent changes to the region will not effect graphical
output until the device is erased, either explicitly with the {\tt ERASE}
command or by a new {\tt DISPLAY}. The device will not be erased by a {\tt
PLOT}. 


%%%%%%%%%%%%%%%%%%

\subsection {Image display devices}
\label {device}

Several options in LEXT make use of an interactive cursor. Due to the
number of options available during some of these sessions, it may be better
to use the device {\tt IKON\_VT}, which responds directly to keyboard
buttons, in preference to {\tt IKON}. (The latter requires the cursor
button is depressed, then a keyboard character is typed to decide on the
subsequent action to be followed.) 

If the image is to be displayed on a X-windows VAXstation, then {\tt DEVICE
XWINDOWS} also allows direct use of the keyboard. Subsequent X-windows are
called {\tt XWINDOWS2} etc. 

%%%%%%%%%%%%%%%%%%

\subsection {Displaying images}
\label {display}

The {\tt DISPLAY} command is used for images. This has several parameters and 
options. The user is required to give black and white levels for 
dynamic scaling. By default the image is scaled spatially so that both $x$
and $y$ fill the screen. This can be over-ridden by use of the {\tt /1TO1} 
option.

The routine calculates sensible default values for the black and white
levels. Since this takes some time, the option {\tt /FAST} 
can be useful where the black and white levels are known in advance.

The look-up table used in the display can be altered with {\tt LUT}, which 
offers a choice of several predetermined LUTs as well as user input.
Information about these is supplied with:
\begin{quote}
{\tt LEXT - IMAGE 2 > LUT HELP}
\end{quote}
Note that on a hard-copy device, black and white are interchanged.

\subsection {Plotting List information}
\label {plot}

Lists can also be displayed using the command {\tt PLOT}. 
PLOT has a large 
number of options, some corresponding to possible list {\tys}.
Usually in any given list the first two columns are taken as the 
cartesian coordinates.
This can be altered with the {\tt SET XCOLUMN} and {\tt SET YCOLUMN} commands.


The available plot types are:

\begin{itemize}
  \item {\tt /1TO1} for true aspect ratio.
  \item {\tt /BOXES} A BOXES list has four coordinate pairs associated with each 
        element, defining the vertices of the rectangle, the object position
        on the slit etc.
        Thus a {\tt PLOT/BOXES} will draw up those regions on the device.
        Additionally {\tt /CYCLE} will draw subsequent ones in different
        colour pens.
  \item {\tt /JOIN} draws arrows between corresponding pairs of ($x$,$y$) positions
        from two list slots. The user can further specify an expansion
        factor, by which the length of the arrow is increased, whilst the
        origin and direction remain the same. This option is useful to
        visualise the effects of transformations on an image.
  \item {\tt /CIRCLE} draws a circle of user defined centre and radius
        on an existing plot.
  \item {\tt /ELLIPSE} similarly draws an ellipse of user defined centre and
        dimensions on an existing plot.
  \item {\tt /KNOTS} uses a KNOTS list to draw horizontal 
        and vertical lines
        representing the spline fitting knots.
  \item {\tt /LINE} draws in line segments to connect successive points in
        a list.
  \item {\tt /MASK} plots a representation of a mask using information
        in the MASK list. Any coordinate of zero-weight will be be plotted
        as for a fiducial hole.
  \item {\tt /NUMBERS} prints the numbers contained in a specified column
        of the current list, at the cartesian positions 
        defined for each list entry.
  \item {\tt /SPECTRUM} draws a spectrum list.
  \item {\tt /FIBOX} for a FIBOX list.
  \item {\tt /FIELD} draws a rectangle, taking user defined limits.
  \item {\tt /FIDUCIAL} draws four crosses at the cardinal points
        a user specified distance from the origin.
  \item {\tt /ROH} draws a representation of a row-of-holes mask.
        This qualifier is only for use with {\tt /MASK}.
  \item {\tt /DIRECT} for plotting of a DRCT list, in the form
        of an outline of the slits (and fiducial holes) and
        also the zero-order position.
  \item {\tt /LIMIT} shows the limits of the field of view, as determined
        by CAMFIELD and COLFIELD.
  \item {\tt /TEXT} plots up text at a user defined position
\end {itemize}

PLOT does not clear the device and so is drawn on top of any existing
image or previous PLOT.
For interactive displays the line colour can be changed with the command 
{\tt SET PEN}.
For hard copies plots can be made on subsequent pages by ADVANCEing the 
plotting window. If {\tt ADVANCE} is used on an
interactive display the device 
is simply cleared.
(NB: the hardcopy file thus created must be sent to the appropriate 
physical device by issuing a DCL command.)


%%%%%%%%%%%%%%%%%%

\subsection {Defining a region of interest}
\label {region}

LEXT allows the user to define a current region of interest by use of
the {\tt REGION} command. Subsequently all graphics and many
other operations will only apply to this region.
Note that once a plot is displayed of a given region, then the
envelope will apply so long as the display is not erased.

REGIONs can be selected in a variety of ways, the default uses the 
graphics cursor. Another useful way of specifying the REGION is
with the {\tt /AUTO} qualifier: in list mode, this selects
the end points according to the extremal values in the current list,
whilst in image mode the full size of the image is taken.
Alternatively {\tt /FULL} provides the full image size, whichever mode
is selected.
{\tt REGION/BOX} allows the specification of a particular spectrum, 
{\tt REGION/SMALL} reduces the size a little, and there are 
several similar options listed in HELP.

%%%%%%%%%%%%%%%%%%

\subsection {Interactive examination of data}
\label {exam}

The user can interact with a displayed image or plot by use of either:

\begin {itemize}
  \item {\tt CURSOR} is used for both images and lists. 
        The values of data 
        points can be read and stored in a CLIST list slot.
        The actual position recorded by the cursor can optionally be
        modified using one of two centroiding algorithms {\tt /FIT} finds
        a local centre of mass and {\tt /GFIT} fits a 2D gaussian.
        This could be used in identifying targets, which would then have to
        be {\tt TRANSFORM}ed into a MASK list.

        If a PLOT is being examined there is the option to edit the 
        corresponding list by means of the {\tt /EDIT} qualifier.
        This is particularly useful for BOXES and MASK lists, which can
        be modified to change the size and position of the boxes in addition
        to deleting entries altogether. Both lists are required so that
        the information in each remains correlated. Care should also
        be taken with this
        routine as it works on proximity to bottom, left-hand corner of
        the box rather than simply seeing which box the cursor is currently
        in.

        The particular options, corresponding to the keyboard
        numeric buttons, are displayed on the terminal.

        The option {\tt CURSOR/FC} allows the field centre to be respecified.

  \item {\tt BROWSE} can also be used to examine either DISPLAYed images or 
        PLOTed lists.
% nrt - check in a small region.
% nrt - should the special BOXES or COEFS behaviour be an option?

        In image mode the each cursor read results in the 
        position and value of the pixel to be output. Also, if
        a BOXES list is available then the box number which the pixel
        occupies is also output, whilst, if COEFS are present, the 
        wavelength corresponding to the position is reported.

        In list mode the cursor read causes the list
        to be examined and 
        the number of the closest list element to be reported.

        In both cases the cursor position is read on each button depression,
        and a position selected outside the display area brings about the exit.
\end {itemize}




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section {Spectrum extraction and calibration}
\label {spectrum}

Once the data in the image frame has been preprocessed the multiple
spectra can be flat-fielded, extracted and calibrated.
It is only required that there 
exist a BOXES list containing the definitions of the spectra locations.
The BOXES list can be updated in accordance with the actual data using the
{\tt UPDBOXES} command.

The 1D spectra files are created using the {\tt EXTRACT}
command and the wavelength calibration of the arc images to take place via
the {\tt ARC} command.
These commands have many options and are described in detail
below.
Alternatively the following routines may be useful to perform
variations on the standard analysis:

\begin{itemize}
  \item {\tt SKYSUBTRACT} performs the sky-subtraction for each spectrum.
        It can be run in either automatic or, by use of the logical 
        argument {\tt PLOT}, interactive mode.
        The algorithm differs somewhat from that used by EXTRACT.
  \item {\tt FLUX} uses a fluxing standard contained in an FSPEC list
        to correct for the spectral response of the detector/instrument
        combination. It can be multiplied ({\tt /MUL}) or divided ({\tt /DIV}).
        The spectrum and standard are assumed to have the same dispersion
        and spectral range.
  \item {\tt SCRUNCH} transforms the data to a linear wavelength scale.
  \item {\tt BOXIMAGE} cuts out a given spectrum and puts it into a smaller
        external 2D image. This might be required
        if another package is to be used for the subsequent calibration.

        The header items from the parent image are propogated, and information
        regarding the details about the box is also recorded.
  \item {\tt HORNE} is an option to perform optimal extraction using
        the Horne (P.A.S.P., 1986) algorithm. This algorithm is particularly
        appropriate for spectra which have only small tilts of the
        object spectrum, such as those produced by LDSS-2.

        It is intended to be performed on images which have already been
        sky subtracted.
\end {itemize}

%%%%%%%%%%%%%%%%%%
\subsection{Flatfielding}
\label{flat}

In order to take out small scale variations in the sensitivity
for the dispersed image, it is necessary to flat-field the
data using a white light image.
A routine {\tt MAKEFF} exists for the purpose of generating
the necessary flat-field, which can then be divided into the data
image.

This routine works by dividing each row within a box by the marginal
distribution obtained by summing along the columns in that box. This
takes out the variation of sensitivity with wavelength but does
not account for features which are constant in wavelength for all
positions along the slit. If it is believed that genuine features of
this type exist, it will be necessary to smooth the marginal
distribution before dividing it into the data. This technique will
artificially flatten data in boxes affected by vignetting. This could
affect the flux calibration if the object is not in the centre of the
box. The original image should have uniform illumination of each slit
and a signal level high enough to avoid injecting noise into the
flattened data.

%%%%%%%%%%%%%%%%%%

\subsection {Arc subpackage}
\label {arc}

This is a separate subpackage which can be entered by the command {\tt ARC}.
It provides facilities for mapping an arc image to create
an arc table, and hence derive scrunch coefficients.

A BOXES list must be provided to give details of the positions of the 
slit locations. If an ARCL list is present, containing details of the
arc-lines, it is used; otherwise one is created and modified.

\subsubsection {ARC command interface}
\label {arcoms}

When ARC is entered, the prompt changes to:
\begin{quote}
{\tt OPTION - ARC fitting option - HE for help >}
\end{quote}
 
There is a much smaller set of commands available within ARC.
These are summarised here:

\begin {itemize}
  \item {\tt EX} - exit from the routine and return to the LEXT prompt.
  \item {\tt LA} - list arcline wavelengths in current ARCL list in \AA.
  \item {\tt LF} - For a specified spectrum, lists the lines which have been 
        individually identified with particular arc-lines. This information 
        should be contained in the current LIPOS list, in the form of pixel 
        coordinate of the line centre versus given wavelength of line.
  \item {\tt RA} - Removes a specified arc-line from the current list (ARCL),
        and also removes any fits to this arc-line which have been made, from 
        the LIPOS list. The arc-line is identified by its wavelength, in \AA,
        as contained in the appropriate entry in the ARCL list.

        This will not effect any scrunch coefficients which may have been 
        derived using this line. In order to revise these, the fitting 
        procedure must be explicitly repeated using FI or FA.
  \item {\tt AL} - Adds the user given wavelength of an arc-line to the 
        current ARCL list.
  \item {\tt CU} - Begin interactive session of identifying lines in an arc
        spectrum. The arc image should be displayed on the current graphics
        device. The options are selected by depressing keyboard keys.
        \begin{itemize}
        \item {\tt D} - displays the selected cursor position.
        \item {\tt W} - Allows the user to directly insert a wavelength into the arc-line
        (ARCL) list. This option cannot be used to directly identify a
        particular arc-line for insertion into the LIPOS list.
        \item{F} - This is the main option. With it the cursor is used to indicate the
        approximate position of the line, on the displayed image. A precise
        position for the line is derived by fitting a gaussian cross-section ridge
        within a user-defined window around the cursor hit. This fit is
        indicated graphically, and can be then accepted or rejected.
        If accepted, the user is prompted for the wavelength to associate
        with the line.
        \end{itemize}
  \item {\tt HE} - Displays brief help information on the available ARC commands.
  \item {\tt FI} - Fits a polynomial of given order to the (pixel,wavelength) 
        pairs for a specified spectrum, from the information stored in the 
        LIPOS list. The fit details are reported to the user, who is then asked 
        whether firstly to store the full information for this fit in its own 
        RESL list slot, and secondly whether to store the scrunch coefficients in
        the COEFS list slot for the field.
  \item {\tt FA} - Uses the line positions identified for a given spectrum as 
        a template, and attempts to automatically identify the same lines for 
        each spectrum in the image, and hence produce scrunch coefficients. 
        The line fitting follows the same procedure as the interactive option, 
        CU, by fitting a ridge within a given window around the predicted line 
        position.

        The scrunch coefficients are derived in the same way as for the single
        spectrum option FI, and stored in the current COEFS list slot.
        The user is required to specify a maximum value for fitting residuals
        in order to be acceptable.

        Since the information generated by this routine has not been scrutinised
        interactively, it is not used to update the current LIPOS list, nor are
        any RESL lists produced. Instead it is recorded in a FITL list.

        The progress of this routine is reported to the user and the image 
        display is also updated showing the calculated line positions. It 
        is advisable to note possible failures, so that these spectra can be 
        subsequently re-worked individually.
  \item {\tt AR} - Automatically refine the scrunch fits to each spectrum by 
        searching for fainter lines which are listed in the ARCL list, but 
        haven't been identified in the LIPOS list. This procedure is meant to 
        provide a second order improvement to the fit once an initial attempt 
        has reached the level where the positions of the faint lines can be 
        searched for with confidence.

        The procedure followed is similar to that for FA.
  \item {\tt CP} - allows setting of several parameters and criteria
        governing the fitting of arc spectral lines.
\end{itemize}

Details of standard arc-lines can be found from various sources,
for example, in files such as FIGARO\_PROG\_S:*.ARC

The wavelengths of these can be added manually to the current list
using the command {\tt AL}.

%%%%%%%%%%%%%%%%%%

\subsection {Using the Extract command}
\label {extract}

This task is used for the extraction of the multiple spectra from 
a 2D image. The spectra are output into 1D list files, not into slots.
In order to define the positions of the spectra on the image there must
exist a previously created BOXES list file.
The user should declare the box numbers they want by:
\begin{quote}
{\tt LEXT - IMAGE mode > EXTRACT 2-5 6-10 15}
\end{quote}
or, if all spectra should be processed:
\begin{quote}
{\tt LEXT - IMAGE mode > EXTRACT ALL}
\end{quote}

EXTRACT has a large number of options allowing most of the sophisticated
reduction processing to be preformed with the one command, provided
the necessary lists are present.

The default is to extract a normal sky subtracted object spectrum for
each box. The algorithm used weights the contribution of the object
rows according to a gaussian model of the profile. This helps to 
optimise the signal to noise ratio.
However the following qualifiers provide alternatives which may be 
useful for arc, night-sky or quick-look spectra:

\begin{itemize}
  \item {\tt /OBJECT} simply takes the object signal from specified rows
         with no weighting.
  \item {\tt /SKY} provides a spectrum of just the sky contribution.
  \item {\tt /WHOLE} uses all the rows within the box to obtain a combined
         object/sky spectrum
\end {itemize}

If a normal weighted extraction is to be performed then sky will be
subtracted unless the {\tt /NOSUB} qualifier is specified.
The subtraction process can be either automatic (the default) or
interactive. In the interactive case the user fits the slit profile via
the image display cursor. In the automatic case the program will provide
a graphical display of its progress by specifying {\tt /PLOT}.

It is also possible to scrunch the spectra to a linear wavelength scale
with {\tt /SCRUNCH} (requires a COEFS list), and
to flux them with {\tt /FLUX}
or {\tt /DFLUX} dependent on whether
the fluxing standard is multiplicative or
dividing
(requires a FSPEC list).

The {\tt /TILT} option can be used to account for tilt of spectral 
lines if it is large, but this is a slow process and will not usually
show any significant difference over the default method.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\appendix

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\newpage
\section{Dictionary of LEXT commands}
\label {dictionary}

\begin{center}
\begin {tabular} {|l|l|l|} \hline
Command     & Action & Section \\ \hline
\$ or DCL   & Executes DCL commands --- in batch jobs use DCL only & ~\ref{DCL}\\
$<$         & Execute commands from a LEXT procedure file. & ~\ref{procs} \\ 
ADDC        & Add a constant to a LIST or IMAGE slot entry. & ~\ref{process} \\ 
ADDI        & Add one IMAGE slot to another. & ~\ref{process} \\ 
ADVANCE     & Advance the plotting window one sub-page. & ~\ref{graph} \\
APPEND      & Append one LIST slot to the end of another. & ~\ref{lisproone} \\ 
ARC         & Enter arc-fitting/wavelength-calibration sub-package. & ~\ref{arc} \\ 
BACK        & Step backwards to the previous LIST or IMAGE slot. & ~\ref{stackops} \\ 
BOXIMAGE    & Put BOXES sub-images into small external images. & ~\ref{spectrum} \\ 
BROWSE      & Interactive graphical inspection of display or plot. & ~\ref{exam} \\ 
CADD        & Add one column of a LIST slot to another. & ~\ref{process} \\ 
CCOPY       & Copy the values in a LIST slot column to another column. & ~\ref{process} \\
CLEAN       & Remove missing values from a LIST or IMAGE slot. & ~\ref{manip} \\
CLOSE       & Shuts down a graphics device. & ~\ref{device} \\
CONTINUE    & Continue a command procedure after interruption. & ~\ref{procs} \\ 
COPY        & Copy one LIST or IMAGE slot to another. & ~\ref{stackops} \\ 
CREATE      & Create a LIST or IMAGE slot or a KNOTS or grid LIST. & ~\ref{lists} \\
CURSOR      & Use the cursor to inspect and fit plotted data. & ~\ref{exam} \\
DEVICE      & Select a graphics device. & ~\ref{device} \\
DIRECTORY   & List the status and contents of LIST or IMAGE slots. & ~\ref{stackops} \\ 
DISPLAY     & Display the current IMAGE on a plotting device. & ~\ref{display} \\
DISTORT     & Apply a bicubic spline distortion to a LIST or IMAGE slot. & ~\ref{distort} \\ 
DIVI        & Divide one IMAGE slot by another. & ~\ref{process} \\ 
EDIT        & Allow current LIST slot to be edited. & ~\ref{lisproone} \\ 
END         & Exit the LEXT package. & ~\ref{ending} \\
EMPTY       & Empty a LIST or IMAGE slot. & ~\ref{stackops} \\
ERASE       & Erase the screen of the current plotting device. & ~\ref{graph} \\
EVALUATE    & Fill IMAGE slots with the X and Y shifts from a transform. & ~\ref{distort} \\
EXIT        & Exit the LEXT package. & ~\ref{interface} \\ 
EXTRACT     & Spectrum extraction function. Many options. & ~\ref{extract} \\
% FLIP        & Flip current IMAGE up/down/sideways/both. & ~\ref{} \\ 
FIDUCIAL    & Centroids fiducial holes. & ~\ref{targets} \\
FLUX        & Flux the spectrum in the current LIST slot. & ~\ref{spectrum} \\
FPRINT      & Create formatted list from POS and MASK lists. & ~\ref{io} \\
FREE        & Deprotect current LIST or IMAGE slot. & ~\ref{prot} \\ 
GROW        & Expand BOXES/MASK regions to optimally fill detector. & ~\ref{masks} \\ 
HELP        & Enter HELP facility. & ~\ref{interface} \\ 
HORNE       & Performs optimal extraction via the Horne algorithm. & ~\ref{spectrum} \\
IMAGE       & Select IMAGE mode. & ~\ref{mode} \\ 
INIT        & Initialise LEXT during execution of startup procedure. & ~\ref{procs} \\ 
INVALIDATE  & Set parts of current LIST or IMAGE slot to invalid flag. & ~\ref{manip} \\
\hline
\end {tabular}
\newpage
\begin {tabular} {|l|l|l|} \hline
Command     & Action & Section \\ \hline
KILL        & Exit the LEXT package without checking for SAVEd slots. & ~\ref{interface} \\
LFIT        & Fit a linear transformation to a pair of LIST slots. & ~\ref{distort} \\ 
LIST        & Select LIST mode. & ~\ref{mode} \\ 
MAKEFF      & Utility to create flat-field images. & ~\ref{flat} \\
MAP         & Search IMAGE for peaks and store positions in LIST slot. & ~\ref{improtwo} \\ 
MATCH       & Match up the order of two LIST entries by ($x$,$y$) position. & ~\ref{lisproone} \\ 
MULC        & Multiply current LIST or IMAGE slot by a constant. & ~\ref{process} \\ 
MULI        & Multiply one IMAGE slot by another. & ~\ref{improone} \\ 
NEXT        & Step forwards to the next LIST or IMAGE slot. & ~\ref{stackops} \\ 
OK          & Check whether to continue or abort a procedure. & ~\ref{procs} \\ 
PLOT        & Plot a LIST slot. Many options. & ~\ref{plot} \\
POLY        & Fit a polynomial to the current LIST slot. & ~\ref{lisproone} \\ 
PREBOX      & Predict BOXES positions on detector from MASK details. & ~\ref{masks} \\
PREDIRECT   & Predict slit positions in a direct mask image. & ~\ref{masks} \\
PROC        & Prompt for commands to be stored in a procedure file. & ~\ref{procs} \\ 
PROTECT     & Protect current LIST or IMAGE slot. & ~\ref{prot} \\ 
QUIT        & Exit the LEXT package. & ~\ref{ending} \\
READ        & Read an external file into a LIST or IMAGE slot. & ~\ref{io} \\  
REGION      & Define the current region. & ~\ref{region} \\ 
RELABEL     & Change the {\la} on a LIST or IMAGE slot. & ~\ref{status} \\ 
REPLACE     & Change values in the current LIST or IMAGE slot by hand. & ~\ref{manip} \\ 
% RESTORE     & Read internal variable values from a *.SET file. & ~\ref{internals} \\
RETYPE      & Change the {\ty} of a LIST or IMAGE slot. & ~\ref{status} \\ 
RIDGE       & Map positions of peaks in X or Y in current IMAGE region. & ~\ref{improtwo} \\ 
SAVE        & Flag the current slot to be written out before exit. & ~\ref{prot} \\ 
SAVESET     & Save the current internal parameter settings. & ~\ref{internals} \\
SCRUNCH     & (Re-)Scrunches a spectrum to a linear wavelength scale. & ~\ref{spectrum} \\
SET         & Set the value of an internal variable. & ~\ref{internals} \\ 
SFIT        & Fit a bicubic spline to a pair of LIST slots. & ~\ref{distort} \\
SHOW        & Display the values of internal variables. & ~\ref{show} \\ 
SKYSUBTRACT & Perform 2D sky-subtraction on current IMAGE. & ~\ref{spectrum} \\
SMOOTH      & Apply smoothing to current IMAGE region or LIST column. & ~\ref{improone} \\ 
SQUASH      & Compress selected BOX in current IMAGE slot in X or Y. & ~\ref{improone} \\ 
STATS       & Obtain statistics on current LIST or IMAGE slot. & ~\ref{manip} \\ 
STOP        & Exit the LEXT package. & ~\ref{ending} \\
STORE       & Write current internal variable values to a *.SET file. & ~\ref{internals} \\
SUBI        & Subtract one IMAGE slot from another. & ~\ref{process} \\ 
SUBSET      & Squash or stretch to/from subset of IMAGE slot. & ~\ref{improtwo} \\ 
SWAP        & Swap two columns in the current LIST slot. & ~\ref{stackops} \\ 
TRANSFORM   & Transform LIST slot coordinates between mask and detector. & ~\ref{distort} \\
TYPE        & Type out a subset of the current LIST or IMAGE slot. & ~\ref{manip} \\
USE         & Select the current LIST or IMAGE slot. & ~\ref{stackops} \\
WRITE       & Write current LIST or IMAGE slot to an external file. & ~\ref{io} \\ \hline
\end {tabular}
\end {center}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\newpage
\section {Standard types of List}
\label {listypes}

As mentioned previously LEXT has a variety of uses for list data.
Different functions may operate with only certain lists so in order to
differentiate between them lists are designated one of the following
{\tys}: 

% nrt - should fill in more details here. (eg. more list types)
\begin {itemize}
  \item BOXES defines rectangular regions of the image which are used
         to designate the positions and extent of each of the spectra
         within the 2D image. (All in pixels).

        (X-start, Y-start, X-end, Y-end, ID, Y-pos object, Y-extent obj,
         X-pos zero-order)
  \item KNOTS defines the fiducial points for the spline.

        (X-value, Y-value)
  \item MASK defines the mask details.

        (ID, Obj X (mm), Obj Y (mm), Slitlen, Slitoffset, Obj app RA 
        (rad), Obj app dec (rad), Weight)

        Note that zero weight conventionally designates a Wood's hole.
  \item POS holds object positions and magnitudes.
        This is only for user information, rather than processing.
        It has no official column headers, but, if it is to be
        output by {\tt FPRINT} then the following are assumed:

        (CosX, CosY, ID, B, R, B-R )
  \item ARCL holds standard arc-line wavelengths.

        (Lambda (\AA))
  \item CLIST object positions in pixel units. May also be any list of points.

        (X-pos, Y-pos, Height, X-sig, Y-sig, Background )
  \item MLIST object positions in mm units at the focal plane.

        (As CLIST)
  \item FIBOX defines the extent and positions of rectangular regions 
        for use with FIT. (All in pixels).

        (Xcen (pix), Ycen (pix), X-extent, Y-extent)
  \item LIPOS stores line positions identified for each arc spectrum.

        (X (pix), Lambda (\AA), Box num)
  \item COEFS contains linearity correction for SCRUNCH, for each arc
        spectrum.

        (Npt fitted, Coef $X^0$, Coef $X^1$, Coef $X^2$, Coef $X^3$,
         Coef $X^4$, Coef $X^5$, Coef $L^0$)
  \item RESL contains the full details of the fit to the arc lines
        in a given spectrum.
  \item YPROF profile of pixel values in Y direction.

        (Y-val, Summed int)
  \item XPROF profile of pixel values in X direction.

        (X-pix, Flux, Lambda(\AA))
  \item OPROF profile of object spectrum, not scrunched.

        (X-pix, Flux, Lambda(\AA))
  \item WPROF profile of weighted spectrum, not scrunched.

        (X-pix, Flux, Lambda(\AA))
  \item SPROF profile of sky spectrum, not scrunched.

        (X-pix, Flux, Lambda(\AA))
  \item SPEC contains a 1D spectrum as a function of wavelength.

        (Lambda(\AA), Flux)
  \item OSPEC scrunched object spectrum.

        (Lambda(\AA), Flux)
  \item WSPEC scrunched weighted spectrum.

        (Lambda(\AA), Flux)
  \item SSPEC scrunched sky spectrum.

        (Lambda(\AA), Flux)
  \item FSPEC contains fluxing standard.

        (Lambda(\AA), Response)
  \item DRCT contains a boxes {\ty} file, created by PREDIRECT for a 
        direct image.

  \item RESL keeps details of the scrunch fit to the arc lines for
        an individual box.

  \item FITL list contains details from auto-refine during automatic arc
        fitting.
 
  \item DLIST distorted list

\end {itemize}

The designated {\ty} of a list can be modified at any time by means of 
the {\tt RETYPE} command.
This is useful to change the semantic interpretation of the list data.
LEXT will even allow an invented {\ty}, which may, of course, make
sense if the user wants to store any unusual information, but could
not be interpreted automatically by LEXT.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\newpage
\section{Procedure FIND\_TWEAK}
\label{app-proc}

The following listing of the procedure FIND\_TWEAK, used for target 
acqusition, serves as an example of how to write LEXT procedures.

\begin{verbatim}
#************************#
# Authors - Keith Taylor #
#           Nial Tanvir  #
#                        #
#************************#
set echo
#*******************************************************************#
#* FIND_TWEAK - operates on an acquisition image (ie. a direct image#
#*           of the target through the mask)  and its corresponding #
#*           catalogue file which it uses to determine the shift    #
#*           between the stars and their respective holes.          #
#*           It then predicts the offsets to feed into the          #
#*           WHT's TCS TWEAK proceedure.                            #
#*******************************************************************#
#*******************************************************************#
#*                                                                  #
#*  Calling Sequence: FIND_TWEAK p1 [p2 p3]                         #
#*       where:   p1 = number of fiducial holes  [compulsory]       #
#*                p2 = Name of acquisition image [optional]         #
#*                p3 = Name of catalogue file    [optional]         #
#*                                                                  #
#*******************************************************************#
ok
#
#  Have you selected a display device ?
#
:query
:goto kt1
dev
:label kt1
image
#
#  Have you already read in an acquisition image ?
#
:query
:goto kt2
#
#  Read in the image.
#         
image
read/3 $2
:goto kt3
:label kt2
image
dir
#
#  Are you pointing at the relevant image ?
#
:query
:goto kt4
use
:label kt4
:label kt3
list
dir
#
#  Have you already a catalogue file ?
#          ... it has to be in slot 1 with all other slots empty.
#
:query
:goto kt5
#
#  Read in the catalogue file and predict rectangular regions (in pixels)
#  surrounding slits and fiducial holes.
#
#  NB: all list slots will be emptied. If any are required you should
#      answer `n' here, write them out to disk, and then type `continue'.
#
ok
list
empty/all y
read/cat $3 $3
:label kt5
list
clean 8
use 1
free
empty
copy 2 1
use 2
free
empty
use 1
create/mask 21 21
#**************************************************************************
#          Finding the geometric centres of the fiducial holes.
#**************************************************************************
fiducial
clean 1
match 4 2 matched_fibox
use 2
rety fbx
use 4
#**************************************************************************
#    Now finding the centroids of the fiducial stars within the holes.
#**************************************************************************
fit/fid 2
#**************************************************************************
#  Each fiducial hole image will now be displayed with the calculated centre
#                   of hole and star for inspection.
#
# Note that, you will have an opportunity later to interactively edit out
# any bad holes/stars. For now, only leave at the exit points if you
# think that you will be able to perform a fix outside this procedure.
#
#**************************************************************************
:loop $1
reg/fibox $$$
disp/1/fast
use 4
set pen 3
set marker 4
plot
use 6
set pen 4
set marker 5
plot
ok
:back
#**************************************************************************
#
#  The full image will now be displayed with the vectors between the 
#  calculated positions of the stars and the centres of the holes. For 
#  clarity the lengths of the vectors are scaled up by a factor of 50(!).
#
#**************************************************************************
ok
region/full
er
set pen 2
plot/join/1 6 4 50
set pen 4
plot/num 0
#**************************************************************************
#
#  Now is your opportunity to reject any stars/holes which you think should
#  not be included in the fit.
#
#  Use the cursor to edit out bad vectors (keep at least 3 !)
#  The cursor should be placed at the base of the vector.
#**************************************************************************
free
cursor/edit
lfit/noscale/field 6 4
#**************************************************************************
#  OK - you got it, Bud - now be so good as to tell your friendly T.O.
#                         to perform the TWEAK.
#**************************************************************************
set noecho
exit
\end{verbatim}

\newpage

\section{Summary of main LEXT internal parameters}
\label{app-set}

These LEXT parameters are essential for mask design.

\begin{itemize}
\item X\_FORMAT and Y\_FORMAT -- extent of CCD array
\item XPIX and YPIX -- pixel size ($\mu$m)                            
\item SCALE -- Image scale at mask (arcsec/mm)
\item FRED -- focal reduction factor between telescope and camera
\item SLITWIDTH -- slit width (arcsec; only affects the plotting in LEXT)
\item FIDUCDIAM -- diameter of fiducial holes (arcsec)
\item MINSLITLEN and MAXSLITLEN -- minimum and maximum slit widths (arcsec)
\item MINYSEP -- minimum distance between adjacent slits (arcsec)
\item MINYMARGIN -- minimum distance between an object and the slit ends (arcsec)
\item OBJECTEXTENT -- default extent of the targets (arcsec)
\item DISPERSION -- the dispersion at the detector (\AA/mm)
\item LAMMIN and LAMMAX -- the minimum and maximum wavelengths considered (\AA)
\item LAMZERO -- the wavelength of zero order (\AA\ ;  normally zero)
\item LAMBLAZE -- the undeviated wavelength (\AA\ ; usually close to blaze)
\end{itemize}

\begin{figure}[htbp]
\hrule
\begin{verbatim}
 # Parameter file for LDSS-2 with medium dispersion grism and Tektronix 1024 CCD
 set XPIX               24
 set YPIX               24 
 set X_FORMAT           1024
 set Y_FORMAT           1024
 set DISPERSION         220
 set FRED               5.4717
 set SCALE              4.50836
 set LAMBLAZE           5725
 set LAMMIN             3000
 set LAMMAX             8000
 set LAMZERO            0
 set MINSLITLEN         10.0
 set MINYSEP            1.0
 set MINYMARGIN         5.0
 set MAXSLITLEN         60.0
 set OBJECTEXTENT       6.0
 set FIDUCDIAM          10.0
 set SLITWIDTH          1.5
 set COLFIELD           11.5
 set CAMFIELD           33.9
 set DRZ                2.5E-04
 set LATOBS             0.50197
\end{verbatim}
\hrule
\caption{An example of a file containing statements to set up internal 
parameters in LEXT}.
\label{fig-set}
\end{figure}


\newpage
\section{Catalogue format}
\label{app-cat}
Catalogue files are the preferred medium for reading and writing
high-precision mask coordinates by LEXT.  They are read into LEXT with
the READ/CAT command and written with WRITE/CAT. They are text files
written in a free format using common astronomical conventions and are
thus easily generated from coordinate lists. Their default file type is
.CAT, and they must have a maximum record length of 132 characters.  A 
catalogue written with WRITE/CAT can later be read back into LEXT with 
READ/CAT.

The lines in the file are either interpreted as containing keyword
values, object coordinates or a comment. Keywords are valid for the
whole file. Coordinate and keyword lines can be mixed higgedly piggedly
in any manner throughout the file.  However, for readability sake it is
best to segregate the keyword lines to either the top or bottom of the
file. Keyword and coordinate lines are distinguished by whether
non-numeric characters are present.  Coordinate lines must only contain
numerals, wild card character ``*'', and optional comments at the end. If
anything other than the characters ``0123456789+-.ED*! '' are present, the
line is interpreted as being a keyword line. Characters to the right of
an exclamation mark (!) are interpreted as a comment and are ignored.
Lines that READ/CAT can not interpret are also ignored. 

\subsection{Coordinate entries}

The format for a coordinate line is
\begin{quote}
$<$id$>$ $<$RA$>$ $<$Dec$>$ [Wt] [SL] [Offset] [X] [Y]
\end{quote}
The fields are:
\begin{description}

\item{\bf $<$id$>$}      Identification number of object.
\item{\bf $<$RA$>$}      Right Ascension of object. RA is in hours of time, and should 
          be a sexagesimal string, that is standard hours minutes seconds 
          (HH MM SS.SSS) format, although formats such as HH MM.MMMMM, or 
          even HH.HHHH are also accepted.
\item{\bf $<$Dec$>$}     Declination of object.  This is in degrees and should also be 
          in sexagesimal format (+--DD MM SS.SS), although formats such as 
          +--DD MM.MMMMM, or +--DD.DDDDDD are also acceptable.  The sign 
          of the declination (+--) is optional for northern objects but 
          mandatory for southern objects.
\item{\bf [Wt]}      Weight for growing slits.  Larger weights mean slits grow 
          faster.  Wt = 0.0 is reserved for fiducial stars used for 
          aligning the mask.  A centred hole is placed at the mask 
          position of such objects, while slits are used for other 
          (WT $>$ 0) objects.  Negative weights should not be used, 
          except for WT = MISVAL = -32767, which marks a {\it deleted}
          object.
\item{\bf [Sl]}      The slit length (or fiducial hole diameter).  The default 
          units are arcsecs, although this can be changed with the MMUNit 
          keyword.
\item{\bf [Offset]}  The Y coordinate difference between the slit centre and object 
          position: Offset = Ycen - Yobj.  The slits are drawn 
          parallel to the Y axis, and therefore they have the same X 
          coordinate as the object.  The default units are arcsecs, 
          although this can be changed with the MMUNit keyword.
\item{\bf [X]}       The X coordinate of the object on the mask in mm.  
\item{\bf [Y]}       The Y coordinate of the object on the mask in mm.

\end{description}

The fields in angle brackets ($<$$>$) are required, while those in square
brackets ([]) are optional.  Fields are separated by one or more spaces.
Defaults are assumed for blank fields, and were denoted by a word
starting with ``*".  X and Y are written with a WRITE/CAT but are ignored
by READ/CAT which recalculates them from the positions and field centre
parameters. 

\subsection{Keyword entries}

The keyword lines are of the format

$<$keyword$>$ $<$value$>$

and the currently recognized keywords are 

\begin{description}

\item{\bf CENtre}   * The Right Ascension and declination of the field centre in 
           sexagesimal format (as above).  The coordinates must be in the same 
           equinox as the coordinate list.
\item{\bf EQuinox}  * The equinox of the coordinate system used, in years.  This 
           MUST NOT be prefixed by B or J (eg neither B1950 nor J2000 is 
           understood; use 1950 and 2000 instead).
\item{\bf EPoch}    * The epoch of observation, in years e.g. 1992.85.
\item{\bf PA}         The APPARENT PLACE position angle of the mask in degrees measured 
           from north towards the east.  This is equal to the positional 
           angle of a slit at the field centre.  However, since all slits 
           are parallel to the Y axis and sky coordinates are non-cartesian, 
           there will be some rotation of position angles away from the field 
           centre.  Default = 0.0 (ie North-South slits).
\item{\bf SLObj}      The slit length for objects with a blank slit length field.
           Default is set by the LEXT global {\it MINSLITLEN} in arcsec.
\item{\bf SLFid}      The diameter of fiducial star holes which have a blank slit 
           length field.  Default is set by the LEXT global {\it FIDUCDIAM} in
           arcsecs.
\item{\bf WDEF}       The slit growing weight for objects with a blank weight 
           field.  Default is 1.0
\item{\bf OFFDefault} The offset of the slit centre from the object position along 
           the Y axis, for objects with a blank offset field.  Default 
           is 0.0. 
\item{\bf MMUNit}     The scale in mm/units at the focal plane for slit lengths, 
           and offsets used in this file.  This includes the values for 
           SLO, SLF, and OFFD.  Default is the mm/arcsec scale of the 
           telescope as given by the {\it reciprocal} of the LEXT global 
           {\it SCALE}, i.e. MMUNIT~=~1/{\it SCALE}. If {\it SCALE} is not 
           specified the mm/arcsec scale for the AAT Cassegrain focus is used.

\end{description}

Only the capitalized letters are required for the keywords (although
they do not have to be capitalized in the file). Extra letters beyond
those capitalized above are not considered, so that ``SLOW\_and\_easy",
``Equus\_the\_horse", and ``epping\_boys\_high" will be interpreted as the
``SLObj", ``EQuinox", and ``EPoch" keywords respectively. Keyword
lines marked with a * are required.  If they are not in the file values
are prompted for when the file is read by READ/CAT. 

\subsection{Positional accuracy.}

The coordinates used to design a mask should be of the highest
precision.  Once a mask is made there is no way to adjust the position
of the slits.  Even errors of 0.5 arcsec can make a significant difference in
S/N, considering that most masks have a slit width of 1.5 arcsec and are made
for the study of faint objects.  Therefore it is recommended that the
RELATIVE positional accuracy of the coordinates is kept to a few tenths
of an arcsec. The accuracy of the LEXT software is limited by its
predominantly REAL*4 implementation, giving positions accurate to about
0.01 arcsec. 

It is not that important to beat down the zero-point errors to the FK4
or FK5 system.  The accuracy of the field centre position is also not
that important, at least during the design of the mask.  It can be
tweaked during the design, and any offsets resulting from the
manufacture can be measured and at the telescope, and the field centre
adjusted. However, it is very important that the fiducial stars'
positions are measured at the same time as the program objects.  These
are used to position the telescope.  If they are not precisely on the
same coordinate system as the program objects it is quite likely that
objects will not fall on the slits. 

\subsection{Example}

Below is an example catalogue for LDSS-1, first in a format acceptable by
READ/CAT, and then reformatted by WRITE/CAT.
An example of the output from WRITE/MAN is also shown. 



{\bf Input}

\hrule
\begin{verbatim}
 EPOCH 1990.8      ! Observing October 1990.
 EQUINOX 1950.0    ! 1950 coordinates
 CEN 1 31 20.175 - 5 47 10.43
 PA 140.0
 188    1 31 29.588 - 5 46 40.71   0  ! Fiducial star
 394    1 31  7.060 - 5 44  0.33   0  ! Fiducial star
 288    1 31 25.162 - 5 50  9.01   0  ! Fiducial star
 451    1 31 28.955 - 5 50  4.64      ! The rest are galaxies
 461    1 31 28.391 - 5 49  7.67   
 242    1 31 27.919 - 5 48 49.33   
 240    1 31 27.775 - 5 48 31.14   
 157    1 31 25.472 - 5 48 34.24   
 98     1 31 24.768 - 5 48 18.79   
 164    1 31 21.048 - 5 48 48.15   
 94     1 31 21.7   - 5 48  0.6    
 1      1 31 20.175 - 5 47 10.43   
 22     1 31 20.030 - 5 47 34.73   * 8.0 ! This slit starts 8" long
 107    1 31 20.592 - 5 47 47.64         ! The rest take the default
 42     1 31 19.974 - 5 46 34.23   
 49     1 31 17.191 - 5 46 47.75   
 217    1 31 20.421 - 5 45 34.75   
 144    1 31 12.700 - 5 46 28.41   
 207    1 31 18.560 - 5 44 56.73   
 225    1 31 12.461 - 5 45 34.99   
 336    1 31 16.783 - 5 44  9.68   
 337    1 31 14.803 - 5 44 10.38   
 389    1 31  8.603 - 5 45  0.36   
 339    1 31 14.400 - 5 43 32.15   
 544    1 31 10.886 - 5 43 38.37   
\end{verbatim}
\hrule

{\bf Output from WRITE/CAT }

\hrule
\begin{verbatim}
 EQUINOX  1950         
 EPOCH  1990.8       
 CENTRE    1 31 20.176  - 5 47 10.43
 PA  140          
 MMUNIT  0.1492537    
!id        R.A.           Dec.      Wt.    Length    Offset     X(mm)     Y(mm)
 188    1 31 29.588  - 5 46 40.71   0      10.000     0.000    18.905    10.113
 394    1 31  7.060  - 5 44  0.33   0      10.000     0.000    -4.082   -40.537
 288    1 31 25.162  - 5 50  9.01   0      10.000     0.000    -8.670    27.556
 451    1 31 28.955  - 5 50  4.64   1      15.000     0.000    -1.782    32.502
 461    1 31 28.391  - 5 49  7.67   1      15.000     0.000     2.734    25.184
 242    1 31 27.919  - 5 48 49.33   1      15.000     0.000     3.692    22.411
 240    1 31 27.775  - 5 48 31.14   1      15.000     0.000     5.196    20.126
 157    1 31 25.473  - 5 48 34.24   1      15.000     0.000     0.972    17.176
 98     1 31 24.768  - 5 48 18.79   1      15.000     0.000     1.257    14.400
 164    1 31 21.048  - 5 48 48.15   1      15.000     0.000    -7.908    12.416
 94     1 31 21.700  - 5 48  0.60   1      15.000     0.000    -2.225     7.919
 1      1 31 20.176  - 5 47 10.43   1      15.000     0.000     0.000     0.000
 22     1 31 20.030  - 5 47 34.73   1       8.000     0.000    -2.584     2.568
 107    1 31 20.592  - 5 47 47.64   1      15.000     0.000    -2.867     4.848
 42     1 31 19.974  - 5 46 34.23   1      15.000     0.000     3.138    -4.424
 49     1 31 17.191  - 5 46 47.75   1      15.000     0.000    -2.907    -6.873
 217    1 31 20.421  - 5 45 34.75   1      15.000     0.000     9.619   -10.577
 144    1 31 12.700  - 5 46 28.41   1      15.000     0.000    -8.705   -15.527
 207    1 31 18.560  - 5 44 56.73   1      15.000     0.000    10.102   -17.591
 225    1 31 12.461  - 5 45 34.99   1      15.000     0.000    -3.975   -21.973
 336    1 31 16.783  - 5 44  9.68   1      15.000     0.000    11.597   -25.516
 337    1 31 14.803  - 5 44 10.38   1      15.000     0.000     8.154   -28.278
 389    1 31  8.603  - 5 45  0.36   1      15.000     0.000    -7.223   -31.465
 339    1 31 14.400  - 5 43 32.15   1      15.000     0.000    11.143   -33.223
 544    1 31 10.887  - 5 43 38.37   1      15.000     0.000     4.554   -37.555
\end{verbatim}
\hrule

\newpage

\begin{figure}[htbp]

{\bf Output from WRITE/MAN } 
\hrule
\begin{verbatim}
 :FIELD 3c435a_l1  

  Label   - ASTR:3C435A
  Equinox - 1950         
  Epoch   - 1992.6       
  Centre  -  21 26 38.992    7 20 10.00
  PA      - -7           

 :SLITS 
  13
   56.89, -79.89,  17.62
   34.94, -52.93,   9.37
  -24.73, -42.00,  10.52
   20.67, -29.19,  13.08
  -24.42,  -5.98,  11.72
   44.24,  17.96,   8.31
  -13.34,  28.05,   9.93
   71.38,  50.85,  10.02
   30.84,  60.28,   7.11
   76.50,  71.15,  14.39
  -61.74,   6.66,  12.17
   35.19, -17.19,   9.18
   22.76,  39.42,  10.78
 
 :STARS 
   4
  102.25, -63.58,   5.00
   -9.05, -66.17,   5.00
   71.16, 110.17,   5.00
  -87.94,  84.27,   5.00
 
 :END
\end{verbatim}
\hrule
\caption{An example of a file containing mask manufacturing instructions}
\label{fig-mfr}
\end{figure}

\newpage
\section{Wavelength maps}
\label{app-wavelength}

For each grism, data for the spectrum of a CuAr arc lamp is given
in two ways: (1) a plot of a sample spectrum with wavelengths marked
(Figs~\ref{fig-w-low}-\ref{fig-w-high}) and
(2) a table showing the results of a sample wavelength-position fit.
(Tables~\ref{tab-w-low}-\ref{tab-w-high}). The actual relationship between
wavelength and position will depend on the position of the slit.

\begin{figure}[htbp]
\vspace{230mm}
\caption{Extracted spectrum of CuAr with the low dispersion grism ({\it LOW})}
\label{fig-w-low}
\end{figure}
\begin{table}[htbp]
\caption{Sample wavelength calibration for CuAr with the low dispersion grism 
({\it LOW})}
\label{tab-w-low}
\hrule
\begin{verbatim}

      Channel   Wavelength   Calculated  Discrepancy  Line#

     162.3267    9784.5029    9784.7031       0.2002      1    
     173.7100    9657.7861    9657.5723      -0.2139      2    
     212.5117    9224.4990    9224.3428      -0.1563      3    
     221.5908    9122.9668    9123.0479       0.0811      4    
     262.4153    8667.9443    8668.1611       0.2168      5    
     275.6128    8521.4219    8521.3604      -0.0615      6    
     298.7408    8264.5234    8264.4424      -0.0811      7    
     327.2691    7948.1758    7948.1890       0.0132      8    
     347.5340    7723.9800    7724.0107       0.0308      9    
     355.5787    7635.1060    7635.1318       0.0259     10    
     378.3795    7383.9810    7383.5962      -0.3848     11    
     388.4259    7272.9360    7272.9487       0.0127     12    
     399.8812    7147.0420    7146.9277      -0.1143     13    
     407.1342    7067.2178    7067.2202       0.0024     14    
     416.4084    6965.4302    6965.3970      -0.0332     15    
     424.8877    6871.2891    6872.4009       1.1118     16    
     435.7045    6752.8340    6753.9146       1.0806     17    
     442.8033    6677.2822    6676.2485      -1.0337     18    
     466.6873    6416.3071    6415.5376      -0.7695     19    
     513.1519    5912.0850    5911.5103      -0.5747     20    
     551.8049    5495.8740    5496.4468       0.5728     21    
     597.0931    5017.1631    5017.0620      -0.1011     22    
     602.0119    4965.0801    4965.5645       0.4844     23    
     631.6654    4657.9009    4658.0029       0.1021     24    
     669.3045    4277.5278    4276.2588      -1.2690     25    
     676.8939    4199.6299    4200.6904       1.0605     26    
     690.0090    4072.1101    4071.3748      -0.7354     27    
     702.6833    3947.5300    3948.0637       0.5337     28    

 RMS error:       0.56, Line width used:  0.80

 Order of fit:   5

 0.8307935577354688D-11 -0.1340119590698429D-07 0.9081933402004803D-05
-0.2736789302840305D-02 -0.1079666108289552D+02 0.1157892611228203D+05
\end{verbatim}
\hrule
\end{table}

\begin{figure}[htbp]
\vspace{230mm}
\caption{Extracted spectrum of CuAr with the blue medium dispersion grism 
({\it MED/BLUE})}
\label{fig-w-medb}
\end{figure}
\begin{table}[htbp]
\caption{Sample wavelength calibration for CuAr with the blue medium 
dispersion grism ({\it MED/BLUE})}
\label{tab-w-medb}
\hrule
%   33 lines identified from DISK$TEMP:[GDS]43367_XS
\begin{verbatim}

      Channel   Wavelength   Calculated  Discrepancy  Line#

      55.8706    8264.5234    8264.7666       0.2432      1    
     114.5345    7948.1758    7948.0605      -0.1152      2    
     156.2538    7723.9800    7723.8359      -0.1440      3    
     172.8345    7635.1060    7634.9463      -0.1597      4    
     219.8312    7383.9810    7383.6890      -0.2920      5    
     240.6217    7272.9360    7272.8672      -0.0688      6    
     264.2592    7147.0420    7147.1216       0.0796      7    
     279.2982    7067.2178    7067.2607       0.0430      8    
     298.5115    6965.4302    6965.3984      -0.0317      9    
     316.2255    6871.2891    6871.6548       0.3657     10    
     338.5972    6752.8340    6753.5020       0.6680     11    
     353.1441    6677.2822    6676.8237      -0.4585     12    
     366.8350    6604.8530    6604.7695      -0.0835     13    
     402.7394    6416.3071    6416.3447       0.0376     14    
     408.7843    6384.7168    6384.7012      -0.0156     15    
     435.7682    6243.1201    6243.7461       0.6260     16    
     449.6925    6172.0298    6171.2085      -0.8213     17    
     499.5909    5912.0850    5912.4678       0.3828     18    
     533.0875    5739.5200    5739.9277       0.4077     19    
     559.1616    5606.7329    5606.3267      -0.4063     20    
     580.6898    5495.8740    5496.5220       0.6479     21    
     642.0282    5187.7461    5186.4160      -1.3301     22    
     667.0335    5062.0371    5061.2866      -0.7505     23    
     686.2102    4965.0801    4965.8794       0.7993     24    
     718.6735    4806.0210    4805.5430      -0.4780     25    
     726.9457    4764.8652    4764.9346       0.0693     26    
     772.1011    4545.0518    4545.1787       0.1270     27    
     779.0596    4510.7329    4511.6162       0.8833     28    
     844.7731    4199.6299    4199.0405      -0.5894     29    
     865.0320    4103.9121    4104.3940       0.4819     30    
     899.0550    3947.5300    3947.4390      -0.0911     31    
     930.5639    3803.1721    3804.4602       1.2881     32    
     939.5880    3765.2700    3763.9561      -1.3140     33    

 RMS error:       0.58, Line width used:  1.00

 Order of fit:   4

 0.2919603424406206D-09 -0.2026285267407393D-06 0.2842190413556393D-03
-0.5443302136844694D+01  0.8568032054526452D+04
\end{verbatim}
\hrule
\end{table}

\begin{figure}[htbp]
\vspace{230mm}
\caption{Extracted spectrum of CuAr with the red medium dispersion grism 
({\it MED/RED})}
\label{fig-w-medr}
\end{figure}
\begin{table}[htbp]
\caption{Sample wavelength calibration for CuAr with the red medium 
dispersion grism ({\it MED/RED})}
\label{tab-w-medr}
\hrule
%   30 lines identified from DISK$TEMP:[GDS]43537_XS
\begin{verbatim}

      Channel   Wavelength   Calculated  Discrepancy  Line#

      57.3152    8264.5234    8264.5293       0.0059      1    
     115.9556    7948.1758    7948.1221      -0.0537      2    
     157.6526    7723.9800    7724.0425       0.0625      3    
     174.2240    7635.1060    7635.1948       0.0889      4    
     221.2025    7383.9810    7383.8247      -0.1563      5    
     241.9763    7272.9360    7272.9336      -0.0024      6    
     265.6038    7147.0420    7147.0601       0.0181      7    
     280.6354    7067.2178    7067.1396      -0.0781      8    
     299.8402    6965.4302    6965.2285      -0.2017      9    
     317.5393    6871.2891    6871.5107       0.2217     10    
     339.8658    6752.8340    6753.5698       0.7358     11    
     354.4210    6677.2822    6676.8462      -0.4360     12    
     368.1093    6604.8530    6604.8052      -0.0479     13    
     404.0711    6416.3071    6416.0439      -0.2632     14    
     410.0630    6384.7168    6384.6621      -0.0547     15    
     437.0343    6243.1201    6243.6538       0.5337     16    
     450.9136    6172.0298    6171.2607      -0.7690     17    
     500.7675    5912.0850    5912.3545       0.2695     18    
     534.0324    5739.5200    5740.8037       1.2837     19    
     560.5043    5606.7329    5605.1128      -1.6201     20    
     581.8288    5495.8740    5496.3823       0.5083     21    
     643.0414    5187.7461    5187.1123      -0.6338     22    
     668.0462    5062.0371    5061.9233      -0.1138     23    
     687.1658    4965.0801    4966.6396       1.5596     24    
     719.6962    4806.0210    4805.5112      -0.5098     25    
     728.0645    4764.8652    4764.3008      -0.5645     26    
     773.0864    4545.0518    4544.8589      -0.1929     27    
     780.0766    4510.7329    4511.1958       0.4629     28    
     845.6921    4199.6299    4199.5474      -0.0825     29    
     865.5753    4103.9121    4103.9438       0.0317     30    

 RMS error:       0.58, Line width used:  1.50

 Order of fit:  10

-0.9424988456191865D-24  0.4067576866842583D-20 -0.7525524268956207D-17
 0.7808671003325572D-14 -0.4993849800134690D-11  0.2038715667084528D-08
-0.5326183519054469D-06  0.8706836804261911D-04 -0.8242856089165049D-02
-0.4995482148387141D+01  0.8566179584915310D+04
\end{verbatim}
\hrule
\end{table}

\begin{figure}[htbp]
\vspace{230mm}
\caption{Extracted spectrum of CuAr with the high dispersion grism 
({\it MED/BLUE})}
\label{fig-w-high}
\end{figure}

\begin{table}[htbp]
\caption{Sample wavelength calibration for CuAr with the high dispersion 
grism ({\it HIGH})}
\label{tab-w-high}
\hrule
%   23 lines identified from DISK$TEMP:[GDS]43370_XS
\begin{verbatim}

      Channel   Wavelength   Calculated  Discrepancy  Line#

      68.5122    5495.8740    5495.3438      -0.5303      1    
      86.0192    5451.6519    5452.1714       0.5195      2    
     151.0161    5292.5171    5292.6064       0.0894      3    
     194.0565    5187.7461    5187.6226      -0.1235      4    
     234.0315    5090.4951    5090.6470       0.1519      5    
     286.0787    4965.0801    4965.2144       0.1343      6    
     335.0711    4847.8101    4848.0679       0.2578      7    
     352.7338    4806.0210    4806.0679       0.0469      8    
     370.1714    4764.8652    4764.7290      -0.1362      9    
     415.7065    4657.9009    4657.3936      -0.5073     10    
     436.2100    4609.5669    4609.3628      -0.2041     11    
     464.0057    4545.0518    4544.5601      -0.4917     12    
     478.6262    4510.7329    4510.6206      -0.1123     13    
     526.0810    4400.7598    4401.1846       0.4248     14    
     549.2548    4348.0640    4348.1587       0.0947     15    
     555.5106    4333.5610    4333.8926       0.3315     16    
     633.0545    4158.5908    4158.8174       0.2266     17    
     645.0946    4131.7241    4131.9365       0.2124     18    
     657.6050    4103.9121    4104.0947       0.1826     19    
     707.0172    3994.7920    3995.0391       0.2471     20    
     729.0117    3947.5300    3946.9756      -0.5544     21    
     774.0031    3850.5811    3849.6133      -0.9678     22    
     813.0164    3765.5500    3766.2588       0.7087     23    

 RMS error:       0.39, Line width used:  2.00

 Order of fit:   3

 0.9602472321444220D-07  0.1045408027795212D-03 -0.2483892165373404D+01
 0.5664999221813987D+04
\end{verbatim}
\hrule
\end{table}

\newpage
\section{Filter throughput}
\label{app-filterthroughput}

The measured throughput of the three broadband filters, PB, PV and PR is 
shown in Fig.~\ref{fig-filters}. 
\begin{figure}[htbp]
\vspace{150mm}
\caption{Measured throughput of the broadband Harris/NOAO photometric filters 
used with LDSS-2}
\label{fig-filters}
\end{figure}

\end {document}
\bye


\end{document}
