INS-DAS-25:

Configuration files for UltraDAS

Introduction

Purpose of this document

The syntax and semantics of UltraDAS' configuration files are defined.
The validity of the UltraDAS software may be judged against this
specification.
ING staff who need to set up an UltraDAS installation should consult
this
document for to find the proper usage of the configuration files.

Scope of the interface

The configuration files are used by server programmes in UltraDAS. At
the
time of writing, the consumer programmes are udas_server (of
the
DAS) and udas_hct (of the CIA). The client programmes of
UltraDAS
also sometimes use the configuration files.

The section on co-ordinate spaces and mappings is completely
rewritten
to describe a new notation.

The pixsize, chiptype and shutter keywords were
added.

The ndr keyword was added.

The trimsec keyword was added.

The definition of biassec was changed.

The bitpix and pixelskip keywords were added.

The ccdcprog_gen
keyword was added

Names, location and purpose of the files

The configuration files adapt generic UltraDAS programmes to particular
instruments and cameras and to the computing environment at particular
telescopes. The files are installed with the UltraDAS software, but are
not subject to the same version control strictures as the compiled
software.
It is intended that support staff can edit the configuration during the
lifetime of a particular version of an observing system, and that this
does not require a re-release of the system or a formal patch.

The configuration files are all kept in /int/etc, /jkt/etc or
/wht/etc, as befits the telescope they serve. There is a
separate
installation of configuration files for each telescope. UltraDAS
requires
that there also be a directory /INT which is a link to /int
(or /JKT linked to /jkt, or /WHT linked to /wht).
That is, when UltraDAS programmes look for the configuration files they
may use either upper or lower case (but not mixed case) for the name of
the telescope.

An UltraDAS installation uses only the file-tree for the telescope
it
serves. For example, UltraDAS at the INT does not need to see /jkt or
/wht.

The files are kept higher up in the file-trees than the observing
systems
and the patches; that is, the location is, e.g., /int/etc
rather
than /int/s8-1/etc. This is deliberate: the configuration files
are shared between versions of the observing system and do not need to
be re-installed when a new system-version is released.

All the configuration files have names beginning with "udas_"
and ending in ".dat".

There is one configuration file for the host computer as a whole:
its
is called udas_<host>.dat, where <host>
stands for the
last part of the name of the computer. For example, the DAS
computer
at the INT is, at the time of writing, lpss14. The configuration file
for
this /int/etc/udas_lpss14.dat. The host-name embedded in the
file-name
must be that returned by the function gethostname(3C).
The host-configuration
file describes aspects of the system that are common for all
instruments
and cameras. Typically, this file just lists the data discs
available
on a given DAS computer (via the obsdata statement). The file
must
be present for each node used by UltraDAS even if there are no
statements
to put in it. This means that the system computer (where udas_hct runs)
has to have a host-configuration file separately from the DAS computer.

There is one configuration file for each supported instrument;
UltraDAS
will work badly, or may refuse to work at all, if the instrument
configuration
is missing. The file-name embeds the formal name of the instrument:
e.g.
udas_IDS.dat;
note
the capitalization: case is significant.The instrument
configuration
contains data that are specific to the instrument but are independent
of
the choice of camera.

There is one configuration file for each supported camera. UltraDAS
cannot drive a camera for which it does not have a configuration. The
file-name
embeds the formal name of the camera: e.g. udas_EEV11.dat; note
the capitalization: case is significant. For symmetry, and
because the configuration code is the same in all programmes, UltraDAS
treats the header-collection task (HCT) as an honorary camera: the
"camera"
configuration udas_HCT.dat must exist (but is typically an
empty
file).

In some cases, the instrument configuration and the camera
configuration
may be the same file: e.g. udas_WFC.dat and udas_INGRID.dat

The files are read in the order host-instrument-camera. It is
commonplace
for udas_hct to read more than instrument-configuration, and udas_server
may
do so. A given programme reads only one camera configuration. Some
statements
may be countermanded if they appear in more than one
configuration-file;
in this case, the system uses the version of the statement that it read
last. If the instrument configuration and the camera configuration are
the same file, then the system may read and parse it twice: this has
the
same effect as just reading the file once.

