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 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.
Example:
1 ampsize 1076 4096There 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.
Example:
1 ampname Left-handThere should be one ampname statement for each readout channel.
Example:
2 aspace -1 0 1 1 2048 0There 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.
Example:
1 biassec [15:45,20:4180] [15:2140,4100:4150] [2100:2140,20:4180] [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.
Example:
0 bitpix -32says 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.
Example:
0 ccdcid 0x2bCcdcid statements should only be put in camera configurations.
Example:
0 ccdcprog udas_eev42_dual_timing.lod udas_utility.lodCcdcprog statements are usually found only in camera configurations.
Example:
0 ccdcprog_gen 3 udas_CCD4710_timing3.lod udas_CCD4710_utility3.lodccdcprog_gen statements are usually found only in camera configurations.
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.
Example:
1 chiptype "HAWAII-2"
Example:
0 clearreads 3
Example:
0 display inet:60002:lpss13 1
0 display inet:60002:lpss13 3If 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.
Example:
0 fits_int DISPAXIS 2 Dispersion_axisThis 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.
Example:
0 fits_double FITSDOUB 123.45 Test_comment_for_doubleThis 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.
Example:
0 fits_string TESTCARD TestValue Test_descriptionThis 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.
Example:
2 ispace -1 0 1 1 2048 0There 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.
Example:
1 jointo 1
2 jointo 1states 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.
Example:
1 maxbias 5000 6000sets 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.
Examples:
# Allow binning in y (vertical axis only) up to binning factor 8, but disallow binning in x (horizontal axis)
0 maxbinning 1 8
# Disallow binning on both axes: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.
0 maxbinning 1 1
The maxbinning statement should normally be in the camera configuration.
Example
0 monperiod 30This sets the monitoring period to 30 seconds. If no monperiod statement is present, cryostat monitoring events occur at 60 second intervals.
Example
0 ndr yesIf no ndr statement is present, the camera is assumed not to do non-destructive readout.
Example:
0 obsdata /obsdata/intf /obsdata/intgObsdata 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.
Example:
0 packets WFC observation:given:/int/var tcs:TCS:/int/tcs exposure:MCA:/int/var wfc:MCA:/int/varThe 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.
Example:
0 pixsize 13e-6sets 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.
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 1says 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.
Example:
0 preflash 1.5Preflash 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.
Example:
0 rnfile /wht/var/last_run_v2.dat /wht/var/run_number_lock.txtsets the run number file to "/wht/var/last_run_v2.dat" and the run number lock file to "/wht/var/run_number_lock.txt".
Example:
1 ronoise 2.0 3.4states 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.
Example:
1 rogain 1.3 2.5states 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.
Example:
2 rspace -1 0 1 1 2148 0There 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.
Examples:
# Set slow readout speed:
0 rspeed slow
# Set fast readout speed:If no rspeed statement is present, the camera defaults to fast readout speed.
0 rspeed fast
The rspeed statement should normally be in the camera configuration.
Example:
1 saturation 65000 60000sets 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.
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:If no shutter statement is present, the camera defaults to internal control.
0 shutter MCA@intics
The shutter statement should normally be in the instrument configuration, not the camera configuration.
Examples:
0 temperature 150.0for external cryostat temperature control:
0 temperature externalEach 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.
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.
INS-DAS-19 [1] describes these concepts in more detail.
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 m2where:
For example:
2 rspace -1 90 1 1 2100 0
2 ispace +1 0 1 1 0 0says 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.
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 0does 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 0in 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 -2148Note 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:
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 512D-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:
2 ampsize 512 512
3 ampsize 512 512
4 ampsize 512 512
1 rspace 0 0 1 1 0 0The 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 0The 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.
1 jointo 1
2 jointo 1
3 jointo 1
4 jointo 1
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 0Quadrant 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 1025Quadrant 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 1025Finally, 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:
1 aspace 0 0 1 1 0 0
2 aspace 1 0 1 1 1025 0
3 aspace 0 180 1 1 1025 1025
4 aspace 1 180 1 1 0 1025