QUBES: Software to make SCN-file UV-data available in various sort orders
-------------------------------------------------------------------------
History:
	Contributed by WNB, 940810
	WNB 940812: add interferometer errors


Summary (JPH 940810)

	This note documents software created by WNB during his 1994 visit at NFRA as infrastructure for the program NFILTER.)


1. Introduction

To be able to read a one-directional data vector from the Scan data in
any of the possible coordinate direction, a number of NSCQ.. routines
are available, replacing in essence NSCSCR and NMOMU4 and their
initialisers.
The possible directions are: frequency(f), ha(t), interferometer(i). No
possibilty to go in the direction of Mosaic fields has been built in,
mainly because different mosaic fields have no identical ha's: the
4-dimensional structure (mosaic,f,t,i) is not a regular hypercube.
The structure chosen assumes that the dataset to be considered
consists of a series of 3-d cubes (f,t,i) at different mosaic points.
In principle extension to a series of (mosaic,f,i) cubes at different
ha's would be feasable.
A field in the above is a set of observations at the same position on
the sky, with identical (number of) frequencies, interferometers and
hour angles. Note: the actual check on the number of hour angles is
not extensive, to limit the sorting problems, but with actual WSRT
observations this should not be a problem.
An example of the actual use is given in NFIUVL.for, which at the
moment is a simple test program, not an actual UVLIN.

2. Routines

To write a program using the NSCQ routines, the basic structure of the
program is identical to programs using NSCSCR, i.e. scans in the
i-direction. The user parameters used by the NSCQ routines are the
same: Node, Sets and, possibly, Loops. Other selection parameters can
be used in the same way as in other programs, and model data has to be
initialised in the same way as well (i.e. NMODAX, NMOMUI and NMOMSC/L
have to be used before the actual data loops can start).


To set the field a (short) description of the standard program
structure as it is now (*=optional):

while WNDXLN			do all specified loops(*)
  NMOMSL			calculate scan model(*)
  while NSCSTL			do all sectors
    NSCSIF			get interferometer table(*)
    NSCMBL			get baseline table(*)
    NCARRT			get redundant baseline(*)
    NMORDH			get model parameters(*)
    NMOMST			calculate some model parameters(*)
    for i=ha-range		go through (selected) ha scans
      NSCSCR			get corrected scan data
      NMOMUV			calculate UV coordinates for scan (*)
      NMOMU4			calculate model for scan(*)
      action			including e.g. NSCSWI
    end
  end
end

The structure to go through data in different order is comparable:

while WNDXLN			do all specified loops(*)
  NMOMSL			calculate scan model(*)
  NSCQOP			prepare SETs for reading
  while NSCQFN			get next field in 4-d structure (and 
					coordinate tables) and select
					coordinate order
    NSCMBL			get baseline table(*)
    NCARRT			get redundant baselines (*)
    
    for i=first selected coordinate
      for j=second selected coordinate
        NSCQSR			read selected (pseudo-)scan along 3rd coord
        				and model, if selected in QFN
        action			including e.g. NSCQWA/M
      end
    end
  end
  NSCQCL			close Qube control area
end

routines to calculate e.g. UV-coordinates etc for the pseudo scans are
easily added if necessary. 


3. Description interface


- NSCQOP_L(	QUA_J:O,			Qube control area ptr
		FCA_J:I,		 	(Scan) file control area
		SETS_J(0:SOF__N-1,0:*):I,	SETs selected by user
		LPOFF_J(0:SOF__N-1)		Current Loop offsets
		INFO_J(QINFO__L:QINFO__H):O	Info about 4-d qube
	)

