; MBDLY
;---------------------------------------------------------------
;! Fits multiband delays from IF phases, updates SN table
;# Task Utility VLBI OOP Calibration
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1998
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
;---------------------------------------------------------------
MBDLY     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
MBDLY:    Fits multiband delays from IF phases in SN table
USERID                             User number.
INNAME                             Main input file (name).
INCLASS                            Main input file (class).
INSEQ             0.0    9999.0    Main input file (seq. #).
                                      0 => high
INDISK            0.0       9.0    Disk unit #.       0 => any
INVERS                             Input  SN file version no.
OUTVERS                            Output SN file version.
BIF               0.0       16.0   First IF to use. 0=>1
EIF               0.0       16.0   Last IF to use.  0=>last
TIMERANG                           Time Range is consider.
SUBARRAY                           Subarray (default=1)
FREQID                             Freuency ID (default=1)
PRTLEV            0.0       10.0   Print fit results
                                   >=1 fits, 2=IF resids.
APARM                              Editing parameters
                                   (1) = min SNR; def=5
                                   (2) = max rate rms (deg)
                                         def = 50d
                                   (3) = max MBD rms (deg)
                                         def = 20d
                                   (4) = min. no. IFs. 0->all
                                   (5) = MBD Search range.
                                         def = ambiguity.
                                         <0.  Use zero.
                                   (6) = 0=Keep Residual phase
                                         in cal UV data
                                         1=Zero Residual phase
                                         in cal UV data.
----------------------------------------------------------------
MBDLY
Type:  Task
Use:   MBDLY fits multiband delays from the IF phases in an SN
       table produced by FRING.  The results are placed in
       another SN table.
Adverbs:
  USERID......The user ID of the owner of the image.  0 =>
              current user, 32000 => any user.
  INNAME......Main file name (name).       Standard defaults.
  INCLASS.....Main file name (class).      Standard defaults.
  INSEQ.......Main file name (seq. #).     0 => highest
  INDISK......Disk drive # of image.       0 => any
  INVERS......Input extension file version #.
  OUTVERS.....Output extension file version #. 0=>make new
  BIF.........First IF to use.  0=> 1.  Use to determine MBDLY
              for dual frequency SN table
  EIF.........Last IF to use.   0=> last.  Use to determine
              MBDLY for dual frequency SN table.
  TIMERANG....Time range to consider
  PRTLEV......<= 1.0 -> show multiband fits.
              >= 2.0 -> show phase residuals for each IF
              Use 1 for useful, but succinct information
  APARM.......Editing control parameters:
                (1) is the minimum average SNR (WEIGHT in the SN
              table).  0 => 5.  0.01 lets everything by.
                (2) is the maximum acceptable rate scatter among
              the IFs in units of degrees over the integration
              period. The default is 50 degrees.
                (3) is the maximum acceptable rms residual phase
              of the IF phase residual in degrees.
              The default is 20 deg.
                (4) is the minimum number of IF's for a valid
              solution.  The default is all (EIF-BIF+1 or NUMIF)
                (5) is the search range (+/- value) for the MBD.
              Default is the natural range and is equal to the
              residual of the least-common stepping frequency.
              If <0, then assume MBDLY = 0.  This is useful for
              just averaging the phases over the IF's.
                (6) If =0, keep residual phase in data.  This
              will leave the observed phase in the data after
              removing the multiband slope.  Use with CL2HF.
                    If =1, Remove residual phase from data.
              This will zero the observed phase.  The phase
              inserted in the SN table is the average observed
              phase.  Use this option for further imaging.
----------------------------------------------------------------
PROGRAM:  MBDLY
DOCUMENTOR:  Ed Fomalont   95.03.08
RELATED PROGRAMS:  FRING, SNCOR, CL2HF, HF2SV, BLING, BLAPP

                      PURPOSE

FRING is used to determine the phase rate with time, the phase
rate with frequency and the residual phase at some reference
frequency for each IF over a short period of time.  The results
are placed in an SN table.  The program MBDLY then reads this SN
table (INVERS) to determine the best phase slope through the
residual phases of the specified IF's.  The results are put in a
new SN table (OUTVERS).  This delay over all of the IF's is
called the Multi-band delay or the Group delay and it is often
used in geodetic/astrometric experiments.  The advantage is that
the Group delay is not subject to lobe ambiguities associated
with the phase.

The peculiar phase constants for each IF must be determined and
removed before MBDLY can calculate the phase slope.  The
peculiar phases can be obtained from special phase calibrations
during the observations, or by a manual phase calibration.  The
easiest method to determine the manual phase calibration is to
pick a short segment of data (less than a minute) for a strong
source with a complete set of data.  Run FRING on this segment
to obtain the SBD, rate and phase.  It is best to zero the rates
from this solutions (and perhaps the SBD).  Apply this solution
to the entire data base using CLCAL.  This will line-up the IF
phases and define the multiband delay for the data segment equal
to zero for all antennas.

The Multiband delays can also obtained directly from FRING with
APARM(5)=2.0.  This is recommended for weak sources where the
best signal to noise is required.  For strong sources in
astrometric experiments, it is best to use FRING with APARM(5)=0
and then MBDLY.

Since the phases are sampled at a few discrete IF frequencies,
the best slope is ambiguous by an amount (1000/DF) nsec, where
DF is the basic IF frequency spacing (MHz).  For example, if the
IF spacings are 0, 80, 140, 400 MHz (above a reference
value), then DF is 20 MHz.  The ambiguity spacing of the
MBDLY is then 50 nsec.

For astrometric/geodetic experiments, the results in the SN
table produced by MBDLY are interpolated into the CL table
using CLCAL.  Then, the task CL2HF calculates relevant
astrometric quantities needed for the Calc/Solve software and
places these results in an HF extension file.  Finally the task
HF2SV translates the HF data into something that can be read
into Calc/Solve.   See instructions associated with these two
tasks.

Parameters:

BIF, EIF - The beginning and the ending IF to use for the
solution.  Experiments with simultaneous S/X bands are common.
If the data base is not split into two separate frequency
parts, then MBDLY must be run twice.  As an example, consider
the common case where IF's 1 to 4 contain SBAND data and IF's 5
to 8 contain XBAND data.  FRING can be executed on the combined
data base since each IF solution is independent.  MBDLY must
be run twice.  First, with BIF=1; EIF=4 and then with BIF=5;
EIF=8.  The outputs must be put in different SN tables and
CLCAL'ed separately.  If APARM(4) = 0; then only solutions
with all IF's will be accepted.

TIMERANG -  The time range of the input SN table to process.
0 means take everything.

PRTLEV - Use 1 for most execution.  This will list some
  information about the fits, including the rms phase residual.
Use 2 to see the residual phase error for each IF.  An offset
in the phase calibration can be seen in this listing.  Check
the rms of the fits.  They should be less than about 10 or 15
degrees for a good fit.

APARM - Editting control parameters.  Any SN table entry that
exceeds one or more of the following criteria, will have a
blanked multiband delay written in the output.

APARM(1) - The default is an SNR of >5.  This is reasonable.
To include all data, let APARM(1) = 0.01

APARM(2) - This is the maximum phase scatter over the
integration time which is caused by the scatter in the rate
solutions for the IF's.  The default is 50 degrees.  This
could be set to 10 degrees for good data.  This option removes
source solutions which have significantly different phase
rates amongst the processed IF's.  It is a good indication
of bad data or a weak source.

APARM(3) - The maximum phase scatter in the IF's after
the removal of the best MBD.  The default is 20 degrees.
This could be set to 7 degrees for good data.

APARM(4) - The minimum number of IF's.  This is defaulted
to them all considered in the solutions (EIF-BIF+1).  If eight
IF's are being used, then the default could be set to 6 or 7.  The
depends on the frequency sampling.

APARM(5) - The MBD Search Range.  The default is the natural
ambituity range which is equal to the inverse of the 'unit'
spacing in the frequency set.  For example, if the four IF
relative frequencies are 0, 70, 385, 490 MHz, then the unit
frequency sampling is 35 MHz, or 28.6 nsec which is the
default.  For frequencies which are not commensurate, aparm(5)
should be set to a reasonable range.  If APARM(5)<0, then
assume MBDLY is zero and just average phases in IF's.  This
is useful for getting the average phase over all of the IF's
for a weak source.

APARM(6) - If you want the residual phase to remain in the
data, then set APARM(6)=0.  This option is most useful if the
fits will be analyzed in Calc/Solve, using CL2HF and HF2SV.

           If you want the residual phase to be zero, then
set APARM(6)=1.  This option is more useful if imaging and
is equivalent to self-calibration.






