Macros are simple ASCII files which send commands to control the instrument
and/or the telescope. Examples of macros that can be used with NSFCam and CSHELL
are given below. The commands to control the instruments are straightforward, as
they are simply the instructions an observer would type on the command
line in the instrument GUI (e.g., go, autosavexui on, etc.). The commands
to control the telescope, however, must be written in a special format
that the Telescope Control System (TCS) can understand. All of the commands
to move the telescope must be prefaced by "tcs". The most important command
for moving the telescope - one that will be used by everyone who wishes to
dither in order to construct a mosaic of a field or to shift the positions of
objects along a slit - is described in detail at the bottom of the page.
However, observers should be able to construct their own macros simply
by copying and modifying the examples given here.
Note that the TCS is written in FORTH. Therefore, the formats of the numerical
parameters must be rigorously obeyed as described, even to the presence or
absence of the decimal point and the number of places allowed after a decimal
point.
Here is a macro that can be used with NSFCam to do a 7 point on-source
dither. The macro specifies the observing mode (Obsmode 0, which
indicates that there is no chopping to sky), turns on the autosave,
and sets the cycles to 1. The tcs ABEAM tells the telescope control
system that the observations will start and take place in the A beam (on source).
The next line (tcs 1 0.0 0.0 -1 C.SCN) tells the telescope
to move 0 arcsec east and 0 arcsec north from the current position and
informs the tcs that this first position should be the base position from
which all further telescope movements should be measured. (A detailed
description of these so-called SCAN commands is given at the bottom of the
page.) The macro then instructs the camera to wait 2 seconds for the telescope
to settle at the position, and then to take an image (go). The next
line ( tcs 1 0.0 10.0 1 C.SCN ) moves the telescope 0 arcsec east
and 10 arcsec north from the base position. After another image is obtained,
the telescope is moved 8.7 arcsec east and 5.0 arcsec north of the base position.
At the end of the macro, the telescope is moved back to the base position
(tcs 1 0.0 0.0 1 C.SCN).
If the observer wanted to chop to sky between exposures of the source, s/he would replace Obsmode 0 with Obsmode 2 and remove the line tcs ABEAM. Everything else could remain the same.
Obsmode 0 autosavexui on cycles 1 tcs ABEAM tcs 1 0.0 0.0 -1 C.SCN wait 2 echo P#1 go tcs 1 0.0 10.0 1 C.SCN wait 2 echo P#2 go tcs 1 8.7 5.0 1 C.SCN wait 2 echo P#3 go tcs 1 8.7 -5.0 1 C.SCN wait 2 echo P#4 go tcs 1 0.0 -10.0 1 C.SCN wait 2 echo P#5 go tcs 1 -8.7 -5.0 1 C.SCN wait 2 echo P#6 go tcs 1 -8.7 5.0 1 C.SCN wait 2 echo P#7 go tcs 1 0.0 0.0 1 C.SCN echo Done.
Here is a macro that can be used with CSHELL to acquire spectra of a source at two different positions along the slit. Note that the observer wants to chop to sky between the source exposures. (For CSHELL, Obsmode = 1 is the chopping mode.) The macro puts the instrument in the spectroscopic mode ( InstMode S), and sets the slit size to 1 arcsec, the number of cycles to 1, and the observing mode to 1 (for chopping to sky). Autosave is turned on, and the current position is defined as the base. After a 2 sec pause, an image is taken. Then the telescope is moved 8 arcsec east and 0 arcsec north of the base and another image is taken, etc.
InstMode S Slit 1.0 Cycles 1 Obsmode 1 AutoSaveXUI On tcs 1 0.0 0.0 -1 C.SCN wait 2 echo Pair #1: Base Position go tcs 1 8.0 0.0 1 C.SCN wait 2 echo Pair #2: 8 arcsec E of Base go tcs 1 0.0 0.0 1 C.SCN echo Done.
NOTE: When using the offset guider, it is not possible to reset the base position (i.e., to zero the offsets) after guiding has started. Doing so will cause the guider to fail to track the guide star. If the observer wishes to shift the telescope position and define a new base at the new position after guiding has started (if, for example, the observer wanted to adjust the location of the object on the array or acquire multiple dither sets on the same object, with each set slightly offset from one another), s/he should inform the TO to stop guiding, re-acquire the guide star, and re-start guiding. This will zero the offsets in the guider and the telescope, and then the macros given above can be used. Alternatively, the observer could re-write the macros to incorporate only relative offsets from the last position. For example, in this mode, the NSFCam macro given above would be re-written as follows:
Obsmode 0 autosavexui on cycles 1 tcs ABEAM wait 2 echo P#1 go tcs 1 0.0 10.0 0 C.SCN wait 2 echo P#2 go tcs 1 8.7 -5.0 0 C.SCN wait 2 echo P#3 go tcs 1 0 -10.0 0 C.SCN wait 2 echo P#4 go tcs 1 -8.7 -5.0 0 C.SCN wait 2 echo P#5 go tcs 1 -8.7 5.0 0 C.SCN wait 2 echo P#6 go tcs 1 0.0 10.0 0 C.SCN wait 2 echo P#7 go tcs 1 8.7 -5.0 0 C.SCN echo Done.
Arguments:
r is a reply code:
r=0 for immediate reply.
r=1 to wait for this scan motion to complete before replying.
sss.s: RA arcseconds displacement, then dec arcseconds. (Note,
only one place after the decimal point is allowed.)
c is a command code:
c=0 for relative displacement.
c=1 for absolute displacement.
c=-1 to intitalize the current scan position without moving
telescope (defines this as scan base position).
Displacements are positive for East and North. The displacement given for RA should be the on-sky displacement. This value will be divided by cos(dec) to produce a coordinate difference for output to the telescope.
Scanning patterns in the sky are done with this command. The scan motions are independent of offsetting or beamswitching. The displacements sss.s arcseconds are with respect to the scan base position when using 1 for argument c, and are with respect to the previous scan position when using 0 for this argument.
To specify the current telescope position as the scan base reference, -1 is used for argument c. In this case, the values of sss.s for RA and dec are "don't care".
To cause the telescope to return to the scan base position, the arguments should be r 0.0 0.0 1, where r is either 0 or 1.
Example: tcs 1 21 .3 -100.0 0 C.SCN
Returns the -OK from the TCS after the scan motion is
complete. The telescope is moved 21.3 arcseconds east and 100.0
arcseconds south of its previous scan position.