The syntax of the files

The three types of configuration - system, instrument and camera - use
the same syntax, and any configuration statement
that is valid in one file is syntactically valid in any of them.
However, not all statements make semantic sense in all the files.

The configuration files are ASCII text-files and should contain only
printing characters; tab characters are acceptable as white space. The
files may be edited using ordinary text-editors.

The files are broken into statements separated by the standard
new-line
character for the operating system of the underlying computer. Each
statement
completely defines one aspect of the configuration. No statement is
split
between two lines and there are no dependencies between lines that
effect
the parsing.

Lines beginning with a hash character are comments. These are
ignored
by the parsing software, as are blank lines.

Lines of valid configuration consist in a series of words separated
by white space. The word separators may contain any number of
white-space
characters.

The first word is always an integer giving the number of a readout
channel.
Some configuration statements are specific to one readout channel of a
camera, and the number specifies the channel. For statements that are
not
specific to one channel, the number must be present but its value is
ignored
by the parsing software; by convention, these numbers should be set to
zero in the file.

The second word is always a keyword defining the intent of the
statement.
Case is significant; the keywords must always be in lower case.

The third and subsequent words associate values with the keyword and
their syntax varies from keyword to keyword.

The syntax and semantics of particular configuration statements

ampsize

This defines the size and shape of the raster produced from a
particular
readout channel (i.e. from one amplifier of the detector) when windows
and binning are not being applied. The third word of the statement is
the
size in pixels in the x direction and the fourth word is the
size
in pixels in the y direction. These directions are defined in
amplifier
co-ordinates. That is, the faster-varying pixel-coordinate in the
readout
is x and the slower-varying is y, regardless of how the
raster
is arranged on the the detector.

Example:

1 ampsize 1076 4096

There must be one ampsize statement for each readout channel.
If
an amplifier does not have an ampsize statement then UltraDAS
understands
that no pixels from that amplifier will be sent from the detector
controller
to the DAS under any circumstances.

ampname

This states the name for one amplifier of the detector: the name is the
third word of the command. C.f. ccdname. This datum is carried
through
the system, into the FITS descriptor "AMPNAME".

Example:

1 ampname Left-hand

There should be one ampname statement for each readout channel.

aspace

This describes the amplifier co-ordinate-space for one amplifier in
terms
of the mapping from a-space to detector space. See below for a
discussion
of the syntax.

Example:

2 aspace -1 0 1 1 2048 0

There should be one aspace statement per readout channel.
If a channel has no aspace statement, then its amplifier space
is
taken to have the same origin, scale and alignment as detector space.

biassec

This states the bias section - i.e. the unlit area of the image from
which
the bias level should be estimated - for one channel. Four areas
are listed, one for each side of the channel's readout section, and the
system will pick the one with the largest intersection of a particular
observation (i.e. the choice changes with windowing). The first
section
listed is for the left-hand side of the readout section and the others
follow round in a clockwise direction. Each area is described by an
IRAF-style
image section, in the readout co-ordinates of the channel to which it
applies.
If there is no bias section on a particular side, the section should be
given as [0:0,0:0].

says that the bias sections runs from x =15 to x=45
inclusive
and y=20 to y=4180 inclusive etc: these might be
appropriate
for an EEV4280 CCD which has both underscan and overscan in x
but
only overscan in y.

Each channel should have exactly one biassec statement if
bias is extracted from unlit pixels, as is normal with CCDs. If, as
with
IR arrays, bias is extracted from a separate readout, then no biassec
statements should be used for the camera in question.

bitpix

This states the pixel format in which the data should be written to
FITS
files. The datum is the number of bits per pixel, made positive for
integer
formats and negative for floating-point formats. The only proper values
are 16 and -32.

Example:

0 bitpix -32

says that all images should be in 32-bit floating-point format.

If bitpix is not given, the default format depends on what has been
done to the data. Any observations in which images have been coadded or
covaeraged will come out as 32-bit floating point numbers; all other
observations
will come out as 16 bit integers.

ccdcid

This defines the numeric identifier for a detector controller. UltraDAS
uses this to distinguish the controller when more than one is connected
to the DAS computer, and also to check that the correct controller is
connected.
The third word of the statement is read as an unsigned integer and the
least-significant eight bits must match the code wired into the
camera's
ID-plug.

