\newcommand{\degr}{\hbox{$^\circ$}}
\newcommand{\numm}{\hbox{$\nu_{m}$}}
\newcommand{\nuto}{\hbox{$\nu_{2}$}}
%
% LATEX DOCUMENT SETUP
%
\documentstyle[12pt]{article}
\topmargin -1.0 cm
\setlength{\textheight}{22 cm}
\setlength{\textwidth}{16cm}
\oddsidemargin 0cm
\begin{document}
\vspace{3.5cm}
\title{CAP \\ 
Calibration and Analysis Package \\
Version 0.9}
\author {Fredrik T Rantakyr\"{o}\\
fredrik@astbo1.bo.cnr.it\\
}
\maketitle
\vspace{8.0cm}
\begin{center}
JIVE \\
IRA - CNR \\
\end{center}
\pagebreak
\tableofcontents
\pagebreak
\section{What is CAP}
{\bf CAP} is a {\bf UNIX} script based program that will produce an 
brief analysis of the output from the {\bf AQUIR} package. The program 
will make plots of pertinent data and can be used to find out the
changes to the {\bf T$_{\bf cal}$} and the {\bf GAINCURVE}, determine the 
aforementioned factors if they are unknown. A planned and soon to be 
implemented feature is to determine
{\bf T$_{\bf cal}$} as a function of observing frequency and LO. 
\section{How to use CAP}
\subsection{Installation}
As stated in the the introduction {\bf CAP} is script based and thus 
doesn't need any compilation to run. The program heavily uses the {\bf
sed} and the {\bf awk} programs to create the correct output, thus
both programs are needed in the path. For making graphical output
(postscript/x-windows) the program uses the {\bf GNUPLOT} program,
version 3.5. This program is included in the FS9 distribution, although 
a patch that includes the {\bf GNUFIT} is needed. A patched {\bf
GNUPLOT} can be found with source code in the same directory where the
{\bf CAP} programs are located. You can also make a {\bf fsadapt} then
this patch will be put in place. 
\subsubsection{How to get {\bf CAP}}
{\bf CAP} can be found on {\bf ASTBO1.BO.CNR.IT}. 
\begin{enumerate}
\item Log in as {\bf EVN} using the password you can obtain from your
local Friend of VLBI.   
\item The tar archive can be found in {\bf [EVN.CAP]} under the name {\bf 
CAP}. To get there just issue the command {\bf cd CAP} after you login. 
\item In the same directory you can find the {\bf gnufit.tar} archive
which contains executables and all files needed if you want to
recompile the program yourself. 
\item Select binary transfer by {\bf bin}. 
\item {\bf get CAP.tar} to get the archive. 
\item If you want the {\bf gnufit.tar} download this one too. 
\item After successful transfer {\bf quit}. 
\end{enumerate}
In the same directory as the tar archive you can find this document in
both postscript and in {\bf LaTeX} form.  
\subsubsection{First Installation}
This describes the first installation for {\bf CAP} 
\begin{enumerate}
\item Put the {\bf tar}file in the directory where your binaries are 
stored, typically in \\
{\bf /usr2/oper/bin} in a standard fieldsystem setup. 
\item Unpack the {\bf tar}file with the commando {\bf tar xvf cap.tar}. 
\item If you put the files in a different directory than specified above 
you will need to edit the path specified inside the script program. 
Edit the lines in the {\bf cap} scripts file that say:\\ 
{\bf /usr2/oper/bin/} \\
to say: \\
{\bf your-new-path-goes-here} \\
\item You are now done with the installation.
\end{enumerate} 
\subsubsection{Updating the antenna information}
All the specific antenna information can be found in the database for
each antenna. The source database {\bf sources-freq-code.dat} is the same for
all stations, while {\bf station-frequency-code.dat} has to be
changed for each station to reflect the local {\bf POLY, DPFU,
T$_{\bf cal}$}.% and {\bf T$_{\bf cal}$ frequency polynomial}. 
To edit the station file file just open it with your favourite editor
and do the necessary changes. 
\subsection{Usage}
The usage is really simple:
\begin{enumerate}
\item Change your working directory to that where you have the output
from the {\bf AQUIR} package.
\item Run the programs in the package one by one. Below follows a
example run with explanation of program parameters and the usage. 
\begin{enumerate} 
\item {\bf cap\_format frequency-code log-file}. 
\begin{itemize}
\item {\bf frequency-code} is the standard {\bf VLBI} code
(l/c/q/k/s/x). 
\item {\bf log-file} is the {\bf AQUIR} log-file that you want to
process. 
\end{itemize}
This program will take the log-file and make a formatted output that
can be used by the other programs in the package. The output will be
called station.acp  and contains all relevant information in the
following order: \\
{\bf Source\_Name Assumed\_source\_flux Date\_in\_days Azimuth \\
Elevation Src/Cal Derived\_Tcal Derived\_Source\_flux \\ 
No\_gaincurve\_Derived\_Tcal No\_gaincurve\_Derived\_Source\_flux Flag}(for
flagging bad data).  \\
All values with negative fluxes will automatically be flagged from
being sent to the output file {\bf station.acp}. 
\item {\bf cap\_plot fit yaxis xaxis form source frequency}
\begin{itemize} 
\item {\bf fit} can be either {\bf 0, 1, 2, 3, 4 or 5} for fitting a
polynomial of the aforementioned order to the plot, i.e {\bf 0} means
no fitting just a plot, {\bf 1} makes a flat fit and {\bf 5} makes a
fourth order polynomial fit to the plot($x^4$). Start with {\bf 0} to
get a  handle on how the data looks like, then try with {\bf 1} to
find a good start and then continue with {\bf 2, 3, } and finally a
fourth order polynomial plot. If the program gives the error {\bf
single matrix} edit the {\bf dummy.dat} to try with a different value
(if you're fitting to the {\bf nogain\_curve} change the {\bf
station-freqcode.dat} file and start from scratch with {\bf
cap\_format}). The best way if the gain-curve is unknown is to start 
with  {\bf station-freqcode.dat} with {\bf caltemp=} used caltemp
value and p1-p4 set to 0.0 and do the procedure with {\bf dummy.dat}
described above. 
\item {\bf xaxis} can be either {\bf el} (elevation), or {\bf t} (time in
days).%, or {\bf f} (frequency, this is used when plotting the {\bf
%T$_{\bf cal}$} to determine the frequency dependance. 
\item {\bf yaxis} which is {\bf tcal} (T$_{\bf cal}$), {\bf flux}, and
{\bf nogtcal} and {\bf nogflux} for a curve uncorrected for the
gaincurve polynomial.    
\item {\bf form} is either {\bf ps} (postscript) or {\bf x} (xwindow
output). 
\item {\bf source} is either a named source or {\bf all} to include
all sources in the plot. 
\item {\bf frequency} is the one-letter frequency code. 
\end{itemize} 
This program makes a plot using the {\bf GNUPLOT} package that is
either shown to the screen ({\bf x} option) or saved as a postscript file
({\bf ps} option). The ps-file is called {\bf station.ps}. Typically the
first time one plots the {\bf T$_{\bf cal}$} vs {\bf time} to find out 
if there are some bad data so this can be flagged with {\bf cap\_clip}. 
There will always be made a LSQ-fit to the data (a linear fit for 
{\bf T$_{\bf cal}$}, a fourth order fit for {\bf T$_{\bf cal}$} as a function 
of frequency and for a {\bf GAINCURVE} polynomial fit.   
\item {\bf cap\_clip Minimum\_Tcal Maximum\_Tcal}. This program passes
through the {\bf station.acp} file and flags all observations that
have {\bf T$_{\bf cal}$} values outside the specified range. All the data 
are kept and can be unflagged by giving a larger allowed range for
{\bf T$_{\bf cal}$}. 
\end{enumerate}   
\item The steps {\bf b - c} are repeated until a satisfactory solution
has been found for {\bf T$_{\bf cal}$} and for the {\bf GAINCURVE}.
I'll describe the two extreme cases of either a bad value for {\bf
T$_{\bf cal}$} or an unknown or poorly known {\bf GAINCURVE}. 
\begin{itemize}
\item If the {\bf T$_{\bf cal}$} is unknown just run step {\bf b}
plotting {\bf T$_{\bf cal}$} vs {\bf t}. Then clipping unwanted values
in step {\bf c}. Incorrect source fluxes will show up as offsets from
the ideal flat line in the plot, to complicate it further weather and 
{\bf gaincurve} effects will distort the plot. The {\bf gaincurve}
effects can be avoided by taking a small timesegment and weather by
doing the calibration in good clear weather. The wanted {\bf T$_{\bf
cal}$} is the the average {\bf T$_{\bf cal}$} in the plot.
\item Assuming that {\bf T$_{\bf cal}$} is well known and calibrated
then finding out/testing  the gaincurve polynomial is fairly trivial. 
Plot {\bf T$_{\bf cal}$} vs {\bf el} then if the {\bf POLY}nomial
factors for the {\bf gaincurve} are incorrect the plot will deviate
from a straight line. Any up/down shift of the whole curve curve with
respect to a previously known curve can be traced to a incorrect {\bf
T$_{\bf cal}$} value. Redo the step described above to determine the
correct {\bf T$_{\bf cal}$} value. The deviation from a flat line is 
due to poorly known parameters in the {\bf POLY}nomial and the new 
values can be found by making a {\bf least squares fit} to the data.  
\end{itemize}  
\end{enumerate}   
\subsection{Error messages}
Occasionally within the fitting rutine there might be the error
messages {\bf singular matrix} and {\bf syntax error in data file}.
The {\bf singular matrix} is due to bad initial values for the fit,
either try a simpler fit or clip away bad data. The {\bf syntax error
in data file} is a internal bug for {\bf GNUFIT}, the program dislikes
any column which starts with a character, thus any source that has a
name that starts with a character will stop the program. The temporary
solution is to edit the {\bf station.acp} file with an editor and
rename f.ex cygnusa to 3cygnusa. 
\subsection{Known bugs}
There is the problem with alphabetic characters as the first character
for a value in a column (see above for a temporary fix). A second
known bug is also related to the names of the sources, the sourcenames
cannot contain any mathematical operator (+-*/) or any non numerical
or nonalphabetical character with the exception of \_ sign. The {\bf
AQUIR} files sent out should contain names that are setup correctly. 
%\subsubsection{IF-band corrections}
%With {\bf CAP} it is now possible to make corrections for a non-flat
%if-band. 
\section{How to contact the author}
I can be contacted by email at {\bf fredrik@astbo1.bo.cnr.it}. Please send 
any bugreports, comments and/or suggestions that you have to this address.
\end{document}
\end
