User manual to dbcal
Brent Archinal
Abstract:
Some very old description of progrtam dbcal.
Table of contents:
- 1 Introduction
- 2 How to Run
-
- 2.1 Running in Batch
-
-
- 2.2 Comparison to previous version
-
-
- 2.3 Comparison to UNCAL
-
-
- 2.4 The new lcodes and what they contain
-
-
- 2.5 Files, Subroutines.
-
-
- 2.6 Algorithms used
-
-
- 2.7 What Remains to be Done (UNCAL task)
-
-
- 2.8 Changes for WVR data
-
- 3 Dbcal General Flowchart
1 Introduction
A new version of DBCAL now exists which can compute and store UNCAL
variables in the database. The program calculates the effect of variations
in the phase-cal phases on the "observed" group delay. It also obtains the
effect on delay rate, which already exists separately under the lcode
"PHASECAL". It puts these quantities into the type 2 records under the new
lcode "UNPHASCL". A second new lcode - "UNPHAFLG" - has also been added.
This specifies whether a value for the uncal delay was found, and whether
the ambiguity resolution was performed.
At the user's option calculation and insertion of UNCAL lcodes can be
omitted.
2 How to Run
To run DBCAL you type dbcal <control_file> as appropriate.
The program may ask whether you want added debug output.
It (then) asks you whether you want to include the UNCAL option
(calculate and store UNCAL variables) in this run. Answer either
Y or N. If you respond by typing "Y" the UNCAL option is invoked.
The UNCAL quantities are then calculated and stored, even if this
was already done previously. Responding "N" skips the UNCALing.
The default option (today) is "abort", i.e. the program aborts unless
one reponds Y or N. After this point, DBCAL procedes exactly like
DBCAL. It reads, either from the terminal or from a file, the names
of any calibration files, and the names of the databases, and then
goes off and does its work.
2.1 Running in Batch
Running in batch is possible just as before, except
that the batch control file now needs an extra line at the
beginning to tell the program whether to do the UNCAL part.
This line should contain either the letter "Y" or "N".
2.2 Comparison to previous version
If the UNCAL option is not invoked (i.e. user
answers 'N' when asked), then the program performs
identicallyto the old DBCAL. However DBCAL can also be run
solely to calculate UNPHASCL variables.
In this case one need not supply ANY calibration files,
since the data needed for the computation already
resides in the database.
2.3 Comparison to UNCAL
DBCAL performs the same calculations as the program
UNCAL in finding phasecal effect on group delay.
Most of the code was in fact pirated therefrom.
Of course unlike the older versions of UNCAL,
observed (theoretical?) delays are left undisturbed
and the corrections are stored under a separate lcode.
But unlike the current version of UNCAL, DBCAL stores
the effect of the phasecal at each end of the baseline,
while UNCAL stores only the overall correction.
The delays found by DBCAL are not deriveable from
those stored by UNCAL, because UNCAL stored only
the phase differences.
DBCAL also stores the phasecal effect on rates,
(which it simply reads from elsewhere in the database)
so that the format of the database looks like that
for other calibrations.
The new lcodes created by DBCAL are at present UNPHASCL
and UNPHAFLG. The program UNCAL creates UNCALDLY and UNCALFLG.
The names differ purposely, because the dimensionality
and contents differ.
The program UNCAL has an option of periodic re-synchronizing
of clocks. This is useful if one truly needs the equivalent of
a manual phasecal. However such an option is inconsistent
with uniform application to all databases.
2.4 The new lcodes and what they contain
The lcode UNPHASCL contains the effect of the phase cal on the group
delay and the delay rate. Units are seconds (delay) and seconds/second (rate).
Its dimensionality is (2 x 2), where the first index designates which station
in the baseline, and the second whether group delay (1) or delay rate (2).
This conforms with ordering for other calibrations (cable, WX, WVR) added
by DBCAL. The calibrations are designed for use in the new version of SOLVE,
i.e. with calibration controlled by cal files. I intend these calibrations
to be additive, in the sense that to "undo" the phasecal one adds the values
stored. I'm pretty sure I got the signs right, assuming CAK got them right
in UNCAL (P>98%) and assuming I followed UNCAL's various sign flips correctly
(P<98%). For the rate effect the signs are positive, assuming the
description in "FRNGE to be accurate.
Another lcode - "UNPHAFLG" - has also been added,
to specify the status of the values stored under UNPHASCL.
Flag values mean the following:
For GROUP delay
IFLAG= 0 Delay found, ambiguity resolved
IFLAG= 1 Delay found, ambiguity resolved to temporary
ambiguity standard
IFLAG= 2 Delay found, no ambiguity resolution.
IFLAG=-1 No delay found; set it to zero. (subroutine
to calculate delay returned with error code)
IFLAG=-2 No delay found; set it to zero. (Not all
data needed for calculation is available.)
For Delay RATE
IFLAG= 0 Rate correction found, Got, Put.
IFLAG=-2 Rate correction not found. Put value = 0.d0
If a database has already been through the old UNCAL
program it will have lcodes "UNCALDLY" and "UNCALFLG",
which contain the net phase-cal group delay and a status
flag. After also passing through DBCAL, this information
is superfluous. (The converse is not true.)
DBCAL therfore deletes these two lcodes from the
table of contents if they exists, and so notes in
a history entry.
2.5 Files, Subroutines.
The source code for the new DBCAL version lives
on lu 53 at the moment in the files &DBCAL.
This includes all the code from the old &DBCAL, with
modifications to include the new UNCAL capability.
The following changes were made:
In the root program we added a user query as to whether
to do the UNCAL. This sets a flag - LDOPC - which
tells HEADR and PUTDA whether to invoke the portions
related to uncaling.
In the subroutine HEADR code was added to ADD the two new
lcodes. Some initialization is performed, and the database
table of contents is ASKed whether certain lcodes containing
needed data exist.
In the subroutine PUTDA, the counter NITPC is zeroed
to tell that a new database has begun, and
the call is made to PUTPC, which actually
does all the work. A new labelled common denoted as HPHC was
added several places, and a block data program was added
to reserve space for it.
The file &PUPCL contains most of the new code used in
this new capability. It contains the subroutine PUPCL,
which gets the data it needs from the database,
calls subroutines to calculate the uncal delays,
and puts the new "calibration" into the type 2 record.
It is analogous to PUWX, PUCBL, and PUWVR, except that
the "calibration" it puts in is calculated from
information already present, rather than interpolated
from some external file.
The actual calculation of the phasecal equivalent delay
is performed in the subroutine PCCLC, which is called
by PUPCL. PCCLC is handed the frequencies, phasecal phases,
and other relevant data, performs the scaling and other
setup, calls two subroutines, and returns the value for the delay.
The subroutines called by PCCLC are FOUR1 and PARAB, which
also reside in the file &PUPCL.
These perform the transform and interpolate the location of the
channel of maximum amplitude.
PCCLC is called twice per observation: once for each
station in the baseline.
2.6 Algorithms used
The algorithms used in calculating the UNCAL
variables for DBCAL are the same as those used
in the UNCAL program and in PCPHS.
(Applying these corrections however is NOT in general
equivalent to performing a manual phase-cal.)
To estimate the effect of the phase cal system on
the group delays, we estimate a "delay" from the
phases of the phasecal in each channel. If there
really is a delay-like dispersal as the signals travel
from receiver to recorder, then the phasecal phases
will be some zero-delay offsets plus the phase due to
path delay (through the I.F. chain, et cetera).
The first time a station appears the phasecal phases are
saved, and define the initial phase offsets, including
some contribution from group delay in the I.F. chain.
On subsequent observations involving this station, the
initial phases are subtracted from the measured phasecal
phases. A group delay is then fit to these phase differences.
We thus are tracking changes on the phasecal group delay
from some initial epoch. IF THESE CHANGES ARE NOT
PURELY DELAY-LIKE, MISLEADING RESULTS MAY EMERGE.
(This is why the PCPLT program plots phases of
each individual frequency channel - so that non
delay-like behaviour may be found out.)
The actual calculation of the delay from the phase-cal
phases is performed in the subroutine PCCLC, FOUR1, and
PARAB. PCCLC does all the setup, mapping frequency
channels onto array elements. Phasecal amplitudes
are ignored. FOUR1 performs the fourier transform
to obtain the power spectrum. The channel with the
largest amplitude corresponds to the group delay which
comes closest to adding the vectors in phase.
PARAB finds this maximum channel and performs a
parabolic interpolation to refine the position
of the maximum. PCCLC also calculates the phase residuals
from the fit, but these are not used in RPCAL.
PCCLC then returns the delay to PUPCL which
chooses the group delay ambiguity in a manner designed to
avoid introducing ambiguity shifts insofar as is possible.
2.7 What Remains to be Done (UNCAL task)
At present the program DBCAL computes the phasecal effects
on group delay only. It does not have the capability
to find the effect of the phasecal on phase delay.
This would involve some further calculation, and would require adding
new lcodes for the phase delay corrections and an associated
status flag.
A new version of PCPHS could be written for
databases that have had uncal variables added.
The current version of DBCAL does not write out the delays
or residuals onto disk files.
This is due primarily to the complexity of keeping track of
all the output files that would be required.
However DBCAL already calculates everything needed
for the phasecal plots - both delays and residuals.
With minor modifications DBCAL could store the residuals in
the type 3 records in the database.
PCPHS can then be greatly simplified, reading everything
from the database, eliminating all the
the number-crunching and performing only the bookkeeping.
Alternatively, if and when DBCAL is changed over to the CI
file system, we could also change over PCPHS and PCPLT.
Then it would be relatively simple to have DBCAL write
the input files for PCPLT directly.
DBCAL currently inserts the UNCAL lcodes either for
all databases in a run or for none.
Two modifications may be desirable. First, the insertion
might be decided separately for each database.
This modification is simple, but it would
require changing the format of the control file.
A second possible modification would allow a "conditional"
update, where the UNCAL lcodes are inserted only
in databases which don't already have the UNPHASCL lcodes.
2.8 Changes for WVR data
Several changes have been made in this program in handling
of WVR data. These changes, made by John Gipson (I**2/GSFC),
are not described in this note.
3 Dbcal General Flowchart
Prepared by Melvin White, February 10, 1993.
Only those programs, subroutines, functions, and includes with
source files in /mk3/src/dbcal directory are listed in this
flowchart.
Symbols used:
<-{ } include file
<->" " input/output data or command control files
->[ ] called functions...first letter capitalized
-> XXXXX called subroutines...all letters capitalized
------------------------------------------------------------------
-> DBCAL...|
|<-{ dbcal.i }
|<-" (database file) "
|-> RL.........|
| |<-" (command control file) "
|
|-> RDWX.......|
| |<-{ dbcal.i }
| |<-" (weather data files) "
| |-> RL........|
| | |<-" (command control file) "
| |
| |-> SMOTH
| |-> METO4.....|
| |-> SPLN2.....|
| |-> XDEL
|-> RDCBL......|
| |<-{ dbcal.i }
| |<-" (cable data files) "
| |-> RL........|
| |<-" (command control file) "
|
|-> RDWVR......|
| |<-{ dbcal.i }
| |<-" (wvr data files) "
| |-> RL........|
| |<-" (command control file) "
|
|-> HEADR......|
| |<-{ dbcal.i }
| |<->" (database file) "
| |-> ESTOP
| |-> MATCH
| |-> PKSTA
| |-> RL........|
| | |<-" (command control file) "
| |-> ZTIME
| |-> ANTIM
|
|-> PUTDA......|
|<-{ dbcal.i }
|-> ESTOP
|-> PUWX......|
| |<-{ dbcal.i }
| |<->" (database file) "
| |-> ESTOP
| |-> METO2.....|
| | |-> DSPLN.....|
| | | |-> XDEL
| | |
| | |-> SPLIN.....|
| | |-> XDEL
| |-> METO3
| |-> SASTD
| |-> SASTW
| |-> CFA22
| |-> LANYI.....|
| |-> AELM......|
| | |-> DMOM
| |
| |-> DAELM.....|
| | |-> DMOM
| |-> DMOM
|-> PUCBL.....|
| |<-{ dbcal.i }
| |<->" (database file) "
| |-> ESTOP
|
|-> PUWVR.....|
| |<-{ dbcal.i }
| |<->" (database file) "
| |-> ESTOP
| |->[ Dwvrm ]
| |->[ Wvrmp ]
|
|-> PUPCL.....|
|<-{ dbcal.i }
|<->" (database file) "
|-> PCCLC.....|
|-> FOUR1
|-> PARAB
Last update: 1993.09.20