QOP analyses the SETs (using also the loop info (LPOFF) and Scan file
(FCA), and makes a sorted list of all Sector pointers. It also
reserves buffers for later use.
The QUA is a pointer to the control area to be used in all subsequent
Q calls. 
The INFO array returns the following information (parameters in
CBITS_DEF):
	INFO(QINFO_FLD)		number of different fields
	INFO(QINFO_F)		max. number of frequencies found in all fields
	INFO(QINFO_T)		max. # ha
	INFO(QINFO_I)		max. # ifrs

Note: the system works fastest if field selection is done by the Loop
structure.


- NSCQCL_L(	QUA_J:IO,			Qube control area ptr
		FCA_J:I,			Scan file control area
		SETS_J(0:SOF__N-1,0:*):I	SETs selected by user
	)

QCL frees all the buffers and temporary files used


- NSCQFN_L(	QUA_J:I,			Qube control area ptr
		FCA_J:I,			Scan file control area
		ORDER_J:I,			Order of data reading
		STH_B(0:STH__L-1):O,		A Sector header
		INFO_J(QINFO__L:QINFO__H):O,	Info about 4-d qube
		PINFO_J(QINFO__L:QINFO__H):O	Pointer to Info about 4-d qube
	)

QFN selects the next field for processing (or is .false. if no more).
It uses the QUA and FCA, and the ORDER specified. The ORDER can be:
		QUB_FTI [+QUB_M] [+QUB_OUT]
		    TFI
		    TIF
		    ITF
		    FIT
		    IFT
The ..I uses no sorting file, the I.. may use a large sorting file.
The coding is: I=interferometer, F=frequency, T=ha. The last code
specifies the direction of the 'scan' produced (i.e. FTI is the
'normal' order, TIF produces a scan along the frequency axis); the 1st
code specifies the highest loop direction the user wants to use. Note:
you can loop in a different order than specified, but this will be
rather inefficient in general.
The _M modifier (e.g. QUB_TIF+QUB_M) will in addition to the data also
generate the model data in the same 'scan' direction.
The _OUT modifier will prepare and enable the writing of
interferometer errors.

The STH returned is one of the STHs of the field. I.e., the
coordinates, number of interferometers etc will be correct, but time,
frequency, ha and data depended on these will be random. It can,
however, be used in routines like NSCMBL.

The INFO returned is identical to that for QOP, but now the actual
field number(1..), and axis lengths for this field are returned.

The PINFO (at QINFO_T, QINFO_I, QINFO_F) returns pointers to tables
with the actual coordinates along the axes. These values can be
addressed as:
	A_I(PINFO(QINFO_I)+n_i)		interferometer codes
	A_E(PINFO(QINFO_T)+n_t)		ha values
	A_D(PINFO(QINFO_F)+n_f)		frequencies
with n=0,INFO(QINFO_x)-1


- NSCQFR_L(	QUA_J:I,			Qube control area ptr
		FCA_J:I				Scan file control area
	)

QFR resets the field search to the start of the field list


- NSCQSR_L(	QUA_J:I,			Qube control area ptr
		FCA_J:I,			Scan file area
		AX1_J:I,			1st axis to read
		AX2_J:I,			2nd axis to read
		CAP_J:I,			apply bits
		CDAP_J:I,			de-apply bits
		PWGT_J:O,			pointer to scan weights
		PDAT_J:O,			pointer to scan data
		PMOD_J:O,			pointer to scan model
		POUT_J:O,			pointer to area to put
						ifr errors
	)

QSR reads a (pseudo-)scan along the 3rd axis selected in QFN at the
position specified by AX1 and AX2 (axis types determined in QFN). I.e.
with QUB_TIF and AX1,AX2=300,2 a frequency scan will be produced for
the second interferometer in the interferometer table at the 300th ha
point (values for the axes can be 0..INFO(corresponding)-1).

The data is returned by a pointer to an array. These arrays have
dimensions (0:3,0:length scan-1). Note: the index order is different
from that returned by NSCSCR and NMOCIX, for obvious reasons.
If n_p is the polarisation (0..3) wanted and n_d the data point
(0..INFO()-1),the data can be accessed by:
	A_E(PWGT+4*n_d+n_p)
	A_X(PDAT+4*n_d+n_p)
	A_X(PMOD+4*n_d+n_p)
Interferometer error data (if QUB_OUT included in QFN) can be put into
the array pointed to by POUT, and accessed by:
	A_X(POUT+4*n_d+n_p)

Note: the PMOD has only a valid value if QUB_M was used in QFN
Note: the model data are already converted to XYX format


- NSCQWA_L(	QUA_J:I,			Qube control area ptr
  NSCQWM_L	FCA_J:I,			Scan file area
		AX1_J:I,			1st axis to write
		AX2_J:I,			2nd axis to write
		CAP_J:I,			apply bits
		CDAP_J:I			de-apply bits
	)

QWA will write the additive interferometer errors set (in pseudo-scan
order in the array POUT obtained from QSR) to the scan data file.
QWM the multiplicative interferometer errors.


wnb/940812