[evlatests] Escapers in obs2script

[Walter Brisken]

Rick asked me to document how to use escapers with the EVLA to gain additional 
control of the antennas.  Below is a document I made to that effect.  If 
someone could post it to a relevant web page that would be good -- I'm not sure 
where it should go.  This doc is also available in thesource code tree of 
obs2script.  Comments welcome.

-Walter

..........................................................................


 			Observe File Escapers

 			   Walter Brisken

 			     Oct 4, 2007


Introduction

Escapers are extra lines that can be added to an EVLA observe file to provide 
additional functionality.  Two types of escapers exist.  The first
allows a small number of otherwise unsettable parameters to get set.
The second inserts (literally) a command into the jython script and
can be used to do just about anything.


Local Type 1 Escapers  //* &

A type 1 escaper begins with the 5 characters (not including quotes)
"//* &".  The first three characters are the normal observe file comment
line indicator.  Each of these escapers is in effect only for the scan in which 
they are set -- see Global Type 1 Escapers if more than one scan needs
the same escaper.  Local escaper line(s) should occur after the source card 
they modify.  Escapers of type 1 are not case sensitive.  There are currently 
three escapers known to obs2script:

L301_1 : Forces the tuning of the first L301 (for IFs A & C) to the specified 
frequency in MHz.  The value must be an odd multiple of 128.
This command can be useful if it is known that the default LO frequencies
are not ideal for some reason (RFI contamination, filter or comb roll-off,
...).  A legal example would be:

   //* & L301_1 = 14976

L301_2 : Same as L301_1, but sets the B & D IF pair's L301.

Refant : Sets one or more antenna to be a reference antenna.  This is
used to prevent rastering or focusing of antennas, for example in
holography measurements.  Below are three legal examples:

   //* & Refant = 1

   //* & Refant = [2]

   //* & Refant = [3, 4, 5]

These set antenna 1, antenna 2, and antennas 3,4 & 5 as reference antennas
respectively.  Note that if there are two Refant escapers in one scan, only
the last one will be used -- they are not logically ORed together.


Global Type 1 Escapers

For each "local" escaper described above, there is a global escaper that can be 
set anywhere in a file.  In each case the global escaper sets the new default, 
which can be overridden on a scan-by-scan basis by the non-global equivalent 
escaper.  A second occurance of a global escaper
will change the default for scans that follow.  All global type 1 escapers have 
the same names as the local variants prefixed with the
letter "G".  For example:

   //* & GRefant = [1,3,5]

Will set the default reference antennas to 1, 3 and 5.  In many cases it
is the global escapers that are more useful.


Type 2 Escapers  //* \

A type 2 ecaper begins with the 5 letter sequence (not including quotes)
"//* \".  Again the first three characters form the observe file comment
indicator.  Type 2 escapers literally dump the line of text (minus the
first 5 characters) into the jython file that the executor runs.  It is
probably a good idea to test the use of these escapers with obs2script 
(/home/mchost/evla/bin/obs2script) before submitting a file to ensure
that the right action is being done.

Since python code is being generated, you will have to ensure that the
correct amount of indentation is done.  In almost all cases this means
don't put any white space between the 5 characters that indicate type 2
escaper and the text itself.  For example to turn off phase switching on
antenna 17, one could insert into the observe file:

//* \ea17 = subarray.getAntenna("ea17")
//* \ea17.setSuppressSwitching(1)

Whether or not this affects a single scan or many depends on the interaction
of the escaper with the jython script that is produced.


Running obs2script

It is a good idea to run obs2script on your observe file if you are to
use escapers (especially for type 2 escapers) to make sure the consequences are 
intended.  To do this:

/home/mchost/evla/bin/obs2script My_Observe_File.obs > My_EVLA_File.evla

Then examine the .evla file.  It might be useful to do this twice, once
for a version without escapers and once for a version with escapers:

/home/mchost/evla/bin/obs2script My_Original_File.obs > original.evla
/home/mchost/evla/bin/obs2script My_Escaped_File.obs > escaped.evla

and run "diff" on the two output files to see what changes:

diff escaped.evla original.evla