Example:

0 ccdcid 0x2b

Ccdcid statements should only be put in camera configurations.

ccdcprog

This specifies programme ("lod") files to be run on the two DSPs in the
detector controller. The third word specifies the programme for the
timing
DSP and the fourth word specifies the programme for the utility DSP.
The
programme names must include the file-name extension .lod but
must
not specify the directory in which the programmes are kept (UltraDAS
looks
for the programmes along the user's search-path).

Example:

0 ccdcprog udas_eev42_dual_timing.lod udas_utility.lod

Ccdcprog statements are usually found only in camera
configurations.

ccdcprog_gen

This specifies programme ("lod") files to be run on the two DSPs in the
detector controller. The third word specifies the generation number of
the controller. The fourth word specifies the programme for the timing
DSP and the fifth word specifies the programme for the utility DSP. The
programme names must include the file-name extension .lod but
must
not specify the directory in which the programmes are kept (UltraDAS
looks
for the programmes along the user's search-path).

This command was added to UltraDAS following the introduction of Gen
III SDSU camera controllers, since the old GEN II and the new Gen III
controllers require different DSP files. This command allows a camera
to be used with either Gen II or later generation (3, 4, 5 etc.. )
controllers. If a camera is required to be used by both Gen II and Gen
III controllers, then the configuration file should contain a ccdcprog entry for the Gen II DSP
files, and a ccdcprog_gen entry for the Gen III
DSP files.

Example:

0 ccdcprog_gen 3 udas_CCD4710_timing3.lod udas_CCD4710_utility3.lod

ccdcprog_gen statements are usually found only in camera
configurations.

ccdname

This names a particular detector-chip within the camera: the name is
the
third word of the statement. C.f. ampname. This datum is
carried
through the system into the FITS descriptor "CCDNAME".

Example:

1 ccdname "WFC-1"

There should be one ccdname statement for each readout channel.
Where two or more channels come from one chip, they each have a ccdname
statement with the same value.

chiptype

This sets for one channel the chip-type string that is copied to the
FITS-header
keyword CCDTYPE. The third word is the value of the statement that is
copied
to FITS.

Example:

1 chiptype "HAWAII-2"

clearreads

This sets the number of clearing reads to be performed before a run,
multrun,
or coaverage sequence. This is provided to reduce the effects of image
persistence that are seen on the Hawaii infrared arrays. The clearing
reads
will only be performed for ndr cameras. See ndr configuration keyword.

Example:

0 clearreads 3

display

This sets the name of the image display used by UltraDAS. The third
word
of the statement is a specification of the display in the form
understood
by IRAF's client-display library . The fourth
word is the number of the display frame to which readout-channel 1 is
sent;
if channel 1 goes to frame f, then channel 1+n goes to
frame
(f+n) mod 4.

Example:

0 display inet:60002:lpss13 1

0 display inet:60002:lpss13 3

If the first of the two display statements above appears in udas_A.dat
for camera A and the second statement appears in udas_B.dat for
camera B, then A and B can share the display connected at IP-port 60002
on lpss13. Presuming A and B to each have two channels, A
displays
to frames 1 and 2 and B displays to frames 3 and 4.

There should be a default "display" statement in the system
configuration.
Individual cameras can override this in their own configurations if
necessary.
If it is intended that no camera displays, put "0 display none 1" in
the
system configuration.

NB: at the time of writing, the future syntax and semantics of
display
are undecided.

fits_int

This adds a manually configured FITS card to the output FITS files.
This
creates a FITS card of type INT.

Example:

0 fits_int DISPAXIS 2 Dispersion_axis

This adds the FITS card DISPAXIS to the output FITS files with integer
value 2 and comment "Dispersion_axis". The comment field must not
contain
any whitespaces.

fits_double

This adds a manually configured FITS card to the output FITS files.
This
creates a FITS card of type DOUBLE.

Example:

0 fits_double FITSDOUB 123.45 Test_comment_for_double

This adds the FITS card FITSDOUB to the output FITS files with double
value
123.45 and comment "Test_comment_for_double". The comment field must
not
contain any whitespaces.

fits_string

This adds a manually configured FITS card to the output FITS files.
This
creates a FITS card of type STRING.

Example:

0 fits_string TESTCARD TestValue Test_description

This adds the FITS card TESTCARD to the output FITS files with string
value
TestValue and comment "Test_description". The string value and comment
fields must not contain any whitespaces.

ispace

This describes the image co-ordinate-space (i.e. that used for the
output
images) for one channel in terms of the mapping from i-space to
detector
space. See below for a discussion of the syntax.

Example:

2 ispace -1 0 1 1 2048 0

There should be one ispace statement per readout channel.
If a channel has no ispace statement, then its i-space is
assumes
to have the same origin, scale and alignment as detector space.

jointo

This states how the images from different channels are combined when a
full-frame readout is done. The statement asserts that pixels from one
channel should be joined to pixels from another and output in the image
space (q.v. ispace) of the latter channel.

Example:

1 jointo 1

2 jointo 1

states that channels 1 and 2 are to be combined in the image-space of
channel
1. Note that it is valid to "join a channel to itself". In fact, this
is
the default: if there is no jointo statement for a channel, it
joins
with itself and its pixels are mapped to its own image-space.

NB: at present, jointo is ignored when reconstructing windowed
readouts.
This may change.

maxbias

This states the nominal maximum bias level of the detector ADU at each
of two speeds. This is the highest bias value that is expected. The
bias
level for the slower speed is first.

Example:

1 maxbias 5000 6000

sets the maximum bias value to 5000 for fast speed and 6000 for slow
speed.

Setting the bias level for channel zero sets the same bias level for
all channels. If no maxbias statement is present, the max bias level
defaults
to 65535.

maxbinning

This states the maximum binning permitted on the camera on either axis.
The third and fourth words
indicate the maximum allowed binning in x and y respectively. The
parameters should be set to an integer value between 1 and 10.

If no maxbinning statement is
present, or the keyword statement is incorrectly formatted, the camera
defaults to allow binning from 1 to 10 in both axes.

The maxbinning statement
should normally be in the camera configuration.

monperiod

This defines the period of time in seconds between cryostat telemetry
(such
as temperature) monitoring events.

Example

0 monperiod 30

This sets the monitoring period to 30 seconds. If no monperiod
statement
is present, cryostat monitoring events occur at 60 second intervals.

ndr

This indicates whether a camera performs non-destructive readout. It
must
be set to "yes" for IR HAWAII devices, such as INGRID, and to "no" for
all CCDs.

Example

0 ndr yes

If no ndr statement is present, the camera is assumed not to do
non-destructive readout.

obsdata

This names the disc partitions in which UltraDAS may store raw
observations.
The third and subsequent words of the statement each name one partition
and up to 10 partitions may be named. The name of each partition
is the path-name as seen by the DAS computer. (If the discs are mounted
by the DAS computer from a disc server, then the DAS and the server may
be using different names; often the server prepends /export to the name
and the DAS does not). The partition names in the configuration file
must
not include the directory named for the date of observation: UltraDAS
supplies
this part of the directory name itself.

Example:

0 obsdata /obsdata/intf /obsdata/intg

Obsdata statements should normally be in the host configuration, where
they are applied to all instruments and cameras. This means that the
software
will automatically swap discs if restarted on a different computer. It
is possible to over-ride the set of discs for a particular instrument
or
camera by putting obsdata into one of the other configurations. If you
do this, be aware that the system will not then adapt automatically to
a change of DAS computer.

packets

This names the FITS-header packets to be collected for each
observation.
The third word of the statement specifies the name of the instrument
for
which the header packets are to be collected. The fourth and subsequent
words of the statement each specify one packet and up to eight packets
may be named in the statement. Each packet is specified by one "word"
broken
into three fields by colons (the word may not include white space). The
first field is the name of the packet. The second word is the name of
the
task that produces the packet, or is the pseudo-name "given", or "keep"
(given and keep must be in lower case). These pseudo names indicate
that
the packet is provided without requiring any task to provide the
packet,
and "keep" has the additional meaning of keeping the header packet file
after collection. The third word is the directory in which the
header-packet
file is written. The task-name is the formal (DRAMA) name of the task
which
the HCT will ask to produce the header packet. The pseudo-name given
tells
the HCT that it does not have to ask for that packet. (E.g. the packet
named "observation" is produced gratuitously by the client that
sequences
an observation.)

The packets statement makes most sense when put in an instrument
configuration.
In this case, UltraDAS associates each packets statement with the
instrument
in question. If a packets statement is put in a camera profile, then
the
camera in question tries to collect the same set of the packets for
each
instrument because the packets statements in the instrument profiles
are
occluded.

pixsize

This states the linear width and height of pixels in metres. Pixels are
assumed to have the same width and height and all pixels on a given
channel
are the same size.

Example:

0 pixsize 13e-6

sets the pixel size to 13 microns.

Setting the pixel size for channel zero sets the same size for all
channels.
At present, UltraDAS requires all channels to have the same size of
pixel,
so only the channel-0 form shown above should be used.

pixelskip

This states the number of pixels to be skipped at the start of each
readout.
The camera hardware is pipelined and sometimes produces spurious pixels
before the first real pixel emerges; pixelskip allows these
spurions
to be discarded.
Two different numbers of skips are given, the first for slow readout
and the second for fast readout.

If there are ns skips and nr
real
pixels, the DAS expects to receive ns + nr
pixels
in total from the camera.

Example:

0 pixelskip 2 1

says to skip two pixels in slow readout and one in fast readout.

If pixelskip is not present, the default is to skip no
pixels
for either readout speed.

preflash

This determines the length of the default preflash: the third word of
the
statement is the time in seconds for which the preflash lamps are lit.

Example:

0 preflash 1.5

Preflash is considered for every integration done with UltraDAS. The
configured
preflash is used as the default if no preflash duration is given in the
PREFLASH action. A preflash length of less than one millisecond turns
off
preflash and the lamps do not light. The default for the default, if no
preflash
statement is present, is 0.0 seconds and so the preflash is turned off
by default.

rnfile

This sets the name of the run number file and the run number lock file.

Example:

0 rnfile /wht/var/last_run_v2.dat /wht/var/run_number_lock.txt

sets the run number file to "/wht/var/last_run_v2.dat" and the run
number
lock file to "/wht/var/run_number_lock.txt".

ronoise

This states the readout noise in ADU for one channel, at each of two
speeds.
The noise for the slower speed is given first.

Example:

1 ronoise 2.0 3.4

states that the noise is 2.0 ADU/pixel for slow speed and 3.4 ADU/pixel
for fast speed. There must be one ronoise statement per
channel.
If no ronoise statement is given for a channel, then the noise
is
recorded as zero.

rogain

This states the inverse gain in photelectrons/ADU for one channel, at
each
of two speeds. The gain for the slower speed is given first.

Example:

1 rogain 1.3 2.5

states that the gain is 1.3 e-/ADU for slow speed and 2.5 e-/ADU
for fast speed. There must be one rogain statement per channel.
If no rogain statement is given for a channel, then the gain is
recorded as zero.

rspace

This describes the readout co-ordinate-space for one channel in terms
of
the mapping from r-space to detector space. See below for a
discussion
of the syntax.

Example:

2 rspace -1 0 1 1 2148 0

There should be one rspace statement per readout channel.
If a channel has no rspace statement, then its readout space is
taken to have the same origin, scale and alignment as detector space.

rspeed

This states the startup readout speed of the camera. The third word
indicates the startup readout speed. It should be set to

slow if a slow
readout speed is required;

fast if a fast
readout speed is required;

If the word is not set to one of the values above then a slow readout
speed is used.

Examples:

# Set slow readout speed:0 rspeed slow

# Set fast readout speed:0 rspeed fast

If no rspeed statement is
present, the camera defaults to fast readout speed.

The rspeedstatement should normally be in
the camera configuration.

saturation

This states the nominal saturation of the detector ADU at each of two
speeds.
This is the highest value that is unsaturated. The saturation level for
the slower speed is first.

Example:

1 saturation 65000 60000

sets the saturation value to 65000 for fast speed and 60000 for slow
speed.

Setting the saturation level for channel zero sets the same
saturation
for all channels. If no saturation statement is present, the saturation
level defaults to 65535.

shutter

This states how the shutter is controlled. The third word indicates the
type of control. It should be set to

internal if the shutter is driven directly by an SDSU
detector controller;

none if there is no shutter at all;

external (or a task name: see below) if the shutter is
driven by
some task outside the DAS.

If the word is not set to one of the value abovem then external control
is assumed, and the word is taken to be the name of a DRAMA task that
controls
the shutter; the system may or may not use this information.

Examples:

# Normal CCD shutter:0 shutter internal

# INGRID has no shutter yet:0 shutter none

# INT WFC has a funny shutter controlled by the ICS:0 shutter MCA@intics

If no shutter statement is present, the camera defaults to
internal
control.

The shutter statement should normally be in the instrument
configuration,
not the camera configuration.

temperature

This sets the required temperature of the cryostat. The third word of
the
command is a temperature in kelvin. The system will attempt to change
the
cryostat temperature to this value using the cryostat's heating
circuit.
The temperature set-point determines when alarms are generated about
incorrect
temperature. If the cryostat temperature control is done externally,
then
the keyword "external" should be used instead of the temperature.

Examples:

0 temperature 150.0

for external cryostat temperature control:

0 temperature external

Each camera needs exactly one temperature statement. If
there
is no temperature statement at all, then the temperature will be set to
some default number chosen by the firmware in the detector controller.
This might be acceptable, but it's possible that the optimal
temperature
has changed since the firmware was written.

trimsec

This defines the areas of the readout section that produces useful
data;
normally, it describes where the light-sensitive pixels are. The
argument
of trimsec is an image section in readout coordinates.

Example:

1 trimsec [51:1074,1:1024]

describes the lit area of a Tektronix CCD that has 1024x1024 physical
pixels,
50 pixels each of overscan and underscan in x and 100 pixels of
overscan in y.

If no trimsec statement is present for a channel of a
camera,
then the system assumes equates the trim section with the whole
readout-section.

Co-ordinate spaces and mappings between
them

Four co-ordinate spaces are described in the camera configuration:

r-space (readout co-ordinates) is how the pixels come from the
camera.
The first pixel read out (including any underscan) is (1,1), and the x
co-ordinate increases along the serial register.

a-space (amplifier co-ordinates) is how pixels are arranged on
the
detector.
The first pixel read out (excluding underscan) is (1,1), and the x
co-ordinate increases along the serial register.

i-space (image co-ordinates) is how the pixels are arranged in
the
output
image. Pixels that were contiguous in r-space are contiguous in i-space
also, but the raster may have been reflected and/or rotated and/or
moved
to get it into i-space.

d-space (detector co-ordinates) describe how the other spaces are
related.

There is only one d-space, but each channel has its own r-space,
a-space
and i-space.

In the camera configuration, spaces are each described in terms of
the
mapping needed to go from that space to d-space. This is the syntax:

c k f t s1 s2 m1 m2

where:

c is the channel number;

k, the keyword, is aspace, ispace or rspace.

f ("flip") is +1 for no reversal and -1 to indicate
reversal
of x
co-ordinates;

t ("twist") is an angle of rotation in degrees (positive
means anti-clockwise).

(s1,s2)
("stretch") are scaling factors for the x and y axes;

(m1,m2)
("move") are a displacement on the x and y axes.

The operations are applied in the order given when mapping from a space
to d-space; when mapping from d-space to the other space, the order is
reversed.

For example:

2 rspace -1 90 1 1 2100 0

2 ispace +1 0 1 1 0 0

says that to get from r-space to d-space for channel 2, the system
reverses
the x-axis, rotates the raster 90 degrees anti-clockwise,
doesn't
change the scaling, and offsets the result 2100 pixels in the positive-x
direction. The second line says that the channel should be output in
d-space:
i.e. that there is no change in mapping from i-space to d-space or vice
versa.

Suggestions for setting up the files

This section contains checklists of recommended practices for writing
and
installing the files.

Host configuration file

Do:

Name this file for a particular computer, e.g. udas_lpss14.dat.

Make a separate host configuration for each live DAS computer.

Make a separate host configuration for each spare DAS computer.

Make an empty host-configuration for the system computer.

Put the obsdata statement in the host configuration.

In each obsdata statement, list only discs local to the
host in
question.

Don't:

Make one host configuration called, say, udas_intdas.dat and
expect
it to work for all DAS computers at a telescope.

List in obsdata all data discs on the telescope, even
those not
local to the host in question.

Instrument configuration file

Do:

Name this file according to the formal name of the instrument.

Put in the packets statement for the instrument.

Put in a shutter statement.

Don't:

Put in an obsdata statement unless you really
need to
redirect
this instrument's data files and you are prepared to
reconfigure
manually on a change of DAS computer.

Put in camera-specific stuff like gain and readout noise just
because
the
instrument is usually used with one particular camera.

Camera configuration file

Do:

Give the correct ID-code for the camera using the ccdcid
statement.

Give the lod-file names for the camera in ccdcprog as
unqualified
file-names, such that the system can find the correct version along its
search paths.

List the necessary geometry for each channel:

ampsize

rspace

aspace

ispace

jointo

State the gain and readout noise for each channel.

Give the biassec for each channel.

Remember to list all four bias regions for each channel.

Give the trimsec for each channel.

Give the ampname and ccdname for each channel
(needed
for
the archive).

Put in the temperature statement.

Don't:

Use absolute path-names for lod-files in ccdcprog.
(I.e.
don't
force all versions of UltraDAS to use the same version of one
component.)

Set ccdcid to zero so that "it works" with the ID-plug
disconnected.
(I.e. don't risk hardware damage by defeating the ID system for your
convenience).

Put instrument-level stuff like packets in here because
"this
camera
is almost always used with that instrument."

Put in an obsdata statement unless you really
need to
redirect
this camera's data files and you are prepared to reconfigure
manually
on a change of DAS computer.

Put a shutter statement in here (put it in the instrument
configuration).

Hints for working out geometry statements

INS-DAS-19 has a list of worked examples, covering most types of
detector
used at ING. These define d-space for various types of camera.

For a single-channel camera, it's best to make r-space the same as
d-space.
That is, define d-space such that a full-frame readout, un-mapped, has
its first pixel at (1,1) in d-space. The statement

1 rspace +1 0 1 1 0 0

does this. For a multi-channel camera, it's best to orient d-space to
match
the r-space of channel 1 and to adjust the rspace statements of
all other channels accordingly.

For any given channel, r-space and a-space must have the
same
orientation. The two spaces can only differ by a displacement,
and
that displacement will be due to the presence of underscan pixels.

If r-space and d-space are the same, a-space will typically be
offset
from d-space by the width of an underscan strip. In the case, the
offsets
in the a-space statement will be positive, since the
origin
of a-space is nearer any given pixel of the amplifier section
than
the origin of d-space.

Remember that aspace, rspace and ispace
describe
a mapping from a space to d-space. To map from r-space
to
i-space, the system applies the rspace mapping forwards and the
ispace
mapping in reverse.

If you have a detector chip with output amplifiers on opposite
sides,
you can pretty much guarantee that some of the amplifiers will have a
flip
in their r-space definitions.

Often, one wants i-space for a channel to be the same as
r-space.
That is, the pixels from the channel should be left in the order in
which
they were read out. To achieve this, the ispace statement has
to
reverse the effect of rspace: i.e. mapping from r-space to d-space to
i-space
takes you back to r-space. Here is an example:

1 rspace +1 0 1 1 0 0

1 ispace +1 0 1 1 0 0

in which neither mapping changes anything - both spaces are the same as
d-space.
This is typically what you want for a single-channel camera. Here is a
second example with non-trivial mappings:

2 rspace -1 90 1 1 4200 2148

2 ispace -1 -90 1 1 -4200 -2148

Note that the i-space mapping is exactly the reverse of the r-space
mapping.
You can picture the logical process. The image is first reversed
in x; then it is rotated 90 degrees anti-clockwise; then it
moves
by +4200 in x and +2148 in y: it is now in d-space. The
second
mapping is applied in reverse as we are going from d-space to
i-space: the image is moved by -4200 in x and -4148 in y;
it is rotated 90 degrees clockwise; and it is reversed again in x.
We are now in i-space, but the raster is the same one that we had in
r-space,
which is what was wanted.

UltraDAS doesn't actually map rasters from r-space to d-space and
then
map again to i-space: that would be inefficient, particularly when
i-space
and r-sapce are equivalent. UltraDAS computers a single, compound
mapping
using the algorithm in INS-DAS-19
[1], and applies that. The software is intelligent enough to trap the
cases
where the mapping moves every pixel to the same position in the raster,
and in that case it doesn't waste time shuffling the data.

In aspace, rspace and ispace statements, never
set the scale factors to anything other than unity.

When setting up r-space and i-space, the flips and twists are easy
to
work out, but the moves are difficult. It may help to realize
that
the displacement is the position of the origin of the given
space
measured in the co-ordinates of d-space.

There is a holy war in progress over the question of whether images
should be mapped to different orientations and whether channels should
be joined together before output. The emerging consensus seems to be:

Channels of different detector chips should not be
joined,
because
the a-space to d-space mapping doesn't represent the relative position
of the chips accurately enough.

Channels of a given CCD chip may be joined, but probably should
not, because the joining makes later reduction too hard (a bias
frame
would be needed with every science frame to subtract the bias
accurately).

Channels of a given IR detector-chip should be joined
(bias is
not
a problem, as each run includes a bias frame).

Channels of one CCD chip should be mapped to the same
orientation
if they are not joined.

Channels of different CCD chips shouldnot be
mapped to
the
same orientation.

Whatever values you set, test them. The best test is to run the
camera
in simulation with no windowing or binning. That way, you know what the
image should look like before you transform it.

Worked example of geometry derivation: INGRID

As a further guide to the mental contortion needed to derive and set
the
geometry statements, here is the full working for the setting up of a
four-quadrant
detector somewhat like INGRID. In fact, the real INGRID turned to be
simpler,
needing no reflections or rotations, but this example is still
informative.

qINGRID is read out in four quadrants, each quadrant producing a
square
raster 512 pixels on a side. This immediately sets the ampsize
values:

1 ampsize 512 5122 ampsize 512 5123 ampsize 512 5124 ampsize 512 512

D-space is abitrarily defined to be aligned with r-space of quadrant 1,
so there is a unit mapping for r-space-1 to d-space:

1 rspace 0 0 1 1 0 0

The output from qINGRID is required to be one raster, which (in the
absence
of other instructions) may as well be output in d-space. To do this,
the
i-space of quadrant 1 is made identical to d-space and all quadrants
are
merged in that space:

1 ispace 0 0 1 1 0 01 jointo 12 jointo 13 jointo 14 jointo 1

The jointo line for quadrant 1 is there for completeness and clarity:
this
setting would be implicit if the line was left out. Since the quadrants
are being mereged in i-space-1, the i-spaces for quadrants 2, 3 and 4
are
meaningless and are not defined.

The chip is symmetrical about its centrelines in both x and y, so
the
r-spaces for quadrants 2, 3 and 4 have a non-trivial mapping to
d-space.

Quadrant 2 is a mirror-image of quadrant 1 across the vertical
centreline
in d-space. This quadrant is flipped when mapping to d-space. The
origin
of r-space-2 is 1025 pixels away in x from the origin of
d-space:
i.e. the width of the chip, plus one pixel more because the first pixel
in each quadrant is (1,1), not (0,0). No rotation is necessary for this
quadrant. This gives:

2 rspace 1 0 1 1 1025 0

Quadrant 3 is reflected with respect to quadrant 1 in both x
and
y,
which
is equivalent to a rotation of 180 degrees and no flip. The
displacement
is the width/height of the chip plus one pixel on each axis, giving:

3 rspace 0 180 1 1 1025 1025

Quadrant 4 is a reflection of quadrant 1 about the horizontal
centerline:
this is equivalent to a flip in x followed by a rotation of 180
degrees. The displacement here is all in the y direction,
giving:

4 rspace 1 180 1 1 0 1025

Finally, qINGRID has no underscan regions (because it is an IR
detector,
not a CCD), so a-space is equivalent to r-space for each quadrant: