\section{DiFX and pulsars} \label{sec:pulsars}


%TODO:
%tempo2 example (Jan)
%profile2binconfig
%  - 2 modes
%  - single input file allowed
%makeemptybinconfig (JW -- to be added)



DiFX supports four pulsar processing modes:

\begin{itemize}

\item \label{psrmode:binarygate} {\bf Binary Gating}  
A simple on-off pulse accumulation window can be specified with an ``on'' phase and an ``off'' phase.
This can be used to boost the signal to noise ratio of pulsar observations by a factor of typically 3 to 6 and can also be used to search for off-pulse emission.

\item \label{psrmode:matchedgate} {\bf Matched-filter Gating}
If the pulse profile at the observation frequency is well understood and the pulse phase is very well predicted by the provided pulse ephemeris, additional signal to noise over binary gating can be attained by appropriately scaling correlation coefficients as a function of pulse phase.
Depending on the pulse shape, addition gains by a factor of up to 1.5 in sensitivity over binary gating are realizable.

\item \label{psrmode:bin} {\bf Pulsar Binning}
Pulsar {\em binning} is supported within DiFX.
This entails generating a separate visibility spectrum for each requested range of pulse phase.
There are no explicit limits to the number of pulse phase bins that are supported, however, data rates can become increasingly large.
Currently AIPS does not support databases with multiple phase bins. 
Until there is proper post-processing support for pulsar binning, a separate FITS file will be produced for each pulsar phase bin.

\item \label{psrmode:profile} {\bf Profile Mode}
Profile mode is very different than the other three as it generates autocorrelations only that are used to determine the pulse shape and phase rather than generating cross correlations.
This mode is enabled by placing {\tt mode=profile} in the global scope of the {\tt .v2d} file (conventionally near the top).
The {\tt .v2d} file can enable as many antennas as desired (they will be averaged, so if you have a single large antenna it is probably best to include only that one), but can only operate on one source at a time.
The output of {\tt mpifxcorr} can be turned into an ASCII profile with {\tt difx2profile}.
This profile can then be given to {\tt profile2binconfig.py} to generate the {\tt .binconfig} file that is used by the other three pulsar modes.
There is some evidence that after about 10 minutes of integration the signal to noise ratio of the resultant profile stops growing.
This remains to be fully understood.
It could be that increasing the integration time helps; there is no reason not to use quite large integration times in this mode.

\end{itemize}

