; MBDLY
;---------------------------------------------------------------
;! Fits multiband delays from IF phases, updates SN table
;# Task Utility VLBI OOP Calibration
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1998, 2004-2006
;;  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                             Frequency 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.
                                         0 = ambiguity.
                                         <0.  Use zero.
                                   (6) > 0 remove residual phase
                                   (7) > 0 keep bad data
----------------------------------------------------------------
MBDLY
Type:  Task
Use:   MBDLY fits multiband delays from the IF phases in an SN
       table produced by FRING or CALIB.  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.
  SUBARRAY....Subarray
  FREQID......Frequency ID (may need to set to 1)
  TIMERANG....Time range to consider
  PRTLEV......<= 1.0 -> show multiband fits.
              >= 2.0 -> show phase residuals for each IF
              Suggest using 2.
  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.
                (5) is the search range (+/- value) for the MBD.
              Default (0) is the natural range and is equal to
              the least-common stepping frequency, but is often
              chosen too high.  Try APARM(5)= 10 for DELZN work.
              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.
                (7) > 0 => pass "bad" data.  Set this equal to 1
              if you want to pass through 'bad' data previously
              blanked out by MBDLY.  A zero or low quality code
              (5, 6, or 7) will be set by CL2HF.  Useful for
              multiband observations when a source is detected
              in one band but not the other.
----------------------------------------------------------------
PROGRAM:  MBDLY
DOCUMENTOR:  Ed Fomalont   95.03.08, rev 06.05.21
RELATED PROGRAMS:  FRING, CALIB, DELZN, CLCAL, PCCOR, SNCOR

                      PURPOSE

FRING and CALIB determine the value of the antenna-based phase
for each IF for a specified solution interval.  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 group delays obtained from MBDLY can be
put into DELZN to determine the residual atmosphere and clock
residuals for each antenna, as a function of time.

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 by using PCCOR and choosing an
appropriate time range for a good calibrator.  Another method
is called the 'manual phase calibration'.  Here you run FRING
on a short segment of data (less than a minute) for a strong
source with a complete set of data to obtain the Single-band
delay, rate and phase.  It is recommended to zero the rates
(using SNCOR) unless the rates are persistently large for an
antenna.  Apply the solution to the entire data base using CLCAL.
This will line-up the IF phases and define the multiband delay
to zero for all antennas during the period of the short segment
of data used in FRING.  The relative IF phases should then be
relatively stable so that the residual IF phases for any other
source (strong and without too much structure) should be linear
with frequency.  MBDLY finds this phase/frequency slope.

The Multiband delays can also obtained directly from FRING with
APARM(5)=2.0.  However, this procedure has been found somewhat
unreliable so 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 and this is what is used if APARM(5)=0.
However, it is best to use as small a MBD spacing as possible,
and no more than 10 nsec is recommended for most DELZN
observations.

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.


Adverbs:
  BIF........The begining and
  EIF........The ending IF to use for the solution.  Experiments with
             simultaneous S/X bands are common.  It is recommended
             to separate the two frequencies and reduce separately.
  TIMERANG...The time range of the input SN table to process.  0 means
             take everything.
  PRTLEV.....Use 1 for most executions.  The output will list some
             information about the fits, including the rms phase
             residual.  If PRTLEV=2, the residual phase error for each
             IF is listed underneath each line.  This offset should be
             less than a few degress for a reasonable 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.
             (1) Minimum SNR.  The default is an SNR of >5.  This is
               reasonable. To include all data, let APARM(1) = 0.01
             (2) Maximum rate rms. 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 too weak of a source.
             (3) Maximum multi-band delay rms.  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.  Use PRTLEV=2 if there are
               problems here.
             (4) Minimum number of IFs.  This is defaulted to all IFs
               otherwise no solution is given.  This can be decreased
               even to 2 IF's as long as the phase difference between
               the two IF's is less than 180 deg.
             (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.  For example for most DELZN runs,
               APARM(5)=10 should be sufficiently wide.
                  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.
             (6) Unused now: formerly controlled whether residual
               phases were zeroed or not.  They are now passed
               unchanged.
             (7) > 0 => pass "bad" data.  Set this equal to 1 if you
               want to pass through 'bad' data previously blanked out
               by MBDLY. A zero or low quality code (5, 6, or 7) will
               be set by CL2HF.  Useful for multiband observations,
               when a source is detected in one band but not the other.
