Software documentation: Catag



Preface

CATAG is a program designed for use as the server program for reference pointing. This program will basically be running the entire time during Compact Array operation. If the observer wishes to have offset pointing applied, then (at this stage) he or she simply includes a calibrator with scan type set to RPOINT. This program should automatically pick up this fact and expect CAOBS to execute a POINT pattern. The visibilities are recorded and an Az./El. offset is calculated. These offsets are dispatched to the antenna pointing machinery (which in the final version will be a modification of the PPARAMS.DAT data, which will subsequently be downloaded to the ACC's). One of the nomenclatures used in this code is that of "category" or "bin". Bin is a collection of data that represents the integrated amplitudes of visilibities at a certain pointing offset. There are presently 5 bins, on centre, and 4 offsets left/right/up/down as per the normal CAOBS POINT scan. CATAG assumes this "0,A+,A-,E+,E-,0" pattern. If this pattern is altered the TAG algorithm must be reassessed. The CAOBS POINT pattern is, by default, set so that the number of cycles spent on each offset is 6. This may be easily changed with the command 
 
                set point_pattern n
where "n" is the number of cycles to be spent on each offset.

Call sequence: 

      program catag
      implicit none
      include 'array$inc:array_gs.inc'
      include 'array$inc:a_data.inc'
      include 'caobs$inc:caobs_status.inc'
      include 'constants'
      include 'catag$inc:tag.inc'
      include 'catag$inc:pntcom.inc'
Creation date: 14-Feb-1995

Author: Derek McKay

File: TAG_MAIN.FOR

Routine name: tag_aux_data

Function:

This routine is called when the program needs to record the auxilliary information associated with the particular POINT scan that is being observed. The simple approach is that this routine is called midway through the POINT scan - and this method will be implemented here for the time being. The data that this routine retrieves is placed in the common block that is declared in TAG.INC.

Call sequence: 

      subroutine tag_aux_data(s)
      implicit none
      include 'caobs$inc:caobs_status.inc'
      include 'catag$inc:tag.inc'  ! Only used to install the offset
      include 'catag$inc:pntcom.inc'
      record /getvis/s
Creation date: 7-Feb-1995

Author: Derek McKay

File: TAG_UTIL.FOR

Routine name: tag_azel

Function:

Given the truncated Julian date, Right Ascension and Declination of the observation, this routine will provide the appropriate azimuth and elevation for the Australia Telescope Compact Array.

Call sequence: 

      subroutine tag_azel(tjd,ra,dec,az,el)
      implicit none
      include 'constants'
      double precision
     -  tjd,     ! Trucated Julian Date
     -  ra,      ! Right Ascension (in radians)
     -  dec,     ! Declination (in radians)
     -  az,      ! Azimuth (in degrees)
     -  el       ! Elevation (in degress)
Creation date: 19-Feb-1995

Author: Derek McKay

File: TAG_UTIL.FOR

Routine name: tag_bin_vis

Function:

This routine takes the visibilities and extracts the amplitudes for each cross-correlation as well as the complex visilbities themselves. The reason for storing both is that different antenna gain algorithms use different aspects and during the testing stages it is useful to have both available. Note that the auto-correlations are not used. The binning process is simply a matter of continually integrating the data into the appropriate "bin". The "averaging" stage actually normalises the data based on the number of accumulated cycles for each bin. This accumulation number is incremented here. This does, of course, mean that the complex average is actually a vector average, but this should be OK as for pointing we expect to look at bright calibrators. If this proves not to be the case, then scalar averaging may be coded in later. The data is also sorted according to product. These products (1-4) correspond to the antenna cross products (AA,BB,CC,DD - repsectively). The binning category numbers (1-5) are documented in the function tag_sort_vis().

Call sequence: 

      subroutine tag_bin_vis(s,category)
      implicit none
      include 'caget$inc:getvis.inc'
      include 'catag$inc:tag.inc'
      record /getvis/s    ! Visibility buffer
      integer category    ! Pointing scan category (documented in
                          ! tag_sort_vis().
Creation date: 1-Feb-1995

Author: Derek McKay

File: TAG_UTIL.FOR

Routine name: tag_calc_error

Function:

This routine calculates the position error based on the gain variations. Note that it _doesn't_ make any azimuth error correction based on the elevation of the source. That is doen in the calling routine.

Creation date: 6-Feb-1995

Author: Derek McKay (based on an algorithm by Mike Kesteven)

File: TAG_SOLVE.FOR

Routine name: tag_check_offsets

Function:

If the previous pointing scan has been done in the last ?? hours, then this routine checks to make sure that the corrections being applied are not too large. If they are then they are reset to zero and some diagnostic messages are printed to screen.

Call sequence: 

      subroutine tag_check_offsets(azcor,elcor)
      implicit none
      include 'catag$inc:pntcom.inc'
      real
     -  azcor(6),    ! Azimuth pointing correction (in arcseconds)
     -  elcor(6)     ! Elevation pointing correction (in arcseconds)
Creation date: 7-Jun-1996

Author: Derek McKay

File: TAG_APPLY.FOR

Routine name: tag_clear_data

Function:

A simple routine that cycles through all the bins/baselines/polaristaions of the baseline based amplitudes and complex visibilities and sets the values to zero. It also sets the cycle counter (num_cycles) to zero for each category as well.

Call sequence: 

      subroutine tag_clear_data()
      implicit none
      include 'catag$inc:tag.inc'
Creation date: 2-Feb-1995

Author: Derek McKay

File: TAG_UTIL.FOR

Routine name: tag_convert_amp

Function:

This routine takes the baseline amplitudes and determines the antenna based amplitudes, which will subsequently be used to calculate the Az./El. offsets. It is important to note that the algorithm used requires at least 4 antennas (num.baselines > num.antennas) in order to work. This algorithm uses linear algebra to solve for 6 unknowns from 15 equations. This routine expects a number of parameters which are recovered from the include file TAG.INC. These include the baseline based amplitudes (b_amp), number of antennas (nant) and the antenna usage flags (ant_flag). It returns its results by writing the values of the antenna based amplitudes into the global variables (again, in the TAG.INC file). This algorithm is adapted from CACAL

Call sequence: 

      subroutine tag_convert_amp
      implicit none
      include 'catag$inc:pntcom.inc'
      include 'catag$inc:tag.inc'
Creation date: 3-Feb-1995

Author: Derek McKay (based on an algorithm by Mark Wieringa)

File: TAG_GAINS.FOR

Routine name: tag_convert_amp2

Function:

This routine takes the baseline amplitudes and determines the antenna based amplitudes, which will subsequently be used to calculate the Az./El. offsets. It is important to note that the algorithm used requires at least 4 antennas (num.baselines > num.antennas) in order to work. This routine expects a number of parameters which are recovered from the include file TAG.INC. These include the baseline based amplitudes (b_amp), number of antennas (nant) and the antenna usage flags (ant_flag). It returns its results by writing the values of the antenna based amplitudes into the global variables (again, in the TAG.INC file). This algorithm is adapted from CAPT

Call sequence: 

      subroutine tag_convert_amp2
      implicit none
      include 'catag$inc:tag.inc'
Creation date: 3-Feb-1995

Author: Derek McKay (based on an algorithm by Mark Wieringa)

File: TAG_GAINS.FOR

Routine name: tag_convert_amp3

Function:

This routine takes the baseline amplitudes and determines the antenna based amplitudes, which will subsequently be used to calculate the Az./El. offsets. It is important to note that the algorithm used requires at least 4 antennas (num.baselines > num.antennas) in order to work. This algorithm uses linear algebra to solve for 6 unknowns from 15 equations. This routine expects a number of parameters which are recovered from the include file TAG.INC. These include the baseline based amplitudes (b_amp), number of antennas (nant) and the antenna usage flags (ant_flag). It returns its results by writing the values of the antenna based amplitudes into the global variables (again, in the TAG.INC file). I suspect there may be bug in this subroutine. I've had difficulty getting it to work. This algorithm is adapted from SELFCAL

Call sequence: 

      subroutine tag_convert_amp3
      implicit none
      include 'catag$inc:tag.inc'
Creation date: 3-Feb-1995

Author: Derek McKay (based on an algorithm by Bob Sault)

File: TAG_GAINS.FOR

Routine name: tag_determine_mask

Function:

In order to perform a reasonable job at determining the pointing offsets, it is important to ascertain which antennas are suitable. The most fundamental check, which is performed by this routine, is to note which antennas the observing program has control of. The result of this is written into the antenna mask OBS_MASK. This is distinct from other temporary masks which are used elsewhere in the program. The OBS_MASK is used to decide which antennas are used in the POINT scan. Errors will be returned if the TAG program can't access data from these antennas. The other item that this routine does is to fill the ANT_FLAG array with TRUE or FALSE for each antenna indicating whether or not that antenna is being used. The ANT_FLAG array mimics the OBS_MASK bitmask, but is more easy to access in some cases and so is also provided.

Call sequence: 

      subroutine tag_determine_mask()
      implicit none
      include 'caobs$inc:caobs_status.inc'
      include 'catag$inc:tag.inc'
      include 'catag$inc:pntcom.inc'
Creation date: 6-Jan-1995

Author: Derek McKay

File: TAG_UTIL.FOR

Routine name: tag_diagnostic

Function:

A simple routine to take the specified arguments and print out a status line to standard output. It might not be part of the final release of this software.

Call sequence: 

      subroutine tag_diagnostic(time,pntr,last,s,category)
      implicit none
      include 'caobs$inc:caobs_status.inc'
      include 'catag$inc:tag.inc'
      double precision
     -  time      ! Delta time from this cycle to the previous one.
      integer
     -  category, ! The bin that the data is going to
     -  last,     ! Last valid cycle. This is the one that is actually
                  ! used
     -  pntr      ! CAOBS cycle pointer. Not really useful here.
 
      record /getvis/s  ! Temporary storage of the visibility buffer to
                        ! be displayed
Creation date: 23-Aug-1995

Author: Derek McKay

File: TAG_UTIL.FOR

Routine name: tag_eval_solution

Function:

This routine (again, just for testing) performs a check on the calculated antenna gains. It simply reapplies the gains to our "perfect" flux and divide by the baseline based, measured amplitudes and print the results. Should be very close to unity - but I bet it ain't :-)

Call sequence: 

      subroutine tag_eval_solution(av,gain)
      implicit none
      include 'catag$inc:tag.inc'  ! Includes the measured baseline
                                   ! amplitudes for generation of
                                   ! theoretical-to-measured ratio.
      real
     -  av(4),            ! Average flux (per IF)
     -  gain(5,6,4)       ! Antenna gains (5 categories, 6 antennas, 4
                          ! IFs)
Creation date: 14-Feb-1995

Author: Derek McKay

File: TAG_GAINS.FOR

Routine name: tag_get_corrections

Function:

This routine takes the 4 azimuth and elevation errors from the four IFs and determines which offsets are to be applied to the pointing parameters file. At the moment (for testing purposes) we take the average of the used IFs. The program accepts AZERR and ELERR and returns AZCOR and ELCOR. The former two are arrays for each antenna and IF. The latter are per antenna only.

Call sequence: 

      subroutine tag_get_corrections(pr_flag,azerr,elerr,azcor,elcor)
      implicit none
      logical
     -  pr_flag(1:4) ! Indicates if a given IF (product) was used
      real
     -  azerr(6,4),  ! Azimuthal pointing errors (in arcseconds)
     -  elerr(6,4),  ! Elevation pointing errors (in arcseconds)
     -  azcor(6),    ! Azimuth pointing correction (in arcseconds)
     -  elcor(6)     ! Elevation pointing correction (in arcseconds)
Creation date: 10-May-1995

Author: Derek McKay

File: TAG_APPLY.FOR

Routine name: tag_init

Function:

This routine does some of the necessary initialisation that is required by TAG. It also checks which node TAG is being run on, and warns if this is inappropriate. In the final version, node detection should be handled outside the program (by, e.g., the command procedure). This saves recompiling when you really want to run it on another node.

Call sequence: 

      subroutine tag_init
      implicit none
      include 'catag$inc:tag.inc'
Creation date: 13-Feb-1995

Author: Derek McKay

File: TAG_UTIL.FOR

Routine name: tag_modify_pparams

Function:

This routine reads in the existing PPARMS.DAT file and applies the corrections to the appropriate fields for azimuth and elevation. The routine then writes the corrected file back to disk. PR_FLAG is an array of logicals that indicate which products were used. AZERR and ELERR contain the measured pointing errors of each product/antenna for azimuth and elevation. A quick note about "ee" and "fx". For strange historical reasons, "ee" has been designated for use with the temperature correction and "fx" for the elevation encoder offset. This means the SDV's (self-documenting variables) don't really mean what they are. The problems are vague in that different programs use and notate them differently. What is worse, this program changes backwards and forwards based on external decisions... proceed with caution! On the other hand, the azimuth variable, FZ is chosen based on experiments done in June 1996 by McKay & Kesteven. The old parameter, EA, was rejected.

Call sequence: 

      subroutine tag_modify_pparams(pr_flag,azerr,elerr)
      implicit none
      real
     -  azerr(6,4),   ! Azimuthal pointing errors (in arcseconds)
     -  elerr(6,4)    ! Elevation pointing errors (in arcseconds)
      logical
     -  pr_flag(1:4)  ! Indicates if a given IF was used (this variable
                      ! is simply passed to tag_get_corrections
Creation date: 17-Jul-1996

Author: Derek McKay

File: TAG_APPLY.FOR

Routine name: tag_norm_data

Function:

This function takes the integrated baseline amplitudes and normalises them, thus making them averages rather that accumulated products. The amplitudes are handled in this way, so as to make data acquisition simpler (there's no need to multiply/add/divide every time you get a new data point). All normalisation, therefore must be done at the end, before any processing is commenced - and this function does it. This routine also normalises the accumulated complex visibilities, which have been collected in the same way. You will notice that this makes the complex case a vector average (not a scalar one). The other thing that this routine does is check for errors occurring due to incomplete data. The function returns a logical (T/F) indicating whether it is safe to proceed with the normailised data (this is the TRUE case). Error checking at this stage is limited to ensuring that no bin is non-zero.

Call sequence: 

      logical function tag_norm_data()
      implicit none
      include 'catag$inc:tag.inc'
Creation date: 2-Feb-1995

Author: Derek McKay

File: TAG_UTIL.FOR

Routine name: tag_prev_coord

Function:

This routine loads takes a truncated Julian date, Right Ascension and Declination of an observation and loads the values into the "previous" slots in the PNTCOM global memory are. It also does a conversion to determine the azimuth and elevation and loads them in as well. The reason behind doing this is so that when pointing is done, one can see where the antennas were before driving to the current source. If a scan is not a pointing one, then it doesn't matter and on the next scan the values will be overwritten.

Call sequence: 

      subroutine tag_prev_coord(tjd,ra,dec)
      implicit none
      include 'catag$inc:pntcom.inc'
      double precision
     -  tjd,     ! Trucated Julian Date
     -  ra,      ! Right Ascension
     -  dec      ! Declination
Creation date: 19-Feb-1995

Author: Derek McKay

File: TAG_UTIL.FOR

Routine name: tag_process_data

Function:

This routine is called when a POINT scan has completed or been terminated. It takes the accumulated data and normalises it, then calculates the antenna based amplitudes from those of the baselines. It then, using these values, determines the Az./El. errors associated with each antenna. Most of this is handled by subroutines and functions administered by this routine.

Call sequence: 

      subroutine tag_process_data()
      implicit none
      include 'caget$inc:getvis.inc'
      include 'catag$inc:tag.inc'
      include 'catag$inc:pntcom.inc'
Creation date: 2-Feb-1995

Author: Derek McKay

File: TAG_UTIL.FOR

Routine name: tag_reload_global

Function:

Loads the global solution back into PPARAMS.DAT

Call sequence: 

      subroutine tag_reload_global()
      implicit none
      include 'array$inc:array_gs.inc'
      include 'caobs$inc:caobs_status.inc'
Creation date: 23-Aug-1995

Author: Derek McKay

File: TAG_APPLY.FOR

Routine name: tag_results()

Function:

This routine calculates the antenna based Az./El. errors as derived from the antenna based amplitudes (or gains, if you will). It also handles the presentation or logging of the results and, in the final version, will influence the pointing of the antennas.

Call sequence: 

      subroutine tag_results()
      implicit none
      include 'catag$inc:tag.inc'
      include 'catag$inc:pntcom.inc'
Creation date: 3-Feb-1995

Author: Derek McKay

File: TAG_SOLVE.FOR

Routine name: tag_sort_vis

Function:

This function takes a given visibility and assigns it a category, depending on what sort of data it is. The categories are listed as follows: 

 
                   0    Not a POINT scan
                   1    POINT scan; no Az. or El. offset
                   2    POINT scan; +ve Az. offset, no El. offset
                   3    POINT scan; -ve Az. offset, no El. offset
                   4    POINT scan; no Az. offset, +ve El. offset
                   5    POINT scan; no Az. offset, -ve El. offset
where Az. and El. are azimuth and elevation respectively. The function takes a single visibility record and returns the category number. It is important to note that not all antennas are checked for Az./El. offsets at this stage. Later, when the software is made more generic, some more sophisticated algorithms might be implemented to determine the appropriate offset to use. One final point (groan): this routine also dtermines whether the point pattern is a "standard" or "reference" pointing scan. In a reference pointing scan, the determined offsets are applied to the PPARAMS.DAT file an loaded into the ACC. The norm is for this not to happen.

Call sequence: 

      integer function tag_sort_vis(s)
      implicit none
      include 'caget$inc:getvis.inc'
      include 'catag$inc:tag.inc'  ! Only used to determine which antennas
                                   ! are valid for this pointing scan
      record /getvis/s
Creation date: 10-May-1995

Author: Derek McKay

File: TAG_UTIL.FOR

Routine name: tag_to_array

Function:

This routine sends a message to ARRAY to let it know that the pointing parameters on some/all antennas have been modified and that the file should be reloaded. There are some problems with the way MASK is defined. Please read the comments in the code.

Call sequence: 

      subroutine tag_to_array(mask)
      implicit none
      include 'array$inc:array_gs.inc'
      integer mask         ! Valid antenna mask
Creation date: 11-May-1995

Author: Derek McKay

File: TAG_APPLY.FOR

Routine name: tag_value_init

Function:

In order to solve for the antenna gains, some variables must be set to initial values. This routine takes the antenna amplitude array and sets all the values to the specified real number. This is especially useful during the testing stages where different algorithms are being trialed. The code is a very simple set of loops.

Call sequence: 

      subroutine tag_value_init(value)
      implicit none
      include 'catag$inc:tag.inc'
      real value   ! The actual value to which all the values of the
                   ! a_amp array are set.
Creation date: 14-Feb-1995

Author: Derek McKay

File: TAG_GAINS.FOR

Include file: tag.inc

Function:

Contains the global definitions for the TAG program

Creation date: 2-Feb-1994

Author: Derek McKay

File: TAG.INC

Include file: PntRec

Function:

This include file contains the definitions for the "PNTREC" records that are part of PNTCOM and other programs that handle the on-line pointing data.

Creation date: 19-Feb-1995

Author: Derek McKay

File: PNTREC.INC

Include file: PntCom

Function:

Contains all the declarations of variables in the global common "PNTCOM". These will be used as a shared memory cyclic buffer for the storage of pointing data from the Australia Telescope Compact Array. The data is stored in a cyclic buffer which contains a number of records. Each record describes the parameters of the last pointing scan and their results.

Return to the Australia Telescope Compact Array Home Page

Original: Derek McKay (19-Feb-1994)
Modified: Derek McKay (14-Oct-1996)