The 'fftmac' Structure   


                           Sanjay Bhatnagar



'fftmac' holds various mappings from baselines to samplers/Antennas
with their polarization and band information.

It also holds various other astronomically useful information derived
from the global header, namely, the names of the antenna which are
connected to the samplers, the fixed delays (in meters) associated
with the various antennas connected to the samplers.

It also provides an easy way to find the IF and polarization of the
various FFT pipe lines (equivalently of the connected antenna) and the
index in the antenna table of the various antennas in use.  This index
can be found as a function of the samplers connected to the various
baselines (querry="give the index in the antenna table for the antenna
connected to sampler x").

This object is organized as a structure for C and as a "smart"
structure for C++ users and is filled by a call to getfftmac for C
users and by a called to LTAFMT::getFFTMac for C++ users. (However,
for C users, before calling any of these, one has to set the values of
fftmac.nbase and fftmac.nfft.  These can be got by querrying the
global header of the LTA database (keyword BASELINE and SAMPLERS)).

The structure holds pointers for various arrays.  Buffers for these
arrays are allocaed by methods which fill this struct.  

C users will need to free these buffers at approprate time - at least
once before using this again as an argument of getfftmac().  Failing
to do so may result into unpredicatable behaviour of the application
and certainly a potentially massive memory leak.  (As a general rule
for using offline libraries, once the memory pointed to be pointers is
freed, the pointer should itself be set to NULL.  Many routines which
need to allocated memory take the decision to allocate (or not to
allocate memory) depending upon the value of the pointer).

C++ users need not worry about freeing the buffers.  There is a
destructor defined with this structure in C++ which will clear all
buffers when the structure goes out of scope.  One can safely make
calls to getFFTMac(fftmac &) without freeing the allocated memory in
between the calls - the structure will keep track of when it needs to
allocate buffers.  The actual allocation of the memory is done by the
fftmac::allocarrays(), which also can be called without the need free
the allocated memory (though, there may be no need to explicitly call
this function at the application program level - the
LTAFMT::getFFTMac() will make a call to this when necessary).

The various fields of this object are as follows.

   
Samp1,Samp2
   
   Two fftmac.nbase long arrays of unsigned short integers. Samp1[i]
   is the index of the first sampler making the ith. baseline and
   Samp2 is the other sampler.
   
AntOfSamp

   A fftmac.nfft long array of unsigned short integers.  AntOfSamp[i]
   is the index in the anteann table (struct AntTab) of the antenna
   connect on the sampler i.

ANameOfSamp
  
   A fftmac.nfft long array of char *.  ANameOfSamp[i] is the char.
   string which is the name of the antenna connected to sampler i as
   derived from the antenna table (struct AntTab[i].Name).
   
FDelayOfSamp

   A fftmac.nfft long array of floats.  FDelayOfSamp[i] is the fixed
   delay in meters of the antenna connected to the ith. sampler.

   Once the index in the AntTab of the antenna connected to the ith.
   sampler is available (via AntOfSamp), the rest of the antenna based
   information can be derived easily from AntTab.  However this
   information is also put here for ease of use - and more so because
   of functional compatability with the old fftmac format.

IFOfSamp

   A fftmac.nfft long array of short integers.  IFOfSamp[i] is the IF
   connected to the sampler i.  Value of -1 implies LSB is connect,
   else USB is connected.

PolnOfSamp
 
   A fftmac.nfft long array of short integers.  PolnOfSamp[i] is the
   polarization channel connected to the ith. sampler.  Value of -1
   implies the 130 MHz. channel is connected, else 175 MHz. channel is
   connected.
   
SelfOfSamp

   A fftmac.nfft long array of unsigned short integer.  SelfOfSamp[i]
   is the index of the baseline which has the self correlation for the
   ith. sampler.


For C++ users, following are methods defined for this object.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

fftmac::allocarray()
   This allocated the right amount of memory for the various arrays
   explained above.

fftmac::cleanup()
   This cleans up the memory allocated for the various arrays.  This
   is automatically called by the destructor.

fftmac::fftmac()
   The default (and the only) constructor.

fftmac::~fftmac()
   The default (and the only) destructor.



Examples:
   
struct fftmac fm;

1. To extract the name of the ith. baseline, one should use

	printf("%s-%s",
	       fm.ANameOfSamp[fm.Samp1[i],fm.ANameOfSamp[fm.Samp2[i]]);

2. To extract the polarization of the two antenna of the ith.
   baseline, one should use:

	fm.PolnOfSamp[fm.Samp1[i]] and fm.PolnOfSamp[fm.Samp2[i]];

3. To extract the IF of the two anteanna on the ith. baseline, one
   should use:

 	fm.IFOfSamp[fm.Samp1[i]] and fm.IFOfSamp[fm.Samp2[i]]