In all cases the observer will be responsible for providing a pulsar
spin ephemeris, and in all cases this ephemeris must provide an accurate
description of the pulsar's rotation over the observation duration (the pulsar 
phase must ont drift substantially with time).  If gating is to be applied then 
the ephemeris must be additionally be capable
of pedicting the absolute rotation phase of the pulsar.
Enabling pulsar modes incurs a minimum correlation-time penalty of
about 50\%.  High output data rates (computed from time resolution,
number of spectral channels, and number of pulsar bins) may require 
greater correlator resourse allocations.
The details of pulsar observing, including practical details of using
the pulsar modes and limitations imposed by operations, 
are documented at \url{http://library.nrao.edu/public/memos/vlba/up/VLBASU_32v2.pdf}.

\subsection{Pulse ephemeris}

The use of any pulsar mode requires a pulse ephemeris to be provided by the astronomer.  
This is a table of one or more polynomial entries, each of which evaluates the pulsar's rotation phase over an interval of typically a few hours.
The classic pulsar program {\tt Tempo} can be used to produce the polynomials required \cite{tempo}.
The pulse phase must be evaluated at the Earth center which is usually specified in {\tt tempo} by station code 0 (zero).
Many pulsars exhibit a great degree of timing noise and hence the prediction of absolute pulse phase may require updated timing observations.
When submitting the polynomial for use at the VLBA correlator, please adhere to the following naming convention: {\em experiment}{\tt -}{\em pulsar}{\tt .polyco} , e.g., {\tt BB118A-B0950+08.polyco} .
Instructions for generating the polynomial file are beyond the scope of this document.

Each {\tt .polyco} contains one or more polynomials along with metadata; an example {\tt .polyco} file that is known to work with DiFX is shown immediately below:
\begin{verbatim}
1913+16     6-MAY-15   90748.00   57148.38041666690           168.742789 -0.722 -6.720
   6095250832.610975   16.940537786201    0   30   15  1408.000 0.7785   3.0960
  0.18914380470191894D-06  0.26835472311898462D+00 -0.10670985785738883D-02
 -0.85567503020416261D-05 -0.55633960226391698D-07 -0.37190642692987219D-09
 -0.58920583351397697D-12 -0.27311855964499407D-12 -0.21723579215912174D-13
  0.11968684344685061D-14  0.92517174535020731D-16 -0.28179552068141251D-17
 -0.18403230317431974D-18  0.25241984130137833D-20  0.13743173681516959D-21
\end{verbatim}
\noindent
A description of the file format is available at \url{http://tempo.sourceforge.net/ref_man_sections/tz-polyco.txt}.
Currently {\tt tempo} (version 1) is well supported and {\tt tempo2} is only supported in {\tt tempo1} compatibility mode.
Eventual support for the {\tt tempo2} {\em predictors} will be added.
All ephemerides must be made for the virtual Earth Center observatory (i.e., XYZ coordinates 0,0,0, usually observatory code 0; DiFX versions prior to 2.5 would not accept any non-numeric code even though they are legal).
Any reference frequency can be specified as the correlator takes dispersion into consideration.

Note that although {\tt tempo} version 2 can produce usable {\tt .polyco} files experience has shown that version 1 has fewer failure modes.

\subsection{Bin configuration file}

All three pulsar modes also require the preparation of a {\tt .binconfig} file by the astronomer.
The contents of this file determine which of the three pulsar modes is being used.
Three pieces of information are contained within this file: the pulsar ephemeris (polyco) files to apply, definitions of the pulsar bins, and a boolean flag that determines whether the bins are weighted and added within the correlator.
The file consists of a set of keywords (including a colon at the end) that must be space padded to fill the first 20 columns of the file and the values to assign
to these keywords that start at column 21.
The file is case sensitive.
The pulsar bins each consist of a ending phase and a weight; each bin is implicitly assumed to start when the previous ends and the first bin starts at the end phase of the last.
The phases are represented by a value between 0 and 1 and each successive bin must have a larger ending phase than the previous.
Examples for each of the three pulsar modes are shown below:

\subsubsection{Binary gating}

\begin{verbatim}
NUM POLYCO FILES:   1
POLYCO FILE 0:      BB118A-B0950+08.polyco
NUM PULSAR BINS:    2
SCRUNCH OUTPUT:     TRUE
BIN PHASE END 0:    0.030000
BIN WEIGHT 0:       1.0
BIN PHASE END 1:    0.990000
BIN WEIGHT 1:       0.0
\end{verbatim}

\subsubsection{Matched-filter gating}

\begin{verbatim}
NUM POLYCO FILES:   1
POLYCO FILE 0:      BB118A-B0950+08.polyco
NUM PULSAR BINS:    6
SCRUNCH OUTPUT:     TRUE
BIN PHASE END 0:    0.010000
BIN WEIGHT 0:       1.0
BIN PHASE END 1:    0.030000
BIN WEIGHT 1:       0.62
BIN PHASE END 2:    0.050000
BIN WEIGHT 2:       0.21
BIN PHASE END 3:    0.950000
BIN WEIGHT 3:       0.0
BIN PHASE END 4:    0.970000
BIN WEIGHT 4:       0.12
BIN PHASE END 5:    0.990000
BIN WEIGHT 5:       0.34
\end{verbatim}

Note here that there is zero weight given to pulse phases ranging between 0.05 and 0.95.

\subsubsection{Pulsar binning}

\begin{verbatim}
NUM POLYCO FILES:   1
POLYCO FILE 0:      BB118A-B0950+08.polyco
NUM PULSAR BINS:    20
SCRUNCH OUTPUT:     FALSE
BIN PHASE END 0:    0.025000
BIN WEIGHT 0:       1.0
BIN PHASE END 1:    0.075000
BIN WEIGHT 1:       1.0
BIN PHASE END 2:    0.125000
BIN WEIGHT 2:       1.0
BIN PHASE END 3:    0.175000
BIN WEIGHT 3:       1.0
.
.
.
BIN PHASE END 18:   0.925000
BIN WEIGHT 18:      1.0
BIN PHASE END 19:   0.975000
BIN WEIGHT 19:      1.0
\end{verbatim}

The primary difference is {\tt SCRUNCH OUTPUT:     FALSE} which causes each pulsar bin to be written to disk.

\subsection{Preparing correlator jobs}

When using {\tt vex2difx} to prepare correlator jobs, one must associate the pulsar with a setup of its own that includes reference to the {\tt .binconfig} file.
An excerpt from a {\tt .v2d} file is below:

\begin{verbatim}
SETUP gateB0950+08
{
        tInt = 2.000
        nChan = 32
        doPolar = True
        binConfig = BB118A-B0950+08.binconfig
}

RULE B0950+08
{
        source = B0950+08
        setup = gateB0950+08
}
\end{verbatim}

The {\tt .binconfig} file should be in the same path as the {\tt .v2d} file when running {\tt vex2difx}.

\subsection{Making FITS files}

For the two gating modes, preparing FITS files with {\tt difx2fits} is no different than for any other DiFX output.
FITS-IDI does not support multiple phase bins so the pulsar binning case is different and the situation is non-optimal.
Each pulsar bin must be made into its own {\tt FITS} file with a separate execution of {\tt difx2fits}.  
The {\tt -B} (or {\tt --bin}) command line option takes the bin number (starting at zero as above) and writes a FITS file containing data only associated with that bin number.
Be sure to systematically name output files such that the bin number is understood.
