\documentstyle[11pt]{article}
\setlength{\topmargin}{0mm}
\setlength{\textwidth}{170mm}
\setlength{\textheight}{220mm}
\setlength{\oddsidemargin}{0mm}
\setlength{\evensidemargin}{0mm}
\setlength{\headheight}{0mm}
\setlength{\headsep}{0mm}
%
\def\helpindent#1{\setbox2=\hbox to\parindent{{\it #1}\hfil}
                  \indent\llap{\box2}\ignorespaces}
\def\helpitem{\parindent=70pt\par\hang\helpindent}
\def\helpitemitem{\parindent=70pt\par\indent \hangindent2\parindent
\helpindent}
%============= Definition of \WHTlogo control sequence =====================*
%
%   Roger Wood          This is the terse form  -  expanded, formatted,
%  20-Apr-1989          commented version in ???
%
\newcommand{\WHTlogo}[1]{         \setlength{\unitlength}{#1mm}
\begin{picture}(8,10)(-4,0.7)     \put(-0.4,10.4){\line(1,0){0.8}}
\put(-0.4,10.1){\line(0,1){0.3}}  \put(+0.4,10.1){\line(0,1){0.3}}
\put(-0.4,9.2){\line(0,1){0.6}}   \put(+0.4,9.2){\line(0,1){0.6}}
\put(-0.3,8.9){\line(1,0){0.6}}   \put(-1.6,10.1){\line(1,0){3.2}}
\put(-1.6,9.8){\line(1,0){3.2}}   \put(-1.4,6.2){\line(1,3){1.2}}
\put(+1.4,6.2){\line(-1,3){1.2}}  \put(-1.2,6.2){\line(1,3){1.2}}
\put(+1.2,6.2){\line(-1,3){1.2}}  \put(-1.4,6.2){\line(0,1){3.6}}
\put(+1.4,6.2){\line(0,1){3.6}}   \put(-1.6,4.6){\line(0,1){5.5}}
\put(+1.6,4.6){\line(0,1){5.5}}   \put(-1.5,4.4){\line(-1,3){0.1}}
\put(+2.5,4.4){\line(1,3){0.1}}   \put(-0.25,7.0){\line(1,0){0.5}}
\put(-0.25,6.2){\line(0,1){0.8}}  \put(+0.25,6.2){\line(0,1){0.8}}
\put(-1.6,6.2 ){\line(1,0){3.2}}  \put(0.0,5.77){\circle{0.6}}
\put(-0.75,5.35){\line(1,0){1.5}} \put(-0.95,5.35){\line(-1,0){0.65}}
\put(+0.95,5.35){\line(1,0){0.65}}\put(-0.0,4.6){\line(-1,1){1.6}}
\put(+0.0,4.6){\line(1,1){1.6}}   \put(-0.1,4.5){\line(-1,1){1.5}}
\put(+0.1,4.5){\line(1,1){1.5}}   \put(-0.1,4.5){\line(1,0){0.2}}
\put(-0.4,4.8){\line(-1,0){1.0}}  \put(+0.4,4.8){\line(1,0){1.0}}
\put(-0.2,4.8){\line(1,0){0.4}}   \put(-1.4,4.6){\line(0,1){0.2}}
\put(+1.4,4.6){\line(0,1){0.2}}   \put(-0.2,4.6){\line(-1,0){1.4}}
\put(+0.2,4.6){\line(1,0){1.4}}   \put(-1.5,4.2){\line(0,1){1.15}}
\put(+1.5,4.2){\line(0,1){1.15}}  \put(-1.5,4.2){\line(1,0){3.0}}
\put(-1.0,3.9){\line(0,1){0.3}}   \put(+1.0,3.9){\line(0,1){0.3}}
\put(-1.0,3.9){\line(1,0){2.0}}   \put(-1.6,6.1){\line(-1,0){0.5}}
\put(+1.6,6.1){\line(1,0){0.5}}   \put(-1.6,5.4){\line(-1,0){0.5}}
\put(+1.6,5.4){\line(1,0){0.5}}   \put(-2.1,5.2){\line(0,1){0.9}}
\put(+2.1,5.2){\line(0,1){0.9}}   \put(-2.2,5.7){\line(-1,0){1.5}}
\put(+2.2,5.7){\line(1,0){1.5}}   \put(-2.2,5.5){\line(-1,0){1.5}}
\put(+2.2,5.5){\line(1,0){1.5}}   \put(-3.5,5.2){\line(0,1){0.5}}
\put(+3.5,5.2){\line(0,1){0.5}}   \put(-2.4,5.2){\line(0,1){0.5}}
\put(+2.4,5.2){\line(0,1){0.5}}   \put(-1.8,5.2){\line(-1,0){1.9}}
\put(+1.8,5.2){\line(1,0){1.9}}   \put(-3.7,4.9){\line(0,1){0.3}}
\put(+3.7,4.9){\line(0,1){0.3}}   \put(-1.8,4.0){\line(0,1){1.4}}
\put(+1.8,4.0){\line(0,1){1.4}}   \put(-2.5,3.9){\line(-6,5){1.2}}
\put(+2.5,3.9){\line(6,5){1.2}}   \put(-0.9,2.2){\line(-1,2){0.9}}
\put(+0.9,2.2){\line(1,2){0.9}}   \put(-2.2,2.2){\line(1,0){4.4}}
\put(-2.2,2.1){\line(0,1){0.1}}   \put(+2.2,2.1){\line(0,1){0.1}}
\put(-2.2,2.1){\line(1,0){4.4}}   \put(-1.7,1.5){\line(-1,3){0.8}}
\put(+1.7,1.5){\line(1,3){0.8}}   \put(-1.7,1.5){\line(1,0){3.4}}
\put(-1.7,1.0){\line(0,1){0.5}}   \put(+1.7,1.0){\line(0,1){0.5}}
\put(-1.7,1.0){\line(1,0){3.4}}
\end{picture} }
%
%=========== End of \WHTlogo control sequence definition ===================*
%
\begin{document}
%
% Local definitions
% -----------------
\newcommand{\etal}{{\it et al.\ }}
\newcommand{\eg}{{\it e.g.\ }}    
\newcommand{\etc}{{\it etc.\ }}
\newcommand{\ie}{{\it i.e.\ }}
\newcommand{\qv}{{\it q.v.\ }}
\newcommand{\viz}{{\it viz.\ }}
\newcommand{\degs}[1]{$#1^\circ$}                       % Degrees symbol
\newcommand{\mins}[1]{$#1^{\scriptsize\prime}$}         % Minutes symbol
\newcommand{\secs}[1]{$#1^{\scriptsize\prime\prime}$}   % Seconds symbol

% 
% Title page
% ----------
%
\pagestyle{empty}
\begin{center}

\vspace{1.0in}

{\Huge \bf GUIDE-STAR SEARCH (GSS)}

\vspace{0.3in}

{\Huge \bf USERS' MANUAL}

\vspace{0.6in}

{\large \today}

\vspace{0.5in}

{\Large Robert Laing}


\vspace{0.7in}

\WHTlogo{4}

\vfill

\end{center}
%
\cleardoublepage

% Contents
% --------
\pagestyle{plain}
\pagenumbering{roman}                        % Lower case roman page numbers

\tableofcontents    
\listoffigures    
\listoftables  
\cleardoublepage


% Main text
% ---------

\pagenumbering{arabic}                       % Arabic page numbers hereafter

\section{Introduction}

The main objective of the software described in this manual is to use the Space
Telescope Guide Star Catalogue (hereafter GSC) to locate guide stars suitable
for the ING Telescopes on La Palma. The GSC provides a large number of
stars with (fairly) accurately-known positions.   It will generally contain
several stars in any of the guiding fields for all except the most perverse
target positions (\eg in dark clouds).   The only exception is the WHT
Nasmyth focus (through the derotation optics), where the field is too small
to guarantee that a suitable star will be found. The software, therefore,
accesses the GSC, finds suitable guide stars for a given position and
telescope configuration and outputs their positions in a form suitable for
the telescope, A\&G and autoguider control software.

The software package is called GSS (Guide-Star Search) and runs on Vaxes
under VMS.  It is installed on the ING Vax Cluster and on the software
development machines at RGO, and may be run from remote computers via the
Internet.   It provides output in the form of text files of guide star and
probe positions and may be used to produce plots of the fields on a variety
of graphics devices.

A more specialised application is the selection of guide stars suitable for
closed-loop blind offsets.  This is useful for slit spectroscopy of faint
targets on either the
WHT or the INT.  The technique relies on the fact that the encoding of the
guide probes is more precise than that of the telescope drives.  A reference
star whose position is known accurately with respect to the target is acquired
on the spectrograph slit with the autoguider loop locked.  The telescope and
guide probe are then moved simultaneously by the known offset to the target, so
that the same guide star remains in the autoguider field. When the guide loop
is locked, the target should be accurately centred on the spectrograph slit.
The fields accessible to the guide probes have peculiar shapes, so it is
sensible to check in advance whether a suitable guide star will  be visible
both before and after the offset.  If not, a different choice of reference star
or slit position angle can be made.

Whilst GSS itself is an off-line application, selection and acquisition of
guide stars for the WHT is integrated into the on-line control software via
the TAG I-task.  This uses the same catalogue, algorithms and applications
code as GSS, but will generally require fewer steps to operate, and will
reduce observing overheads significantly. TAG is recommended for most
guide-star applications on the WHT (see the TAG Manual for more details).
Even if you intend to use TAG at the telescope, 
it is worth running GSS to locate guide stars in advance if there is any
doubt whether they will be accessible. The most obvious cases are:
\begin{enumerate}
\item Off-axis autoguiding with UES, where the field is small.
\item Closed-loop offsetting, as described above, where the guide star must
be visible before and after the offset.
\end{enumerate}

The GSS software is supported from RGO Cambridge by Marion Fisher
(mpf@ast.cam.ac.uk) and Robert Laing (rl@ast.cam.ac.uk).  Please report
any faults or suggestions for improvements via the Defect Database or
directly to the authors.

\section{The Guide-Star Catalogue}

The GSC contains roughly $1.9\times 10^7$ objects with magnitudes in the 
range 7 -- 16, of which more than $1.5 \times 10^7$ are classified as 
stars.   It is based on an all-sky, single epoch, single passband Schmidt 
survey.   Astrometry, at equinox J2000, is available at the epoch of the 
individual plates used in the GSC (1975 -- 1983) and is based on the
AGK3, SAO and CPC  catalogues.   An analysis against CAMC measurements
by Taff \etal (1990) showed that the GSC absolute positional errors are
dominated by systematic effects and vary from 0.5 -- 1.1 arcsec from
plate centre to edge in the north and from 1.0 -- 1.6 arcsec in the
south.  Relative errors at \degs{0.5} separations vary from 0.3 -- 0.8
arcsec, depending on hemisphere and magnitude.  The positions are
therefore not quite accurate enough to be used for blind offsetting into
narrow slits.

The catalogue is subdivided into 9537 regions bounded by small circles of
right ascension and great circles of declination.  Data for each region are 
stored in separate files; these files are contained in subdirectories, each 
of which covers a \degs{7.5} range of declination.   The GSC is distributed 
on two CD ROMs in  ISO 9660 format, divided at a declination of \degs{7.5}S.
All data files are in FITS table format.
The catalogue is fully documented in the booklet supplied with the CD-ROM 
set and a series of papers (Lasker \etal 1990, Russell \etal 1990 and 
Jenkner \etal 1990).

\section{Running GSS}

\subsection{General}

The GSS may be run from any account on the La Palma Vax Cluster or 
on the software development Vaxes at RGO.  In the latter case, outside
users are not normally allowed, so a dedicated account with
restricted privileges has been set up for the express purpose of running
GSS.  Both sets of  machines are accessible over the Internet.
The first step is always to set up the logical names needed by GSS, which
requires a command procedure to be run from the login prompt. 
Thereafter, the software is started by the command {\tt GSS}, 
which gives a {\tt GSS$>$} prompt, and stopped by {\tt EXIT}.  If for
any reason the GSS gets stuck, try {\tt CNTRL Z} to stop an application
and return to the prompt.  If all else fails, {\tt CNTRL Y} will abort
the program and return you to the operating system prompt.
In the rest of the manual, instructions to be typed are shown as follows:
\begin{verbatim}
$ GSS
\end{verbatim}
or 
\begin{verbatim}
GSS>DEVICE XWINDOWS
\end{verbatim}
where {\tt \$} and {\tt $>$GSS} are the VMS and GSS prompts.  Neither
the GSS software nor the VMS operating system are case-sensitive.  Both support
minimum-match abbreviation of commands.

\subsection{La Palma: normal operation}

In order to allow access to the GSC by multiple users, and to improve
access speed, the catalogue has been copied to a magnetic disk, which
should be visible to any machine in the cluster. To set up the logical
names needed to run the GSS on La Palma, execute the command procedure:
\begin{verbatim}
$ @DISK$USER3:[GSS]GSS_INIT
\end{verbatim}
(you may find it convenient to add this to your LOGIN.COM file).
Then type 
\begin{verbatim}
$ GSS
\end{verbatim}
to start the software.  
It occasionally happens that the catalogue disk is not mounted on every
node in the cluster.  In order to check its availability, type:
\begin{verbatim}
$ SHOW DEVICE GSS_DISK
\end{verbatim}
You should see something like:
\begin{verbatim}
Device                  Device           Error    Volume          Free Trans Mnt
 Name                   Status           Count     Label        Blocks Count Cnt
LPVS3$DKB300:           Mounted              0  GSTARCAT        762004    1   8
\end{verbatim}
If the disk is not mounted, try logging into the captive account
MDISK from a DECserver terminal or an X-terminal LAT session ({\em not} 
from a remote machine)  and following the instructions.  If you still cannot
mount the disk, try running GSS from LPVS3 (to which the disk is
physically attached).  If all else fails, use the CD-ROM version (see
below).

\subsection{La Palma: operation from CD-ROM (emergencies only)}

If the disk containing the GSC is, for some reason, inaccessible, then
the software can access the original CD-ROM version of the catalogue.
The disks are mounted on LPVS3 (LPVS3\$DKB400: and DKB500:) and the
drives are located next to this VaxStation.  The disks should be
permanently loaded in the two drives. If they are not, consult the
software group (who may be using the system for VMS documentation).  Do
not attempt to (un)load CD's until you have had a lesson from a
qualified person.  It does not matter which disk goes in which drive.

\noindent{\bf Warning}: the v1.1 release of the GSC should always be
used, as our copies of the v1.0 disks generate an unacceptable number of
hardware read errors.

\noindent In order to set up to work with the CD-ROM version, type:
\begin{verbatim}
$ @DISK$USER3:[GSS]GSS_INIT
$ DEFINE/JOB GSS_DISK CDROM
$ GSS
\end{verbatim}
The system should respond with the
{\tt GSS$>$} prompt after the 15 seconds or so needed to mount the CD's. 
If the program is being run by someone else, there will be an
error message to the effect that the disks are allocated to another
user.  In this case, type {\tt SHOW DEVICE/FULL LPVS3\$DKB} and note the
username.  Contact the offending person and ask them to exit from the
GSS and/or dismount the disks.
The {\tt EXIT} command will automatically dismount the CD-ROMs, but if
you have to use {\tt CNTRL Y} to abort GSS, you
will need to type:
\begin{verbatim}
$DISMOUNT GSS_DEV1
$DISMOUNT GSS_DEV2 
\end{verbatim}
If you wish to revert to the magnetic disk version, type 
\begin{verbatim}
$ DEFINE/JOB GSS_DEVICE DISK
\end{verbatim}
to reset the logical name.

\subsection{RGO: the GSS account}

In Cambridge, the GSS may be run from any account on the software
engineering group Vaxes  (GXSEG0, GXSEG1 or GXSEG2).  Users without
their own account should log in to the GSS account.  The password to
this account will change periodically: please e-mail Marion Fisher
to find out the current password (mpf@ast.cam.ac.uk).  To access GXSEG0
remotely, use:
\begin{verbatim}
telnet gxseg0.ast.cam.ac.uk
\end{verbatim}
and log in with username GSS and the current password.  The appropriate
initialisation is done automatically, so to start the software, just
type:
\begin{verbatim}
$ GSS
\end{verbatim}
If you wish to display plots on a remote X-windows device, type:
\begin{verbatim}
$ XDISPLAY
\end{verbatim}
before starting GSS.
The GSS account has been allocated enough disk space to allow users to
store output and plot files (it is a good idea to create a new
subdirectory for the purpose).  Files may be copied to another machine
using ftp, but VMS mail is disabled.  Please delete unwanted files as soon as
possible: in any case they will be removed automatically after 60 days.  Users
who already have an account on the cluster should execute the command:
\begin{verbatim}
$ GSS_INIT
\end{verbatim} 
before starting GSS.  By default, the software uses a version of the GSC
on magnetic disk: the CD-ROM version of the catalogue is not normally
available, and would be loaded only by special request in the event of a disk
crash.


\section{Simple use of the program}

This section describes the most common applications of the GSS software.
Fuller details of all of the available commands are given in
Sections~\ref{Conf-target} -- \ref{IO}.


\subsection{Standard configurations}
\label{Config-summary}

In order to find guide stars, the GSS needs to be told the telescope and
focal station/instrument combination (referred to as the {\it  configuration}) 
and the position angle of the instrument rotator.
The current configurations are:
  \begin{description}
  \item [WHT CASS] WHT Cassegrain focus with the guide probe
  restrictions appropriate for slit-viewing, used with ISIS and FOS.
  \item [WHT AUXPORT] WHT Cassegrain focus with no restrictions on
  guide probe movement (appropriate for LDSS and auxiliary port
  imaging).
  \item [WHT TAURUS] WHT Cassegrain focus with Taurus (as AUXPORT, but
  with a different rotational offset).
  \item [WHT PRIME] WHT Prime focus CCD imaging ({\em not} Autofib/WYFFOS,
  where guide stars should be found as part of the set-up of the
  fibre positioner).
  \item [WHT UESPROBE] WHT UES Nasmyth focus with derotation optics 
  (moving guide probe).
  \item [INT PRIME] INT Prime focus (imaging CCD, photographic camera)
  \item [INT CASS] INT Cassegrain focus (IDS, FOS \etc)
  \item [JKT CCDE] JKT f/15 Cassegrain + CCD East of the pier
  \item [JKT CCDW] JKT f/15 Cassegrain + CCD West of the pier
  \item [JKT WFCE] JKT f/8 Cassegrain + wide-field camera East of the
                       pier
  \item [JKT WFCW]f/8 Cassegrain + wide-field camera West of the
                       pier
  \item [NONE] Nearest star search (this is independent of telescope, and is
  intended merely to locate the star(s) nearest to the target position, 
  \eg for use as references in blind offsetting).
  \end{description}
In order to specify the configuration, use the command {\tt CONFIG
configuration\_name} at the {\tt GSS$>$} prompt.  The position angle is input
using the {\tt ROTATOR} command, for example:
\begin{verbatim}
GSS>CONFIG WHT CASS
GSS>ROTATOR 180
\end{verbatim}


\subsection{Finding Guide Stars}

The simplest option is to use the configuration defaults.  To find stars
for the INT, use commands like the following:
\begin{verbatim}
$GSS
GSS>CONFIG INT CASS
GSS>ROTATOR 90
GSS>SEARCH 12 34 56.23 30 00 02 J2000
GSS>EXIT
$TYPE OUTPUT.GS
\end{verbatim}
This finds the brightest 10 guide stars available for the INT Cass
focus at the specified position for sky position angle \degs{90}.  The
position and probe coordinates for the guide star are given in
OUTPUT.GS, which is the default output file name.

The next example shows how to increase the number of potential guide
stars and to produce a plot of the results for the INT Prime focus.
\begin{verbatim}
$XDISPLAY
$GSS
GSS>CONFIG INT PRIME
GSS>ROTATOR 180
GSS>NUMBER 50
GSS>DEVICE XWINDOWS
GSS>SEARCH 23 23 24.56 45 56 23.1 B1950
GSS>PLOT
GSS>EXIT
$TYPE OUTPUT.GS
\end{verbatim}
produces an X-windows plot.

On La Palma, the guide star details may be printed using {\tt WHT\_LASE OUTPUT.
GS} or {\tt INT\_LASE OUTPUT.GS}.  To get a hard copy of the plot, use CANON\_L
as the device name, and use {\tt WHT\_GLASE} or {\tt INT\_GLASE} to print the
resulting CANON.DAT file, or POSTSCRIPT\_L, followed by {\tt WHT\_PLASE
GKS\_72.PS}. A complete list of the currently-supported configurations is given
in the next section.


\subsection{Guide stars for closed-loop offsetting}

In order to select guide stars suitable for closed-loop offsetting, the
positions of the target and a nearby reference star of accurately known
relative position must be entered in a catalogue.  This is a simple text file,
and the allowed formats are described in detail in Section~\ref{Catalogues}.
In most circumstances, only the name, RA, Dec and equinox of each object need to
be specified.  For example, in order to observe a target 3C789 with a reference
3C789REF, the catalogue file (BLACK.CAT) would look like:
\begin{verbatim}
3C789    20 13 14.156 45 45 45.45 J2000
3C789REF 20 13 16.020 45 44 06.34 J2000
\end{verbatim}
To select a suitable guide star in order to observe with the INT at PA 90:
\begin{verbatim}
$GSS
GSS>CONFIG INT CASS
GSS>ROT 90
GSS>CATA BLACK.CAT
GSS>BLIND 3C789REF 3C789
GSS>EXIT
$TYPE OUTPUT.GS
\end{verbatim}
The output gives the probe coordinates appropriate for the reference star and
the offset required to acquire the target (this will be applied automatically by
the INT TCS command {\tt AUTOFFSET} described in the INT Manual, although
beware the fact that the target and reference must have coordinates at the same
equinox in this case).


\subsection{Finding guide stars for a large number of targets}

In order to determine guide star positions for a long list of targets to be
observed with the same instrumental configuration, the
simplest method is to make a catalogue file containing their positions (as
described in the previous section) and to use the {\tt CATSEARCH} command.
For example, to list one guide star for each of the entries in a catalogue
WHITE.CAT, to be observed with the JKT CCD camera:
\begin{verbatim}
$GSS
GSS>CONFIG JKT CCDE
GSS>NUMBER 1
GSS>CATSEARCH WHITE.CAT
GSS>EXIT
\end{verbatim}

\section{Configurations and Target Data}
\label{Conf-target}

This section describes the specification of configurations and target positions
in more detail.  Between them, these provide all of the data needed to execute
the search procedure.

\subsection{Configurations}
\label{Config-details}

A {\it configuration} is the set of parameters needed to specify the
search procedure for a given object and rotator position angle.  The
combinations of telescope and focal station currently supported 
were listed in Section~\ref{Config-summary} (see Appendix ~\ref{Geometry} for
more details).
The parameters included as part of a configuration are as follows:
\begin{description}
\item [Geometry] The descriptions of the search areas and the
conversions between RA, Dec. and guide probe coordinates.  These are not
expected to change unless mechanical modifications are made and are not
accessible to the user.
\item [Magnitude] Each configuration is associated with a
magnitude range, defining the brightest and faintest possible guide
stars.   The defaults have been set to suit the autoguiders, but may be
overridden.
\item [Observing aperture] This is specified as an (x,y) pair, in arcsec,
and defines the position in the focal plane at which the target is to be 
observed.  The origin of coordinates is at the intersection of the rotator 
axis with the focal plane and the x and y axes are defined in the same 
sense as those used by the telescope control system for aperture offsets.
 \begin{description}
 \item [WHT Cassegrain] The default aperture coordinates are set to
  zero, as the centre of rotation is almost on the ISIS slit.
 \item [WHT Nasmyth] Defaults are zero, pending further information.
 \item [INT Cassegrain] The defaults are set for a position
 corresponding to the intersection of the IDS slit and the central
 column of the EEV5 detector.
 \item [INT Prime] This is the only configuration for which the aperture 
 is displaced by more than a few arcsec from the rotator axis. Some care
 is needed to ensure that self-consistent parameters are used by the GSS
 and the telescope control system.  For CCD observing, the 
 aperture used by the GSS should
 be the same as the nominal aperture determined for the chip centre
 (see INT Telescope Manual).  For the plate camera, the aperture offset
 should be close to (0,0). 
 \item [JKT Cassegrain] The default is set to (0,0), which 
 should be close to the centre of the 
 imaging CCD.
\end{description}
Note that accurate blind  offsetting from an off-axis guide star will
require precise specification of  the observing aperture (this
application will only become feasible once the proposed astrometric
recalibration of the catalogue is completed).  Default values are held
as part of the  configuration.
\item [Minimum separation] This defines the minimum distance between a
selected guide star and its nearest neighbour in the catalogue (whether
or not the latter satisfies the selection criteria).
\item [Number of stars] This is the maximum number of stars to be
selected during a search.
\end{description}

\subsection{Target data}

The parameters specified below define the target position and rotator
position angle.
\begin{description}
\item [Target name and position] in any of the coordinate systems supported 
by the WHT telescope control system.  The following parameters are 
required:
  \begin{description}
  \item [Right ascension] Hours, minutes, seconds, separated by spaces.
  \item [Declination] Degrees, minutes, arcseconds, separated by spaces.
  \item [Equinox] Mean FK4 or FK5 systems (\eg B1950, J2000) or apparent 
  coordinates of arbitrary date. (Note that this is a change from the WHT
  TCS, which supports apparent coordinates of current date only.  This is 
  necessary in order to allow running of the guide star search software
  well before the observations take place).
  \end{description}
The remaining parameters are optional.   Parallax and radial velocity, in 
particular, will make very small differences to the exact selection of 
guide stars and to the computed guide probe positions, but are retained for 
consistency with the TCS and to allow direct use of WHT catalogue files.
  \begin{description}
  \item [Proper motions] in RA (seconds of time per year) and Dec 
  (arcseconds per year).  Defaults to zero.
  \item [Epoch] (year).  Defaults to equinox.
  \item [Parallax] (arcsec). Defaults to zero.
  \item [Radial Velocity] (kms$^{-1}$; defaults to zero).
  \end{description}
It is possible to input target positions in a catalogue file in
the format accepted by the WHT control system.   In this case,
references to a particular object are by name.   The catalogue format is
described in detail in Section~\ref{Catalogues}.
\item [Rotator position angle] This is a sky position angle, in the range 
\degs{0} -- \degs{360}, as used by the relevant telescope control system.
See Appendix~\ref{Astrom} for some subtleties affecting wide fields.
\end{description}


\section{Commands}
\label{Commands}

Data can be input either interactively or via
simple command files.  The normal mode of use will be to select the
configuration at the beginning of a session, thereafter changing only
the source position and (optionally) the rotator position angle.   There
follows a list of commands, subdivided into {\em data entry} and {\em
actions}.

\subsection{Data entry}

\begin{description}
\item [APERTURE] Enter the observing aperture coordinates (arcsec). The default
values are determined by the telescope/focal station combination.
\helpitem{Format:   } {\tt APERTURE x y}
\helpitem{Example:  } {\tt APERTURE 10 20}
\item [CATALOGUE] Enter the name of a source catalogue to be used as a
list of target positions.   Standard VMS syntax, defaulting to the current 
directory with a .CAT extension.
\helpitem{Format:   } {\tt CATALOGUE $<$filename$>$}
\helpitem{Examples: } {\tt CATALOGUE MANX} (uses MANX.CAT in the current
                      working directory)
\helpitem{}           {\tt CATALOGUE U3:[GUEST01.CATS]JELLICLE.CAT}
\item [CONFIGURATION] Specify the observing configuration.
The current list of telescope and focal station
combinations is given in Section~\ref{Config-summary}.
\helpitem{Format:   } {\tt CONFIGURATION $<$telescope$>$ $<$focal\_station$>$}
\helpitem{Examples: } {\tt CONFIG INT CASS}
\helpitem{}           {\tt CONFIG NONE} 
\item [DATE] Enter the epoch of observation (as a year number, to an accuracy
of 3 decimal places, or in DEC standard format). The default is the current
date and time.
\helpitem{Format:   } {\tt DATE $<$date$>$}
\helpitem{Examples: } {\tt DATE 1994.256}
\helpitem{}           {\tt DATE 21-DEC-1995}
\helpitem{}           {\tt DATE 25-DEC-1999:22:00:00}
\item [DEFAULT] Reset the relevant configuration parameters to their default
values. The keywords covered by this command are: {\tt DATE}, 
{\tt APERTURE}, {\tt MAGNITUDE}, {\tt NUMBER}, {\tt SEPARATION} and
{\tt ALL}. The default (assumed if no parameter is given) is {\tt ALL}.
\helpitem{Format:   } {\tt DEFAULT $<$configuration$>$}
\helpitem{Examples: } {\tt DEFAULT MAGNITUDE}
\helpitem{}           {\tt DEFAULT}
\item [DEVICE] Set the GKS device to be used for plotting.
To get a list of workstation names, type {\tt DEVICE} followed by 
{\tt ?} at the {\tt \_GKS Device name:}prompt ({\em not} {\tt DEVICE ?}). 
\helpitem{Format:   } {\tt DEVICE $<$GKS\_device\_name$>$}
\helpitem{Example:  } {\tt DEVICE XWINDOWS}\newline
The most commonly-used device names are: 
 \begin{description}
 \item [PERICOM\_MG] Pericom graphics terminal.
 \item [CANON\_L] Canon laser-printer (landscape mode).  Note that a
 device-name of \newline CANON\_L;filename causes the plot output to be written
 to a file called filename rather than the usual CANON.DAT.  Canon graphics
 can be printed on La Palma using the commands {\tt WHT\_GLASE} and 
 {\tt INT\_Glase}.
 \item [CANON\_P] Canon laser-printer (portrait mode; output filename as 
 above).
 \item [POSTSCRIPT\_L] Postscript (landscape mode).  Again, specifying 
 POSTSCRIPT\_L;filename generates output in filename, rather than the
 generic GKS\_72.PS.  Postscript output can be printed on La Palma using the
 command {\tt WHT\_PLASE}.
 \item [POSTSCRIPT\_P] Postscript (portrait mode; output filename as above).
 \item [XWINDOWS] X-window on VaxStation, Sun or X-terminal.  Note that
 to get a window on a remote workstation, the command {\tt XDISPLAY} 
 should be issued at the {\tt \$} prompt before starting GSS.  This is a
 Starlink command, and to use it you will need to execute the appropriate
 login procedure by typing (or including in your LOGIN.COM file) the
 command {\tt @SSC:LOGIN}.
 \end{description}
\item [MAGNITUDE] Set the bright and faint V magnitude limits.
The default values are the standard values for the configuration.  The allowed
range is 5 -- 19 (there are no stars in the GSC with magnitudes outside these
limits).
\helpitem{Format:   } {\tt MAGNITUDE V$_{min}$ V$_{max}$}
\helpitem{Example:  } {\tt MAGNITUDE 12 15}
\item [NUMBER] Set the maximum number of guide stars to be selected at a given 
position angle.  Overrides system default (50 for NONE; 10 for all other
configurations).
\helpitem{Format:   } {\tt NUMBER $<$max\_number$>$}
\helpitem{Examples: } {\tt NUMBER 45}
\item [ROTATOR] Input the sky position angle, as given to the relevant
telescope control system, in degrees (\degs{0} -- \degs{360}) or specify that
guide stars be found for all possible position angles using the keyword {\tt
ANY}.  The latter option is meant for small fields, where there may only be a
limited choice of guide stars, in order to allow a sensible choice of rotator
PA.  It is disabled for WHT and INT Prime and for the JKT Wide-Field Camera.
\helpitem{Format:   } {\tt ROTATOR $<$angle$>$} or
\helpitem{}           {\tt ROTATOR ANY}
\helpitem{Examples: } {\tt ROTATOR 180}
\item [SEPARATION] Set the minimum separation of guide stars (arcsec).
Overrides system default (5 arcsec for telescope configurations; zero for
NONE).
\helpitem{Format:   } {\tt SEPARATION $<$min\_separation$>$}
\helpitem{Example:  } {\tt SEPARATION 2}
\end{description}

\subsection{Actions}

\begin{description}
\item [BLIND] Determine the positions of guide stars suitable for a 
closed-loop blind offset between two named objects.
The reference and target objects must be
included in the current catalogue.  This command will then select  guide
stars which are within the accessible  field for both objects and will write
the probe positions and displacements to the current output file.  It does not
work if the {\tt CONFIG NONE} or {\tt ROTATOR ANY} options are specified.
\helpitem{Format:   } {\tt BLIND $<$reference$>$ $<$target$>$}
\helpitem{Example:  } {\tt BLIND THREE MICE}
\item [CATSEARCH] Search for guide stars around all
objects in a named catalogue. The catalogue name follows standard VMS 
syntax and the default extension is .CAT.
\helpitem{Format:   } {\tt CATSEARCH $<$catalogue\_name$>$}
\helpitem{Examples: } {\tt CATSEARCH MACAVITY.CAT}
\helpitem{}           {\tt CATSEARCH U3:[GUEST01.CAT]BASKET}
\item [DO] Filename.  Search the GSC using GSS commands from the 
specified file rather than interactive input.   Defaults to .COM
extension and the current directory. Nesting of GSS commands is not supported.
\helpitem{Format:   } {\tt DO $<$filename$>$}
\helpitem{Example:  } {\tt DO STARS.CMD}
\item [HELP] Access to help on GSS commands and abbreviations via a VMS HELP
library with the usual hierarchical structure.
\helpitem{Format:   } {\tt HELP [$<$topic$>$]}
\helpitem{Examples: } {\tt HELP}
\helpitem{}           {\tt HELP OUTPUT}
\item [EXIT] Stop the GSS program. If using the CD-ROM version of the
catalogue, also dismount the disks.
\helpitem{Format: } {\tt EXIT}
\item [OFFSET] Determine the positions of guide stars for a closed-loop blind
offset of a specified amount from a named reference object. The reference
object must be included in the current catalogue.  The offsets are specified in
arcsec in the tangent plane parallel to RA ($\xi$) and Declination
($\eta$).  An optional rotation, in 
degrees, may also be included (this is intended primarily for alignment of 
multislit fields on the WHT and has the same parameters as the TCS {\tt TWEAK}
command). {\tt OFFSET} selects  guide stars which are within the
accessible field before and after the offset and will write the probe positions
and displacements to the current output file.
It does not work if the {\tt CONFIG NONE} or {\tt ROTATOR ANY} options are
specified.
\helpitem{Format:   } {\tt OFFSET $<$reference$>$ $\xi$ $\eta$ 
[$<$rotation$>$]}
\helpitem{Examples: } {\tt OFFSET ALPHACEN 3.4 -23.4}
\helpitem{}           {\tt OFFSET REF 4.5 0.0 1.3}
\item [OUTPUT] Filename.  Creates and opens a new output file to be used until
superseded by another OUTPUT command, and closes any previous output file.
Standard VMS syntax, defaulting to OUTPUT.GS in the current directory.
\helpitem{Format:   } {\tt OUTPUT $<$filename$>$}
\helpitem{Examples: } {\tt OUTPUT WHT.GS}
\helpitem{}           {\tt OUTPUT DISK\$USER1:[GUEST01.CATS]TARGETS.GUIDE}
\item [PLOT] Plot the positions of the selected guide stars on the selected
device.   The plot is centred on the rotator axis and shows the
positions of the selected guide stars in the focal plane coordinate
system (x left-right; y up-down; PA \degs{0} vertical).  The target position
is marked by an open star, and the rotator axis (if the target is not on it)
is marked by an open circle and dot. The outline of
the field is drawn, together with an ``L'' indicating North and East.
An open circle indicates that the object is classified as stellar on all
available plates. An x represents an object with a non-stellar classification
on all plates and a circle with a superposed x represents an ambiguous
classification.  Larger symbols correspond to brighter objects.
\helpitem{Format:  } {\tt PLOT}
\item [SEARCH] Search the catalogue for guide stars around a target 
position specified explicitly.   The RA, Dec and Equinox are required; 
other positional information can be entered using  optional qualifiers, as follows:
  \begin{description}
  \item [/RAPROPER] proper motion in RA (seconds of time per year)
  \item [/DECPROPER] proper motion in Dec 
  (arcseconds per year).
  \item [/EPOCH] (year).  Defaults to equinox.
  \item [/PARALLAX] (arcsec). Defaults to zero.
  \item [/RADVEL] radial velocity (kms$^{-1}$; defaults to zero).
  \end{description}
Examples:
\begin{verbatim}
SEARCH 20 12 13.33 -30 45 55.2 B1950
SEARCH 19 57 57 30.233 04 06.77 J2000 /RAP=0.001 /DECP=-0.12 /EP=1945.5
\end{verbatim}
This command is for use when a catalogue
has not been  specified (\eg for small numbers of objects).
\item [SHOW] displays the parameters of the currently-selected configuration
({\tt SHOW CURRENT}) or lists all the available configurations ({\tt SHOW
CONFIG}).  The former is the default.
\helpitem{Format: } {\tt SHOW $<$keyword$>$}
\helpitem{Examples:} {\tt SHOW}
\helpitem{}          {\tt SHOW CONFIG}
\item [SOURCE]  causes  the GSC to be searched around the position
of a named object in the current catalogue, 
using the current configuration and rotator PA.  The name should follow
the requirements of the WHT TCS (up to 20 characters; embedded spaces
require double quotes).
\helpitem{Format:   } {\tt SOURCE $<$sourcename$>$}
\helpitem{Example:  } {\tt SOURCE M87}
\end{description}

\section{Input and output files}
\label{IO}

\subsection{Catalogues}
\label{Catalogues}

A {\em catalogue file} is 
a list of target names and positions in the format used by the WHT TCS.
A catalogue is simply a
    text file of positional information in free format with spaces as
    separators.   All data for an entry should be on one line of the file.
    Anything following an asterisk or exclamation mark is treated as a
    comment and is ignored. Do not use tab, control or other peculiar
    characters.   The parameters must be in the order: Name, Right
    Ascension, Declination, Equinox,  proper motion in right ascension,
    proper motion in declination, Epoch, Parallax, Radial velocity.   The
    first four parameters are mandatory and the remainder are optional with
    sensible defaults. The formats and units of the necessary parameters
    are as follows: 
%
\begin{list}{$\bullet$}{\setlength{\itemsep}{-0.5mm}\setlength{\topsep}{0mm}}
 \item  {\bf Name}---up to 20 characters.   Embedded spaces are allowed,
        but if they are used, then the name must be enclosed in double
        quotes (\eg\ {\tt "NGC 7027"}). 
 \item  {\bf Right ascension}---hours, minutes, seconds, separated by
        spaces. 
 \item  {\bf Declination}---degrees, minutes, seconds, separated by spaces. 
 \item  {\bf Equinox}---for {\it mean} positions, a leading letter 
        indicates the coordinate system: \\*
          \hspace*{0.5cm} {\tt B} implies mean pre-IAU76 or FK4 \\*
          \hspace*{0.5cm} {\tt J} implies mean post-IAU76 or FK5 

        The letter is followed immediately by a number indicating the 
        epoch of the mean equator and equinox of that system 
       (\eg\ {\tt B1950.0} or {\tt J1987.5}). \\*
        For {\it apparent} positions this field should contain the word
        {\tt APPARENT} (abbreviable to {\tt A}). In order to maintain
        strict compatibility with the WHT TCS, no epoch is specified,
        and the {\tt DATE} command should be used to set the epoch of
        observation. 
\end{list}
\smallskip
%
The formats, units and defaults of the optional parameters are as follows:
%
\begin{list}{$\bullet$}{\setlength{\itemsep}{-0.5mm}\setlength{\topsep}{0mm}}
 \item  {\bf Proper motions}---in right ascension (seconds of time per
        year) and declination (arcseconds per year). Default to zero if not
        specified. 
 \item  {\bf Epoch of position}---(year).   This should not be confused
        with the equinox. The epoch of observation is used in conjunction
        with the proper motions to correct for the space motion of the
        object. If the epoch is not specified, then it is assumed to be the
        same as the equinox. 
 \item   {\bf Parallax}---(arcseconds).   Generally negligible. Defaults to
        zero if not specified. 
 \item  {\bf Radial velocity}---(km s$^{-1}$, positive for a receding
        object).   Generally unimportant. Defaults to zero if not
        specified. 
\end{list}
\medskip
\noindent Examples of catalogue files are:
%
\begin{list}{$\bullet$}{\setlength{\itemsep}{-0.5mm}\setlength{\topsep}{0mm}}
 \item  The simplest possible catalogue contains only name, right
        ascension, declination and equinox: 
 \begin{verbatim}
  3C567    12 34 56.78  -01 23 45.6  B1950 
  NGC123   00 12 46.6    05 34 56    J1987.5 
  COMET    12 12 12.12  +12 12 12.1  A
\end{verbatim}
 \item  A more complicated entry might include proper motions:
 \begin{verbatim}
  SP1  00 31 22.2  -12 24 21  B1950.0  0.011 -0.17
 \end{verbatim}
 \item  The ultimate in complexity has parallaxes and radial velocities too:
 \begin{verbatim}
  S01-07  00 50  7.596  -10 38 39.54  J2000  -0.01531 -0.2287 2000  .059    8 
  S01-22  01 06  7.724  -23 59 33.07  J2000  -0.00225 -0.0409 2000  .000    0
 \end{verbatim}     
\end{list}


\subsection{Command Files}

A GSS {\em  command file} is a 
list of commands identical in format to an interactive terminal session. 
It is executed from within the GSS program using the {\tt DO} command.
An example might look like:
\begin{verbatim}
CONFIG WHT CASS 
CATALOGUE TABBY.CAT
ROTATOR 90
SOURCE SIAMESE
ROTATOR 0
SOURCE ALLEY
\end{verbatim}

\subsection{Output Files}

There is a single output file for each session unless a 
deliberate change is made  using the {\tt OUTPUT} command.
This contains the following information: 
\begin{description}
\item The name or position of the target and the assumed configuration
details.
\item The J2000 positions of all of the
guide stars meeting the selection criteria, up to the specified number. 
\item The calculated guide probe coordinates for each of the guide stars 
(x y or r $\theta$).
\item The magnitudes of the guide stars (to be used in evaluating 
integration times).
\item An asterisk after the probe position indicates that the 
object is classified as stellar on all GSC plates and a ? represents an
ambiguous classification. No symbol is given for objects classified as
non-stellar on all plates.  These should only be used as guide stars in
case of dire need.
\end{description}
For example:
\begin{verbatim}


   GSS - LIST OF GUIDE STAR DATA FOR GIVEN TARGETS
 =====================================================

 Key: * = star, blank = non-star, ? = ambiguous object
 =====================================================

 Target:                      Equinox  PA   Tel  Focus
 20  0  0.00  +40  0  0.00    J2000.0  0.0  WHT  CASS      
   Date       Apx     Apy  Vmax  Vmin
 1993.060     0.0     0.0   8.0  16.0

    RA2000       Dec2000     Mag        r     theta  
 19 59 26.30  +39 51 51.59   9.72    27231.   128486.  *
 20  0 32.97  +39 51 36.04   9.88    28812.    52998.  
 20  0  7.59  +39 49 37.99  11.38    28238.    82003.  *
------------------------------------------------------

\end{verbatim}
In addition, the {\tt BLIND} command generates some additional information:
\begin{description}
\item The position of the reference star.
\item The probe offsets required to move between the reference and the target.
\end{description}
For instance:
\begin{verbatim}


   GSS - LIST OF GUIDE STAR DATA FOR GIVEN TARGETS
 =====================================================

 Key: * = star, blank = non-star, ? = ambiguous object
 =====================================================

 Reference: REFERENCE            Equinox  PA  
 20  0  0.00  +40  0  0.00       J2000.0  0.0
 Target:    TARGET               Equinox  PA  
 20  0  0.00  +40  0 10.00       J2000.0  0.0
 Tel  Focus       Date       Apx     Apy  Vmax  Vmin
 INT  CASS       1995.975    23.6     1.5   6.0  14.0

    RA2000       Dec2000     Mag        x         y      del x     del y 
 19 59 26.30  +39 51 51.59   9.72   570092.   586001.        0.     1853.  *
 20  0 32.97  +39 51 36.04   9.88   427869.   588885.        0.     1853.   
------------------------------------------------------

\end{verbatim}
Here, the guide probe coordinates are for the {\em reference} object, and del x
and del y are the amounts by which the probe should be moved in order to
acquire the target.


\noindent{\large{\bf References}}\\
\\
\noindent 
Jenkner, H. \etal, 1990. {\sl Astron. J.}, {\bf 99}, 2081.\\
Lasker, B. \etal, 1990. {\sl Astron. J.}, {\bf 99}, 2019.\\
Russell, J.L. \etal 1990. {\sl Astron. J.}, {\bf 99}, 2059.\\
Taff, L.G. \etal 1990. {\sl Astrophys.J.}, {\bf 353}, L48.\\

\newpage
\appendix
\section{Search Procedures: General}

\subsection{Definitions}

Define the following variables:
\begin{description}
\item [F] The focal length (mm).
\item [$\psi$] The sky position angle in radians.
\item [$\psi _0$] The offset between the coordinate system of the guide 
probe and that of the instrument rotator, in radians.
\item [$\epsilon$] The handedness of the guide-probe coordinate system
($\pm$1).
\item [x y] Guide probe coordinates, in encoder units.
\item [x$_{min}$ x$_{max}$ y$_{min}$ y$_{max}$] xy limits on the area
within which guide stars may be selected, in encoder units. 
\item [r $\theta$] Polar coordinates of the guide probe (encoder units;
r is positive by definition).
\item [$\theta _{min} \theta _{max}$ r$_{min}$ r$_{max}$] Limits on the
area within which guide stars may be selected, in polar coordinates; 
encoder units).
\item [e$_r$ e$_\theta$] The linear and angular encoder scales in 
mm/encoder unit and rad/encoder unit, respectively.
\item [x$_0$ y$_0$] The position of the centre of 
rotation in encoder units in the guide probe coordinate system (used for
xy systems only).
\item [r$_0$] The radial offset for guide probe coordinates, in encoder
units (used for r$\theta$ systems only).
\end{description}

All of the existing A\&G boxes on the La Palma telescopes use xy stages
for their guide probes, with the exception of the WHT Cassegrain system,
which has an r$\theta$ arrangement.   A general description of the
search areas may  be given as follows (note that not all configurations
use every constraint):
\begin{enumerate}
\item $x_{min} < x < x_{max}$ and $y_{min} < y < y_{max}$ (within a 
rectangle).
\item $[(x-x_0)^2 + (y-y_0)^2]^{1/2} \leq r_{max}$ or $r \leq r_{max}$
(within a circle: this may be either a result of vignetting or a
restriction on the mechanical travel of the probe).
\item $(x-x_0)^2/l^2 + (y-y_0)^2/m^2 > 1$ (inner ellipse excluded).  A
minimum radial travel for an r$\theta$ system is a special case.  A
similar condition, $[(x-x_0)^2 + (y-y_0)^2]^{1/2} > r_{min}$ or $r >
r_{min}$ is used for the {\tt ROTATOR ANY} option, where the available
area is always a circular annulus.
\item $x < x_-$ or $x > x_+$ or $y < y_-$ or $y > y_+$ (\ie the area $x_- <
x < x_+$ and $y_- < y < y_+$ is {\it excluded}).
\item The probe azimuth is in the range $\theta_{min} < \theta <
\theta_{max}$.
\end{enumerate}

\subsection{Conversion between equatorial coordinate systems}
\label{Astrom} 

The required conversions are between mean (FK4 and FK5) or apparent 
coordinates of arbitrary date and mean FK5 coordinates referred to equinox 
J2000 and the epoch of observation.   The algorithms used are those 
in the COCO package (SUN 56), which is based on SLALIB (\qv) subroutines.
Users should be aware of a subtle difference in the way that sky
position angle is specified for the WHT and the other two (equatorial) 
telescopes. 
The WHT is an altazimuth telescope, and corrects
continuously for field rotation.  The instrument rotators are controlled
in such a way that the position angle on the sky is defined in the
coordinate system used for the target (B1950, J2000, \etc).  The GSC
positions are in the J2000 system, and the GSS software therefore
corrects the input position angle for the effects of precession before
computing guide probe positions.  By contrast, the instrument rotators
on the INT and JKT are not designed for continuous movement, and are
left in a fixed position, independent of coordinate system.  This
effectively corresponds to adopting a sky position angle defined in
geocentric apparent coordinates, and the GSS operates on this
assumption.  Effects such as differential refraction and pointing model
corrections are not included in the GSS software, since they require
knowledge of the time of observation and the details of the telescope
models.
For most practical purposes, the definition of position angle is of
little importance, and the assumptions made by the GSS will be the most
appropriate.  Applications in which precise positioning is required over
a wide field may require a careful check to ensure that the position
angles used by the TCS, GSS and any other astrometric software are
self-consistent.  


\subsection{Choice of an initial search area}

The object here is to choose an area of sky, bounded by curves of constant 
Right ascension and Declination, which {\it just} includes the guide field.
The outer boundaries of the guide fields are either circular or rectangular 
in the tangent plane.  In the former case (except for targets near the Poles), 
the ranges of RA and Dec are given by:
\[ \Delta\alpha = \arctan(R/f\cos\delta _0) \]
\[ \Delta\delta = R/f \]
where R is the radius of the guide field and f is the focal length.  This 
formula fails for the case where $\delta _0 + R/f > \pi/2$ or 
$\delta _0 - R/f > -\pi/2$ (\ie the guide field includes one of the Poles),
in which case all stars with $\delta > \delta _0 - R/f$ (in the North) or
$\delta < \delta _0 + R/f$ (in the South) are selected.   

For rectangular guide fields, the RA and Dec of each corner are derived from
its tangent-plane position using the formulae: 
\[ \tan(\alpha - \alpha _0) =
\xi\sec\delta _0 / (f - \eta\tan\delta _0) \] 
\[ \tan\delta = \frac{\eta +
f\tan\delta _0} {[(f + \eta\tan\delta _0)^2 + \xi^2\sec^2\delta _0]^{1/2}} \]
and the widest range in each coordinate is used in the initial search.
A similar caveat
applies to guide fields around the Poles, for which the selection is 
made on Declination alone, as for circular guide fields. 

\subsection{Equatorial to tangent plane conversion}

The first step in the conversion process is to derive the {\it standard 
coordinates} $\xi$ and $\eta$ for the guide stars.   These are given by:
\[ \xi = \frac{\cos\delta\sin (\alpha - \alpha _0)}
{\sin\delta\sin\delta _0 + \cos\delta\cos\delta _0\cos(\alpha - \alpha _0)} \]
\[ \eta = \frac{\sin\delta\cos\delta _0 - \cos\delta\sin\delta _0
\cos(\alpha - \alpha _0)}
{\sin\delta\sin\delta _0 + \cos\delta\cos\delta _0\cos(\alpha - \alpha _0)} \]

\subsection{Apertures}

The objective here is to direct the light from an object of interest to a 
particular point (an {\it aperture}) in the focal plane.   Apertures are 
specified in angular units.   They cause the tangent-plane coordinates
$\xi,\eta$ to be modified to $\xi'\eta'$, as follows: 
\[ \xi' = \xi  +  (-x_A \sin\psi - y_A \cos\psi ) \]
\[ \eta' = \eta + (+x_A \cos\psi - y_A \sin\psi ) \]
where $x_A,y_A$ is the aperture position as given to the TCS.

\subsection{Radial distortion}

The standard coordinates are then corrected for the effects of radial 
field distortion:
\[ \xi' = \xi D(\rho) \]
\[ \eta' = \eta D(\rho) \]
\[ \rho = (\xi^2 + \eta^2)^{1/2} \]
These effects should be negligible for the JKT f/15, INT f/15 and WHT f/11 
foci, but corrections are required for WHT and INT Prime and JKT
f/8. In particular, WHT Prime requires precise 
location of guide stars, since the autoguider field is small. The formula:
\[ D(\rho) = 1 + a\rho + b\rho^2 + c\rho^3 + d\rho^4 \]
is appropriate, with coefficients as given in Table~\ref{Distort}.

\begin{table}
\begin{center}
\caption{Radial distortion coefficients for corrected foci.\label{Distort}}
\begin{tabular}{|l|c|c|c|c|}
\hline
&&&&\\
Configuration & $a$ & $b$ & $c$ & $d$ \\
&&&&\\
\hline
&&&&\\
WHT Prime & 1.2797 & 27.458 & 24320.0 & 0.0 \\
INT Prime &        &        &          &     \\
JKT f/8   & 0.0    & 13.32   & 0.0     & 0.0 \\
&&&&\\
\hline
\end{tabular}
\end{center}
\end{table}


\subsection{Conversion to guide-probe coordinates}

The $\xi'\eta'$ coordinate system are then rotated, translated and 
scaled to the guide probe system, using the relations:
\[ x =(f/ e_r) [\xi'\cos(\psi + \psi _0) - \eta'\sin(\psi + \psi _0)] + x_0  \]
\[ y =\epsilon (f/ e_r) [\xi'\sin(\psi + \psi _0) + \eta'\cos(\psi +
\psi _0)] + y_0  \]
\[ r = [(x-x_0)^2 + (y-y_0)^2]^{1/2} \]
for xy systems and
\[ x =(f/e_r) [\xi'\cos(\psi + \psi _0) - \eta'\sin(\psi + \psi _0)] \]
\[ y = (f/e_r)[\xi'\sin(\psi + \psi _0) + \eta'\cos(\psi + \psi _0)] \]
\[ r = (x^2 + y^2)^{1/2} - r_0 \]
\[ \sin{e_{\theta}\theta} = x / (x^2 + y^2)^{1/2} \]
\[ \cos{e_{\theta}\theta} = y / (x^2 + y^2)^{1/2} \]
for $r\theta$ systems.

\section{Detailed description of the search areas}

\subsection{Tables}

The current best estimates for these parameters are given in Tables~\ref{xy1}
-- \ref{rt2} and the associated notes.

\begin{table}
\begin{center}
\caption{Limiting magnitudes, plate scales and encoder scales (xy
systems).\label{xy1}}
\begin{tabular}{|l|c|r|l|l|r|}
\hline
&&&&&\\
Configuration & Magnitude & Focal      &e$_r$&$\epsilon$&$\psi _0$\\
              & range     & length/mm  &     &          & rad     \\
&&&&&\\
\hline
&&&&&\\
WHT PRIME & 6.5 -- 14.5 & 11624.5 & +0.001 & $-$1 & 3.0931 \\
WHT UESPROBE &  6.5 -- 16.5&46257&+0.0009806&--1&
-1.5906\\
INT PRIME     &  6 -- 14  &8357 &+0.0393&+1&
4.71239\\
INT CASS &  6 -- 14  &38216&+0.001 &+1 &
3.14159\\
JKT WFCE  &  5 -- 13  &8060 &+1.0   &--1   &
6.250\\
JKT WFCW  &  5 -- 13  &8060 &+1.0   &--1   &
3.108\\
JKT CCDE &  5 -- 12  &15000&+0.005 &+1 &
0.000\\
JKT CCDW &  5 -- 12  &15000&+0.005 &+1 &
3.141\\
&&&&&\\
\hline
\end{tabular}
\end{center}
\end{table}

\begin{table}
\begin{center}
\caption{Limiting magnitudes, plate scales and encoder scales 
(r$\theta$ systems).\label{rt1}}
\begin{tabular}{|l|c|c|l|l|l|c|}
\hline
&&&&&&\\
Configuration & Magnitude & Focal       &e$_r$&e$_\theta$&
$\epsilon$ & $\psi _0$\\
              & range     & length/mm   &&     &    & \\
&&&&&&\\
\hline
&&&&&&\\
WHT CASS& 8 -- 16  & 45738 &
0.001 &$\pm 1.7453\times 10^{-5}$& +1 &1.57996\\
WHT AUXPORT& 8 -- 16  & 45738 &
0.001 &$\pm 1.7453\times 10^{-5}$& +1 &1.57996\\
WHT TAURUS& 8 -- 16  & 45738 &
0.001 &$\pm 1.7453\times 10^{-5}$& +1 &$-$0.01876\\
&&&&&&\\
\hline
\end{tabular}
\end{center}
\end{table}

\begin{table}
\begin{center}
\caption{Guide probe offsets and limits (xy systems).\label{xy2}}
\begin{tabular}{|l|c|c|c|c|c|c|}
\hline
&&&&&&\\
Configuration  &x$_{min}$&x$_{max}$&y$_{min}$&y$_{max}$&x$_0$&y$_0$\\
&&&&&&\\
\hline
&&&&&&\\
WHT PRIME    & 0 & 110000 & 0 & 20000 & 56401 & 97417 \\
WHT UESPROBE & 0       & 73600   & 0       & 71000   &
35939 & 34844 \\
INT PRIME      & 550     & 1850    & 900     &  1850   &
512 & 281\\
INT CASS & 405000  & 595000  & 405000  & 595000  &
497919 & 499938\\
JKT WFCE/W       &  139.1  & 240.0   &  90.8   & 180.0   &
142.9 & 96.9 \\
JKT CCDE/W       &  1      & 29200   &  1      & 29200   &
14146 & 13000 \\
&&&&&&\\
\hline
\end{tabular}
\end{center}
\end{table}

\vspace{1cm}

\begin{table}
\begin{center}
\caption{Guide probe offsets and limits (r$\theta$ systems).\label{rt2}}
\begin{tabular}{|l|c|c|c|c|c|c|c|}
\hline
&&&&&&&\\
Configuration  &r$_{min}$&r$_{max}$&$\theta_{min}$&$\theta_{max}$&
x$_0$&y$_0$&r$_0$\\
&&&&&&&\\
\hline
&&&&&&&\\
WHT CASS & 0 & 40000 & 30000 & 180000 & 0 & 0 & 112040 \\
WHT AUXPORT    & 0 & 40000 & 0     & 180000 & 0 & 0 & 112040 \\
WHT TAURUS    & 0 & 40000 & 0     & 180000 & 0 & 0 & 112040 \\
&&&&&&&\\
\hline
\end{tabular}
\end{center}
\end{table}

\subsection{Notes}
\label{Geometry}

\subsubsection{WHT CASS} 

The travel of the  autoguider probe defines a semi-annulus (see above). 
Note, however, that the probe can obstruct  the slit-viewing optics (not
the slit itself) for  $\theta < 30000$, giving an additional azimuth
restriction.   The excluded inner  region (a circle) is 
treated as a special case of the ellipse  mentioned earlier, with $l = m$.

\subsubsection{WHT AUXPORT}

This configuration is identical to the previous one, except for the absence of
a lower limit to $\theta$ (the slit viewing optics are not used).

\subsubsection{WHT TAURUS}

This is identical to WHT AUXPORT except for a different position-angle offset
(the PA reference is defined by the Taurus detector, rather than the ISIS slit
unit).

\subsubsection{WHT UESPROBE}

The limits on the search area are set by the autoguider probe x and y
travel and vignetting by the derotation optics. 
They should also be affected by the shape of the central
aperture in the autoguider mirror, for which there are several alternatives.
Since this is not in focus, partial vignetting of the guide star occurs, and
the effects are complicated.  For the moment, no correction is implemented.

\subsubsection{INT PRIME}

The search area is a rectangle in the unvignetted field and the
guide probe cannot obscure the CCD Camera.   The only conditions on x and y
are therefore: 
\[ x_{min} < x < x_{max} \]
\[ y_{min} < x < y_{max} \]
Vignetting sets the value of $r_{max}$.
Note that the aperture offset to the centre of the detector depends on the
chip and is large.  

\subsubsection{INT CASS}

The outer boundary of the guide probe field is set by the onset of 
vignetting (no vignetting at 10 arcmin 
radius; 50\% at 11 arcmin, so $r_{max} = 3.1998\times 10^{-3}$ rad) 
for the latter figure and the xy limits.   The inner
boundary of the field is set by the need to avoid obstructing the
spectrograph slit with the guide probe, giving a rectangular 
excluded area.  The full 4 arcmin length of the slit has been used in
calculating the size of the inner boundary.


\subsubsection{JKT f/8 (WFCE and WFCW)}

The guide field is a rectangle defined by the range of travel of the guide
probe, with a smaller rectangle chopped out of one corner so as to avoid
vignetting of the central region of the field. The additional condition excludes
the region with: $x < x_+$ and $y < y_+$, with x$_+$ = 156.9 mm and y$_+$ =
111.4 mm. Note that the ``encoder scale'' quoted for the JKT f/8 (WFC)
configurations  is not a bit size.  The WFC guide probe is positioned manually
and its  location is read in mm.

\subsubsection{JKT f/15 (CCDE and CCDW}

The outer edge of the field is a circle of radius 16 arcmin (defined by the
filter wheel).   The guide probe is on an xy stage and can
cover all of this area except for a small part outside its -y range and a
cut-out at large x and y.  The inner edge of the field is elliptical with a
semi-major axis of 14 arcmin along x and a semi-minor axis of 10 arcmin
along y. The ellipse is produced because the autoguider is fed
by a flat mirror with a circular hole inclined at \degs{45} to the optical
axis. The additional conditions are: 
\[x^2/l^2 + y^2/m^2 > 1 \]
\[ x^2 + y^2 < r_{max}^2 \]
and the area with $x > x_+$ and $y > y_+$ is also excluded.

\subsubsection{NONE: simple search}

This application selects all stars within a given angular radius of the  target
position.   Applications are production of finding charts, and selection of
reference stars  for the MARTINI image-sharpening instrument and for blind
offsetting.  The plots are labelled in arcsec from the target position.

\section{The CONFIG.DAT file}

Configuration parameters will change from time to time, usually as a result of
mechanical modifications, and additional configurations are likely to be added.
The definitive list of configurations is held in the file GSS\_DIR:CONFIG.DAT,
which may be read or printed.  Each configuration is defined by a block
starting with {\tt CONFIG}.  The variables defining the configuration are then
listed, in fixed order, with variable names as comments.   The translation
between variable names and the symbols used earlier is given in
Table~\ref{Translate}.  Note that the variables RVEL, THVEL, XVEL and YVEL are
used only by the TAG I-task.

\begin{table}
\begin{center}
\caption{CONFIG.DAT variable names.\label{Translate}}
\begin{tabular}{|l|l|l|l|}
\hline
&&&\\
Variable name & Symbol & Unit & Notes \\
&&&\\
\hline
&&&\\
FOCLEN & F & mm & \\
XY FLAG &  &    & F for $r\theta$; T for $xy$ systems \\
PA\_OFFSET & $\psi_0$ & rad & \\
FLIP & $\epsilon$ & & \\
PA\_COORD\_SYS &  &  & T for moving rotator \\
SCALER & $e_r$ & mm/bit & \\
SCALETH & $e_\theta$ & rad/bit & \\
RADA & $a$ & & \\
RADB & $b$ & & \\
RADV & $c$ & & \\
RADD & $d$ & & \\
X0 & $x_0$ & bits & \\
Y0 & $y_0$ & bits & \\
R0 & $r_0$ & bits & \\
XMIN & $x_{min}$ & bits & \\
XMAX & $x_{max}$ & bits & \\
YMIN & $y_{min}$ & bits & \\
YMAX & $y_{max}$ & bits & \\
RMIN & $r_{min}$ & bits & \\
RMAX & $r_{max}$ & bits & \\
THMIN & $\theta_{min}$ & bits & \\
THMAX & $\theta_{max}$ & bits & \\
LAXIS & $l$ & bits & \\
MAXIS & $m$ & bits & \\
XMINUS & $x_-$ & bits & \\
XPLUS & $x_+$ & bits & \\
YMINUS & $y_-$ & bits & \\
YPLUS & $y_+$ & bits & \\
X\_AP & $x_A$ & rad & \\
Y\_AP & $y_A$ & rad & \\
V\_MIN & V$_{min}$ & mag & \\
V\_MAX & V$_{max}$ & mag & \\
MIN\_SEP &  & rad & Minimum separation \\
NUM\_STARS & & & Number of stars \\
&&&\\
\hline
\end{tabular}
\end{center}
\end{table}


\section{Example Plots}

\clearpage
\begin{figure}
\vspace{20cm}
\special{psfile=wht_cass.ps hoffset = -50 voffset = -100}
\caption{WHT CASS configuration.\label{WHT-CASS}}
\end{figure}

\begin{figure}
\vspace{20cm}
\special{psfile=wht_auxport.ps hoffset = -50 voffset = -100}
\caption{WHT AUXPORT configuration.\label{WHT-AUXPORT}}
\end{figure}

\begin{figure}
\vspace{20cm}
\special{psfile=wht_taurus.ps hoffset = -50 voffset = -100}
\caption{WHT TAURUS configuration.\label{WHT-TAURUS}}
\end{figure}

\clearpage
\begin{figure}
\vspace{20cm}
\special{psfile=wht_prime.ps hoffset = -50 voffset = -100}
\caption{WHT PRIME configuration.\label{WHT-PRIME}}
\end{figure}

\begin{figure}
\vspace{20cm}
\special{psfile=wht_uesprobe.ps hoffset = -50 voffset = -100}
\caption{WHT UESPROBE configuration.\label{WHT-UESPROBE}}
\end{figure}

\begin{figure}
\vspace{20cm}
\special{psfile=int_cass.ps hoffset = -50 voffset = -100}
\caption{INT CASS configuration.\label{INT-CASS}}
\end{figure}

\clearpage
\begin{figure}
\vspace{20cm}
\special{psfile=int_prime.ps hoffset = -50 voffset = -100}
\caption{INT PRIME configuration.\label{INT-PRIME}}
\end{figure}

\begin{figure}
\vspace{20cm}
\special{psfile=jkt_ccde.ps hoffset = -50 voffset = -100}
\caption{JKT CCDE configuration.\label{JKT-CCDE}}
\end{figure}

\begin{figure}
\vspace{20cm}
\special{psfile=jkt_ccdw.ps hoffset = -50 voffset = -100}
\caption{JKT CCDW configuration.\label{JKT-CCDW}}
\end{figure}

\clearpage
\begin{figure}
\vspace{20cm}
\special{psfile=jkt_wfce.ps hoffset = -50 voffset = -100}
\caption{JKT WFCE configuration.\label{JKT-WFCE}}
\end{figure}

\begin{figure}
\vspace{20cm}
\special{psfile=jkt_wfcw.ps hoffset = -50 voffset = -100}
\caption{JKT WFCW configuration.\label{JKT-WFCW}}
\end{figure}

\begin{figure}
\vspace{20cm}
\special{psfile=none.ps hoffset = -50 voffset = -100}
\caption{Configuration NONE.\label{NONE}}
\end{figure}
\clearpage


\end{document}
