[evla-sw-discuss] VCI schema changes -- Part I, Summed Array AGC

[Ken Sowinski]

These emails will serve to document changes to the VCI XML schema
intended to provide more flexible control over some Widar capabilities.
It will be of interest to those who construct or parse VCI documents.
This message describes the control of summed array AGC behavior.  The
next will describe control of the digital SSB mixer incorporated in
each of the filter chips.

The current version of model2script does not set any of the attributes
here, and the default behavior is unchanged, so these changes are harmless.
In the future model2script may choose to use the new attributes to change
summed array AGC discipline for pulsar observing or other use cases.  The
default behavior remains correct for VLBI observations.

This describes AGC control for VDIF summed array output.  The cc element 
contains the same attributes, they behave identically and will be ignored
here.  The current definition of the vdif element includes three attributes
related to AGC:

     - requantGain    int     0 < requantGain < 255
       To explicitly set the requantizer gain.  Not very useful without
       control of the "window" setting as well.

     - agcRms         float
       Desired setpoint for summed array output power RMS.  The default
       values are 1,8 foir 1-bit quantization, and 2.7 for 4-bit quantization.

     - agcEnabled     boolean             **NOW DEPRECATED**
       Chooses between setting requantizer gain explicitly (false), or
       servoing the RMS to the desired setpoint (true).  The default
       is true.

These are all optional with defaults enforced in CM rather than XML.
agcEnabled is now deprecated in favor of agcMode, described below.
These are the newly defined attributes.

     - agcMode        enumeration
       To control how the AGC behaves.

     - window         int                **CURRENTLY UNUSED**
       Which may be used in the future to specify the "window" setting.
       Currently there is no direct control over this hardware setting.

     - agcDelay       int
       The desired interval, in seconds, between a modify request to
       awt the filter chip requantizer and the succeeding summed array
       AGC setting process.   Default is three seconds.

agcMode may take on several values:
     - dontChange   Do nothing, nothing is sent to the BL boards.
     - setRq        Equivalant to agcEnabled=false.
     - servoRms     Equivalent to agcEnabled=true.
     - setRms       Equivalent to servoRms which freezes when stabilized.
     - table        Calculate RQ gain from window setting chosen by hardware
                    and number of antenna included in the sum.  This is not
                    yet implmented in the BL board software.

If agcMode is not present, agcEnabled is taken to mean  "setRq" or 
"servoRms", according to whether it has value "off" or "on".  It is
anticipated that most observations will use either "servoRms" or
"setRms".

If the number of antennas contributing to the sum is known in advance
and the filter chip requantizers are set , it may be possible to
predict the summed array requazntizer gain knob setting and provide
it using the "setRq" value.

For any subband that requests summed array output, the AGC control
values in the original VCI message will be sent to the station boards
after the time given by agcDelay whenever the script issues a request
to set the filter chip requantizers.  This will cause the window setting
to be redetermined and the requantizer gain to be set as required.