Real-time system script

[Barry Clark <bclark@aoc.nrao.edu>]

I thought I would send along a few control concepts, specifically to 
illustrate the complexity introduced by observer-controlled subarrays,
before I get down to the harder and more boring job of writing down the
atomic level stuff the real-time system needs to know to observe.

Apologies to Gianni Raffi.  I have put this in terms of a language definition
rather than specs from which a language definition may be derived, just 
because it is a lot easier.  I think this is not inappropriate for a group
like this - I think we are all committed to doing enough work to entertain
and evaluate counter-proposals from the implementers.  I would certainly
not like to see this set down as a spec to write to, but it is the 
easiest way to provide a guideline to the sort of capabilities we want.


In this document, I shall adopt the conventions given below for examples
and casual discussion.  This is just for purposes of describing a script
with the desired properties.  When we come to implementation I would
expect some discussion of alternate formulations, especially if we end
up with an existing syntax interpreter.  

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.

$ begins a reserved word (convention borrowed from VEX scheduling language).
   Only the words described below are legal.
& signifies that the word following is a macro, and is to be replaced by
   the defining text.
! indicates that from this point to end-of-line is a comment.
/ within the $OBSERVATION block, delimits an observation (sometimes called
   a scan.
{ } 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:
   strings  (in examples below, blank delimited and not containing "hot"
      characters.  We probably need a quoting convention so source names,
      for example, can contain hot characters.)
   integers (as found by scanf("%d"))
   double precision (as found by scanf("%lf"))
   angles - we use, for example, 03h19m48.16s, 41d30'42.1"
   times - I think we need three formats 
      LST - as, eg 01h10m00s or 01:10:00
      UT - I suggest MJD & fraction, eg 51543.75
      Intervals - I suggest .+3 (three seconds from beginning of scan or block)
	 .+3:10 (190 seconds from beginning of scan) etc.

Al Wootten's remark that observers may want to detach just a few antennas to
run off and do a tipping curve was a possiblity that had not occurred to me,
and, although it might be done in any of several ways, is elegantly handled
by user definable subarrays, 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.

An observe file consistes of the following sections:

$HEADER
    {
    parameters with proposal code, proposal contact person, addresses,
    phone numbers, etc., comments helpful to operators at run time.
    }

$MACRO <macroname> 
    {
    a body of text, not containing a $ reserved word, that appears in the
    script when the macroname, preceeded by a &, appears
    }

$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.
    }

SOURCE could be just another MACRO, but I think it might be worthwhile 
giving sources a couple of special properties (for example, for mosaicking).

[ 
  A block to pass information to the pipeline reduction program seems
  indicated.  I'd have to think about how to define such a thing.
]

$OBSERVE [<subarray name>]
    {
    description of observations, with time steps delimited by '/'
    }

Within the observe block, each simple observation (delimited by '/') or
block (here shown delimited by {...}) may be qualified by one or more
of two qualifiers:

    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 subarray to another we have the special
function

    TRANSFER (<subarray 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 simplest is first below.

$SOURCE <source name>
    {
    type = STAR
    ra = <J2000 right ascension>
    dec = <J2000 declination>
    [label = <text to be passed to processing programs>]
    [processing = <pointer(s) to information used by postobserving processing>]
    [display = <name of coordinate system for processed displays - eg B1950>]
    [displayrtn = <16 element rotation matrix to rotate to display system>]
    }

$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 = <pointer(s) to information used by postobserving processing>]
    [display = <name of coordinate system for processed displays - eg B1950>]
    [displayrtn = <16 element rotation matrix to rotate to display system>]
    centers = <ordered list of triads: ra, dec, dwell-time>
    }

This type of source declaration contains a hidden variable, such that 
if you leave and return, you come back to the same center.  (The hidden
variable would need to be available to the array operator, I think, so
he can restart an aborted script.  But I don't see a need to make it
available to the observer.)

$SOURCE <source name>
    {
    type = PLANET
    [label = <text to be passed to processing programs>]
    [processing = <pointer(s) to information used by postobserving processing>]
    [display = <name of coordinate system for processed displays - eg B1950>]
    [displayrtn = <16 element rotation matrix to rotate to display system>]
    position = < ordered list of tetrads: UTTime, geocentric ra, dec, distance >
    }

Note that PLANET and MOSAIC are mutually exclusive.  Mosaicing the sun will 
require a separate named $SOURCE for each pointing center.

$SOURCE <source name>
    {
    type = TIPPING
    [processing = <pointer(s) to information used by postobserving processing>]
    centers = < ordered list of triads: elevation, azimuth, dwell-time >
    }



For use by a "control pannel" 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.
Date: Fri, 28 Jan 2000 08:27:15 +0100 (MET)
To: lucas@iram.fr
From: Majordomo@web3.hq.eso.org
Subject: Majordomo file: list 'alma-sw-ssr' file 'alma-sw-ssr.000127'

--