This document is intended mainly as a list of the atomic items needed to describe the state of the array. In order to do so in a concrete fashion, it is necessary to include a few control concepts and other programmatic conventions. This are seriously affected by choices made in the course of the implementation of the interface, and this document should not be construed as specifying these things; alternate approaches of equivalent power are certainly acceptable.
I am taking the approach that one describes an observation, and then executes it, rather than the approach that the script should describe a sequence of timed commands, which is also a viable approach, but in my opinion a little less desirable.
In the material below, I find it convenient to speak in terms of macro
expansion. (A parameterless procedure is an alternative way to look
at the functionality; the two are indistinguishable except in
implementation.) In the examples I shall use '&' to indicate that the
following symbol is a macro, to be replaced by its defining text
wherever it is found. I think requiring all macros to be defined at
the beginning of the script is a reasonable requirement, and nesting
of macros to arbitrary depth useful.
In the examples and definitions below, I shall use the character '!' to
indicate that the remainder of the line is a comment. (There need to
be two types of comments - one which is visible when the script is
printed, one which is posted to the attention of the array operator at
observe time.)
{ } enclose a block of text to be operated on as a unit.
Most information is conveyed by statements of the form
<parameter> = <constant>
Constant types are:
Al Wootten's remark that observers may want to detach just a few antennas to run off and do a tipping curve was a possibility that had not occurred to me, and, although it might be done in any of several ways, is elegantly handled by user definable sub-arrays, and has pushed me into defining a script that supports them. Most of the control structures below are derived from that requirement.
There will need to be a carefully thought through specification of the scope of parameter settings (I would model it on the scope of variable names in C), which I will ignore for the moment.
Each file should have a special section describing the proposal and observation block (OB hereafter). Say,
$HEADER
{
parameters with proposal code, proposal contact person, addresses,
phone numbers, etc., comments helpful to operators at run time.
}
A special symbol is needed to define a macro. As I mentioned above, I think requiring them to be early in the file is a good idea for readability purposes. The observer's tool should include a library of macros, which can be searched for useful macros to be extracted and put in the script file. A few macro's could be usefully built into the real-time system, for example the list of antennas with a specific set of hardware.
$MACRO <macroname>
{ a body of text, not containing a reserved word,
that appears in the script when the macroname, preceded by a &,
appears
}
There are two items which I suggest deserve a special status, for different reasons. The correlator setup is very fundamental to the system. It, in particular, determines the output format. I think it is useful for the real-time system to have a list of the correlator setups that it may be required to setup for, and especially for the data reduction programs to have a list of the possible data formats they may have to deal with.
Source descriptions are really tables. For a mosaic, the table is a list of offsets from the reference position, or perhaps preferably, a list of positions to be included in a mosaic organized around the reference position. For a planet, asteroid, or comet, the source description is a table of position versus time. (This differs from the mosaic table in that it may be queried at fractional rows, with the expectation of receiving an interpolation.)
Because these two items are quite different I shall return to them individually below, here remarking that they will look something like this:
$SOURCE <sourcename>
{
a body of text setting parameters to set up an observation of a source.
These parameters may appear only in a $SOURCE| block.
}
$CORRELATOR <setupname>
{
a body of text describing the correlator setup. These parameters may
appear only in a $CORRELATOR block.
}
$MESSAGE <messagename> <messageaddress>
{
A block to pass information to other programs, especially the pipeline
reduction program in their native tongue, passed on but not interpreted
by the real-time system.
}
As mentioned above, it seems desirable to give the astronomer the capability of organizing subarrays of his own. A subarray is defined as a collection of antennas (note: not baselines) whose data is output together. (That is, baselines between antennas in different subarrays are not processed.) Not all of the data may be meaningingful, for instance if some antennas are missing their full complement of baseband digitizers, but the data are output together, and the validity of that data is handled elsewhere.
Each subarray is conceived as being an entity, with the entity scanning the script until it encounters its own description of the sequence of observations, and then proceeding to execute that sequence with the time steps described therein. A facility is provided to move antennas from one subarray to another, here conceived as having the subarray to which the antenna belongs yield it to another.
Each description of the sequence of observations would look something like this:
$OBSERVE [<sub-array name>]
{
description of observations, with time steps delimited by '/'
}
It seems worthwhile to provide looping at the script level, to keep the
size of the script small and readability good. The minimum construct
for looping would be to provide two qualifiers, which could be applied
either to simple observations (delimited by '/') or blocks (here shown
delimited by ...):
REPEAT(<integer number of repeats>)
UNTIL(<time (either constant or relative)>)
In addition, it is occasionally necessary to specify some parameters differently for some antennas. So we have a block of text ignored by or read only by a specified antenna list.
{ text not containing '/' } [NOT]FOR ( <list of antennas> )
To transfer antennas from one sub-array to another we have the special function
TRANSFER (<sub-array name>, <list of antennas>)
An example of the simplest form of $OBSERVE block is below. We
presume that setup1 is a macro which organizes frontend
switches, LOs, and the correlator, and sgra*, nrao530
and 1749-28 are the names of $SOURCE blocks.
$OBSERVE
{
&setup1
source = nrao530 / UNTIL (15:30:00)
{
source = sgra* / UNTIL (.+1:20)
source = 1749-28 / UNTIL (.+40)
} REPEAT (60)
}
This runs to source nrao530, observes it until 15:30 LST, then starts
a set of two minute cycles, with 80 seconds on sgra* and 40 on
1749-28, which continue for the next two hours.
For a more complicated example, suppose the observer wants to assign a
few antennas to do a tipping curve for four minutes every 30 minutes.
There is a $SOURCE block with name tipcurve.
$MACRO sgracycle
{
source = sgra* / UNTIL (.+1:20)
source = 1749-28 / UNTIL (.+40)
}
$MACRO mytipsubarray {2 7 9 17 23}
$OBSERVE main
{
&setup1
source = nrao530 / UNTIL (15:30:00)
{
{&sgracycle} REPEAT(13)
TRANSFER (tipping, &mytipsubarray)
{&sgracycle} REPEAT(2)
} REPEAT(4)
}
$OBSERVE tipping
{
&setup1
source = tipcurve / UNTIL(.+4:00)
TRANSFER(main, &mytipsubarray)
}
The first subarray is activated, and does its 13 cycles of source switching. At this point the tipping subarray antennas are transfered to the other subarray, which has been inactive to this point. After the tipping curve is completed, the antennas are transfered back, and the subarray again becomes inactive.
All the hard decisions in designing a script are whether a function
should be provided in the real-time system, or if it is part of the
observing preparation program. I suggest below some details for the
$SOURCE blocks which have a good deal of software in the real-time
system. What this complexity gets you is that first, if the operator
finds it necessary to suspend operation of the observe file and then
restarts it, more sensible results are obtained, and second, a greater
variety of observe files may be written in a day-independent fashion
(that is, that the file run today may be used again tomorrow without
passing through the observe file preparation software again).
$SOURCE blocks come in several forms. The first is the simplest and
probably the most common.
$SOURCE <source name>
{
type = STAR
ra = <J2000 right ascension>
dec = <J2000 declination>
calibratortype = <NON | PHASE | AUXILIARY | FLUX | BANDPASS | POINTING>
[label = <text to be passed to processing programs>]
[processing = <list of $MESSAGE blocks>]
}
$SOURCE <source name>
{
type = MOSAIC
ra = <J2000 reference right ascension for object>
dec = <J2000 reference declination for object>
tracking = <SMOOTH | JUMP> ! antenna pointing at phase reference or
! moving smoothly to next posn during obsn
[label = <text to be passed to processing programs>]
[processing = <list of $MESSAGE blocks>]
centers = <ordered list of triads: ra, dec, dwell-time>
}
This type of source block declares a table of locations, which are then accessed by an explicit or hidden variable, such that each time the source is visited, a new entry in the table is pulled out and used for the phase tracking center. Jumps, based on the durations specified here need to be synchronized so that they begin precisely at the end of correlator integrations. (As should any change of source.) I have suggested positions, rather than offsets, because I always have trouble remembering whether they should be added to the reference position to the the instant position, or vice versa.
$SOURCE <source name> { type = PLANET [label = <text to be passed to
processing programs>] [processing = <list of $MESSAGE blocks>]
position = < ordered list of tetrads: UTTime, geocentric ra, dec,
distance > }
$SOURCE <source name>
{
type = AZEL
[processing = <pointer(s) to information used by postobserving processing>]
[processing = <list of $MESSAGE blocks>]
centers = < ordered list of triads: elevation, azimuth, dwell-time >
}
This is used to position antennas to a given AZEL location, or set of locations.
The set of locations is intended for the use of this for use to generate data for a tipping curve, or for holography with a transmitter. The other common uses for az-el coordinates - parking the antenna for technician access or putting the array into stow position - will likely have convenient commands in the operator and technician interfaces, and are less likely to be done through the observing script.
I am suggesting here that parameters be specified on a baseband pair basis. This forcloses, for instance, different spectral resolutions in the two basebands. One can think of cases in which that is useful, but they do not seem to me to justify the complexity in the real-time system. The suffix X indicates which of the four baseband pairs is indicated. I have no particular opinion about whether this should be A, B, C, D, or 1, 2, 3, 4 or [1], [2], [3], [4] or whatever.
decimationX = <1 | 2 | 4 | 8 | 16 | 32> ! Sets the total bandwidth analysed crosscorrelationX = <YES | NO> ! NO is the multiple single dish mode polarizationX = <YES | NO> ! four vs two products per BB pair (even if, due to switches, some are silly) integrationX = <integration time in seconds> ! the u,v FITS for the VLBA correlator requires the same integration time ! in all basebands, which I here propose to relax. ! having a baseline specific integration time is a big complication in ! the real-time system (and elsewhere also), which I do not believe is ! justified by the reduction in output rate one would realize nmbrlagsX = <16 | 32 | 64 | ... | 2048> ! one may want to process fewer than the full number of lags the hardware ! provides, to exchange spectral resolution for data volume or data rate. archiveX = <list of channel numbers to be passed to archiving system> ! We probably need a mechanism to discard the ends of the spectra ! to get data output rates and volumes down. This is the most ! general way of describing this, and pretty easy to implement. ! However, I can imagine the programmer of a 'filler' program looking ! like the famous Muench painting when asked to implement this in all ! its generality. In practice, one would presumably have a small number ! of spectral windows. But having the full generality in the real-time ! system does not seem harmful to me.
Each subarray has an associated block which describes the sequence of setups and sources as a function of time.
For use by a "control panel" type front end, the real-time system should
be arranged to accept all blocks at the front of the file, and then prepare
itself to receive the $OBSERVE block a record at a time, and to skip
to the new record when it arrives.
I group things by the devices to which they apply for reading convenience - the groupings have no functional significance.
The real-time system would have a database of the parameters of the antenna pointing model - things like azimuth axis tilt, axis perpendicularity, encoder centering, azimuth encoder zero offset, and, for each feed, the collimation offsets. It is a little unclear to me what of these need to be brought out to script level. It is clear that the collimation offsets need to be, and they are the only ones shown here. These script offsets are to be added to the ones from the internal database. If, as seems likely, the initial pointing model needs work, (eg having temperature dependent coefficients, or a higher order harmonic to describe bearing runout), I would incline to changing the internal database directly, rather than bringing the quantities out to the script for playing around purposes.
azcollimation = <collimation offset in arcminutes> elcollimation = <collimation offset in arcminutes> refractivity = <refractivity in N units> ! if refractivity is 0, calculate it from on-line weather instruments wrap = <R | L | N> ! If there is a choice of azimuth wrap, choose CW, CCW, Nearest, resp. reference = <NO | * | receivercode> ! Apply reference pointing collimation errors from named band ! (from current band if *)
Again, there would be a database of the subreflector model parameters, containing for each antenna and receiver, the required focus setting, focus vs sin(elevation) coefficient, focus vs temperature coefficient, x,y focus position, x vs cos(elevation) coefficient. Again, quantities in the script are added to those in the database.
focus = <focus offset in mm> xfocus = <x direction translation in mm> yfocus = <y direction translation in mm> temperature = <temperature, C> ! if temperature is 0, use on-line outside thermometer calibration = <ON | OFF | SWITCHING> ! Subreflector center calibration device ! As I understand it, calibration scheme still undecided. ! Might require a few more codes (ie thermal calib might need ONHOT, ONCOOL) ! parameters need to be added for control of nutating subreflector if one ! is eventually decided on; I understand one is not in the baseline plan.
receiver = <receivercode> ! this selects what collimation parameters to use, and specifies ! which receiver the LO power is routed to. (My understanding is ! that only one receiver at a time receives LO power.) firstlo = <first LO frequency in GHz> phasemod1 = <NONE | SINE | WALSH > ! specifying the functional form of the phase modulation imposed on ! the first Local Oscillator. May also want to specify the order of ! the Walsh function, although letting it be implied by the number of ! available antennas is probably OK. The suffix 1 indicates that it ! is applied to the first LO. ! I include this technical detail in the script because I'm quite ! unsure that we can a priori make the right choice that will work ! for everything. phasemodrate1 = <modulation rate in Hz> ! Basic modulation rate (repetition of the Walsh functions, or lowest ! harmonic for the sine waves). Each antenna will have a sequency or ! harmonic number of it's own. ! If WALSH is selected, there will be interesting constraints on permitted ! rates firstlodoppler = <OFF | SET | SETREF | TRACK | TRACKREF > ! SET = set LO at scan beginnings ! TRACK = track continuously during scan ! REF = set LO at mosaic center; otherwise at mosaic offsets ! If not OFF, firstlo frequency is barycentric dopsource = <source descriptor | CURRENT> ! Use given source descriptor to calculate doppler, rather than current ! source (to observe bandpass calibrator at same frequency as main field)
There are eight basebands, which must be operated in pairs, because
there are only four copies of the second LO module. These pairs are
usually to be used to select polarization pairs, but more exotic
configurations are possible. Because of this pairing, it is
convenient to describe basebands in terms of baseband pairs. Note
that, in electronic terms, we are talking about pairing two baseband
converters from different downconverter blocks. It's implementer's
choice whether you want subscripts or a separate name for each
baseband command. Issue bypassed here by writing, eg,
BBselectXY, wherein X specifies the member of the pair, and Y
specifies the pair. The above could mean BBselectA1 or
BBselectA[1] or BBselect[1,1] or
BBselect[0,0], depending on how you want to name or number things.
In particular, the BBselectXY command is a problem, in that not all
combinations are possible (the switch structure is flexible, but not
infinitely so), and not all possible combinations are useful (eg
selecting different first LO sidebands for the two members of a pair).
An alternative approach would be tied more closely to the structure of
the switches, so that it would not be possible to specify an
impossible or even a non-useful combination.
BBselectXY = <OFF | UV | UH | LV | LH> ! Selects the sideband and polarization of the signal fed to the named ! converter. (I suppose R,L should be permitted as well as V,H, in case ! somebody has a smart idea about a quarter wave plate.) secondloY = <second LO frequency in GHz> phasemod2Y = <PASS | WALSH | SINE | NONE> ! for some purposes it may be desirable to have the second LO remove ! the phase modulation of the first LO and impose a different one of ! its own. (In particular, with the photonic LO scheme, it may well ! be convenient to use sines for sideband suppression and Walsh functions ! to cancel sampler offsets). PASS lets the first LO modulation pass ! unchanged; NONE removes it, and does not impose a different one. phasemodrate2Y = <modulation rate in Hz> phaseoffsetY = <arbitrary phase in degrees to be added to 2nd LO phase> secondlodopplerY = <OFF | SET | SETREF | TRACK | TRACKREF > ! SET = set LO at scan beginnings ! TRACK = track continuously during scan ! REF = set LO at mosaic center; otherwise at mosaic offsets ! If not OFF, secondloY frequency is barycentric ! dopsource (above) would also apply here ! if first LO doppler is not OFF, this only applies difference phasecalibY = <OFF | AUTO | CALIB | POWER | WVR> ! source of phase calibration information ! AUTO indicates using current observations to phase up immediately ! (called Autophasing at the VLA) - principal use for VLBI ! CALIB extracts phases from last calibrator scan, again principally for ! VLBI ! POWER uses power level from receiver in use with a coefficient to convert ! to phase due to water vapor ! WVR uses a special water vapor radiometer being considered ! More codes, and combinations of the above, may be needed deltaDelayXY = <Delay in nanoseconds to add to system offset value> FIRfilterXY = <Code for set of filter tapweights>
It is insufferably confusing unless all baselines in a subarray have the
same values of this set of parameters. They are therefore forbidden to
occur inside a {...} for(..) block.
There would be something to be said to make this stuff into a special
$CORRELATOR block, like $SOURCE. For one thing, it would make it very
natural to supply ahead of time to a 'filler' program a list of all
settups to be expected, which would make it easier to write than having
to have it be ready for anything at all times.
Again, forbidden in for-blocks.
fftY = <YES | NO>
! to get delay functions instead of spectra for special purposes
digitizationCorrectionY = <YES | NO>
! suppress digitizatin correction for higher output rate
statisticsCorrectionY = <YES | NO>
! apply correction for non-ideal digitizer levels
smoothing = <NONE | HANNING>
tsysCorrectionY = <YES | NO>
! apply correction derived from calibration hardware
scaleXY = <arbitrary number to multiply output by>
corrphasecalibY = <OFF | AUTO | CALIB | POWER | WVR>
! Apply phase calibration after correlation instead of to 2nd LO
postintegrationY = <number of LTA integrations to be averaged before
archiveing>
! Only useful if corrphasecalibY is not OFF
archivebothY = <YES | NO>
! Only useful if postintegration is specified