Here are some helpful hints for using the SONIC.

DARKS:

You should take dark frames at the beginning and end of the night and
probably at least once in the middle.  Make sure you have dark frames at
every frametime you use for taking data.  A convenient way to take the
darks is to use the command "darks", which executes a file called "dark"
in your home directory.  If you don't have such a file, or if it is
messed up, copy the one in ~willner.  Lines can be commented out by
placing a '#' character (without the quotes) at the beginning of the
line.  It is better to comment out unwanted lines than to delete them,
since you or someone else may want them in the future.

Before starting "darks", make sure the filter is moved to the BLK
position and that the comments are up to date.  (The script _may_ update
the object name in the comment file; it _does_ force the file name to be
DARK or BIAS.)

Typical frame times are 1, 10, and 30 seconds.  Combine as many frames
as you have patience to do (better statistics).  Also, take some bias
frames at 0.2 seconds frame time.

See PATCH for suggestions on monitoring the data.

PATCH:

You can monitor data from dark or other frames by using the "patch"
command.  See "help data patch" for details.  A convenient alias is
"pp", which does a patch of a region without bad pixels and with equal
numbers of even and odd columns.  Another convenient alias is "dp",
which moves data from the integration buffer and then does "pp".  Note
that dp works while in tv mode; this is quite useful for setting gate
voltage.

GATE VOLTAGE:

See discussion in "startup.txt".  At present, the operating gate voltage
is -1.4 volts.  Remember to set it to a more negative value (say -1.6),
then come back positive to -1.4.

DISPLAY SCALE:

Convenient aliases for setting the display scale are "obj" for faint
objects, "o" for typical objects in tv mode, and "std" for observing
standards in both object and sky beams.

BEAM:

The status display highlights which beam (object/sky) the data system
thinks you are observing.  If you accidentally swap the two, don't
worry.  Just store the data normally, make sure you are in tonight's
directory ("dlink now"), and edit the comments ("oldcom <file number>").
Find the keyword "SWAPPED", and change its value from "F" to "T".  Now
when you read the data into iraf with "rira", the object exposure will
be correctly placed into the "a" file and the sky into the "b" file.

Before starting the next integration, use "bt" to get yourself back in
sync.

OFFSET FILES:

There are a number of useful offset files for common procedures.  The
files are located in ~willner/cats/*.off, where you cannot ordinarily
modify them.  The default catalog directory /Realtime/lib/catalogs
contains symbolic links to these files, meaning that you can use them
just as if they were in the default directory.

One offset file called "std" observes standards (or objects!) in eight
positions on the array, avoiding bad pixels.  To use it, set the star
image on pixel (31,29) (the exact middle of the array), and do your
first integration.  The first seven offsets in the file move the star to
various locations around the array, and the eighth moves it back to the
center.  You can thus use the file repeatedly for different filters or
simply to repeat a series of observations.

Offset files beginning with "bs" are intended for object/sky
beamswitching.  They are labeled with the beam switch distance in arcmin
and the direction.  Finally, a "d" is appended if the file will dither a
small distance around the object location.  No "d" means only the sky
positions will be dithered.  Thus "bs4nd" will beam switch 4 arcmin to
the north and dither.

To use the dither files, choose one from the offset menu in tcs.  Set up
on the object and start an integration in the normal way ("go <time>").
When the integration finishes, move the first offset in the catalog, and
start the sky integration with "ss".  When that finishes, store the data
("sd"), move the next offset, and start the next sky integration.
Continue in this pattern, doing an offset after _every_ integration.

To use the non-dither files, proceed as above except that there is _no
offset_ between two _object_ integrations.

The set of beam switch files (and other offset files, for that matter)
is by no means complete.  If you make more, please label them
consistently and email me (willner@cfa) to tell me what you have done.
I'm glad for any assistance.

TEMPERATURE:

The temperature control system is generally reliable, but it does have a
few idiosyncracies.  For detailed information, see the file
~willner/temp.txt.

If the power goes off, the cooler will stop.  Normally it will come back
on by itself as soon as the power comes back, but it may take up to half
an hour for the temperature to restabilize.  You can speed up the
process by judicious use of "killirholdtemp" and "tsonic".

ALIASES:

Almost all the useful commands are aliases.  If you have forgotten a
command name, try typing "alias" in the command window to see a list of
all aliases defined.  Chances are the command you want will be there.
And of course "help" produces detailed information.

Feel free to create your own aliases and save them ("writealias").  If
you write them to the file "~/.sonic.alias", they will be automatically
loaded when you start up the realtime system.  If you invent aliases
that will be generally useful, please let me know.  If you want only the
standard aliases, delete the .sonic.alias file.


FRAME TIMES:

Frametime (command "ft", header parameter "FRAMERAT") is the on-chip
integration time.  The chip is non linear in two respects: 1) each
frame has a bias (zero point) of about 900 counts, and 2) there is a
saturation at large signals.

"EXPOSURE" (the time given after "go" rounded up to an integer number
of frames) is simply an addition in the computer of an integer number
of frames.  It is obviously linear, and since it uses 32-bit arithmetic,
there is no danger of overflow.

The bias correction is just to subtract a zero point.  This is
normally found from dark frames at 0.2 sec frametime.  Normally I add
up 100 of them, since it only takes 20 seconds, and the noise in the
bias contributes to the noise of every frame.  The bias correction
_per frame_ is then the bias file divided by 100.

The non-linearity correction is basically like the saturation of a
photomultiplier, though the physical cause is different.  The
correction is 2 or 3% at 10,000 counts per frame.  Around 15,000
counts per frame the detector is completely saturated.  One needs to
be careful when measuring standards to keep the count rate below
12,000 counts per frame and preferably lower.  Some standards must be
measured with shorter frame times than 1 second.

Deriving the actual non-linearity coefficients is a little tricky.
Olga and I are working on it separately, but I have one answer that
is probably close.  The basic idea is to measure a constant signal
with different frame times.  If there were no non-linearity, the
signal per frame above bias would be linearly proportional to frame
time.  In fact, the signal decreases as the count rate approaches and
exceeds 10,000 counts per frame.  We need to fit to a function like
  (expected count rate) = (actual count rate) * (1 + a2*x + a3*x^2)
where x is (counts per frame) / 10000, and the coefficients a2 and a3
are derived separately for each pixel.  As I say, we are still
working on deriving coefficients and seeing how constant they are.

Once the coefficients are derived, the iraf task "saotdc.procdata.ircorrect"
will automatically normalize to a single frame, subtract bias, and 
correct for non-linearity.

QUESTIONS

[This is a compilation of questions and answers in no particular order.]

> How do I display a file I have recalled with rfile? Can I do 
> this from the cominterp or do I have to use IRAF.

You have to use "wfits" to write the working buffer out as a fits
file, then you can use saoimage to display it.  You may want to use
"l-r" first to perform a sky subtraction.  You can do other
arithmetic (e.g. flat-fielding) too.  As far as I know, saoimage will
only display the first ("object") image plane.

> I can't get oldcom editor to work. Is there another
> way to change a file name? I have several times forgot to set
> object before starting a new exposure.

Are you sure you are in the right directory (dlink)?  You have to use
:w! to write the file, then :q to quit the editor.  (Yes, it's a nuisance.
Complain to Nelson.)  If that doesn't work, use the command "fitsheadedit"
in a shell window.  It works the same way, so you still have to use
that cumbersome procedure to exit.

Actually, I think there may be a way to get a different editor instead
of vi.  Try setting the VISUAL or maybe EDITOR environment variables
to the full path of some other editor.  No guarantees on this one.