[evla-sw-discuss] interim pointing solutions

[Ken Sowinski]

This message carries on from the discussion of antsol that I began 
last month.  The topic today is pointing, in particular what should 
be reported when a pointing scan is executed and when should it be
reported.  I append below a struct which provides a description of
what the pointing analysis program provides that can be packaged for
the rest of the world.

Unlike antsol, there are valid results only after a sequence of
subscans.  I will call a sequence of subscans and the pointing offsets
produced a pointing trial; there may be one or more of these in one
scan.  The question is what must be reported after a single trial and
what, if anything, after the completion of a scan.  The results of a
pointing scan are useful in only three contexts: to produce pointing
corrections for referenced pointed observations, to produce a
collection of pointing offsets that PEEK may use offline to deduce an
update to the antenna pointing model, and to provide a snapshot of the
current pointing to operations as an aid in finding newly moved or
badly pointed antennas.

Let us take referenced pointing first.  In the current implementation
the pointing offsets are summed into an array which is cleared at the
beginning of a pointing scan.  When the scan ends we have available
for each antenna the sum of the offsets over all successful trials
and a count of the successful trials.  'Successful' is narrowly defined
to mean believable solutions for both az and el in both polarizations.  
At the beginning of a scan for which a pointing correction is desired, 
the division by the number of trials is carried out and the result for 
each antenna added to the a priori collimations.

For pointing model analysis we are a little more generous.  Each trial
is reported independently of the others and we do not suppress a trial
if no solution was obtained for one polarization.  As pointing offsets
are determined we write them to a .PNT file to be analyzed by PEEK.
For operations we are even more generous; whatever is found may offer
a hint to the operator as to how the antenna is pointing.  The results
of a pointing trial are immediately accessible to the operator.

The new pointing offset solver will create the pointing record defined
below.  After each pointing trial, records will be appended to a .PNT
file which should be compatible with the present file to avoid changes
to PEEK.  In addition the results will be added to all results for this
scan and packaged as an XML document to be sent to the executor.  The
pointing solver will know nothing about the intended use of the XML
documents, but merely publish them as a side effect of a pointing scan; 
the executor will use them or not according to information supplied in 
the observe script.  Second order referenced pointing is a matter private
to the executor.  There should be a utility to display any pointing 
results so that the operator can view pointing errors when trying to
find antennas.  





/* This record represents the results of ptgsol for the subarray given
   in subid for one pointing cycle.  There will be one record for each
   subarray in pointing mode.
*/
struct pointing_record {
  char   version[] = "Ver 10.0    June 2005";   /* PEEK wants this  */
  int    subid;        /* Subarray ID (1-5)  */
  int    mjd;          /* mhad  */
  double iat;          /* IAT in radians  */
  double lst;          /* LSt in radians  */
  char   mod[2];       /* observing mode (must be I?)  */
  char   pid[6];       /* observing program  */
  char   sou[12];      /* source name  */
  int    qua;          /* qualifier  */
  char   band[2];      /* band code  */
  char   cormode[4];   /* correlator mode  */
  float  wx[5];        /* weather recorded at centerof pointing cycle  */
  int    nant;         /* number of antennas in subarray  */
  float  trig[6]       /* cos and sin of az, el, eta  */
  int    nant;         /* number of antennas in subarray  */
  int    npnt;         /* number of antennas with successful pointing solutions  */
  struct offsets[27]   /* pointing results for npnt antennas  */
};

/* this struct represents what PEEK needs.  The version to be sent
   to the executor is described below as ref_offsets.
*/
struct offsets {
  int id;                 /* antenna ID  */
  /* Each of the quantities below is averaged over the two IFs of
     corresponding polarization if both IFs are available.
  */
  float razerr, razbeam;  /* arc-min, normalized RCP  */
  float lazerr, lazbeam;  /* arc-min, normalized LCP  */
  float relerr, relbeam;  /*   RCP    */
  float lelerr, lelbeam;  /*   LCP    */
  float rflux;            /* measured apparant flux at 'on' in DJy  */
  float lflux;            /* measured apparant flux at 'on' in DJy  */
  char  flags[8];         /* space for quality indicators, OTT, etc  */
};

/* this struct, along with pointing_record, represents what is to be 
   passed to the executor.  I expect it to be generated in the module 
   which prepares the packet to be sent to the executor.
*/
struct  ref_offsets {
  int   id;               /* antenna ID  */
  float azerr;            /* sum over all trials of az error  */
  float elerr;            /*              ditto for el  */
  int   count;            /* count of successful trials  */
  char  flags[4];         /* might need this for various referenced
                             pointing variations  */
};