PSRCHIVE user documentation: pcm

1.0 Purpose

The Polarization Calibration Modeling (pcm) program may be used to estimate the polarimetric response of the observing system, as described in van Straten 2004, ApJS 152:129, and van Straten 2013, ApJS 204:13. There are two different modes of operation:

Measurement Equation Modeling (MEM), described in van Straten (2004), uses uncalibrated observations of

  • a single pulsar at multiple parallactic angles,
  • an amplitude modulated reference source (linear noise diode), and
  • [optionally] an unpolarized flux calibrator, such as Hydra A.
Please read this imporant note about assumptions made to overcome measurement equation modeling degeneracy.

Measurement Equation Template Matching (METM), described in van Straten (2013), uses

  • a single well-calibrated observation of a pulsar with high signal-to-noise ratio (the template, or standard),
  • one or more uncalibrated observations of the same pulsar, and
  • [optionally] an amplitude-modulated reference source (e.g. a noise diode coupled to the receptors).

2.0 Usage

2.1 Before running pcm

In order to run pcm in MEM mode, you will need Pulsar::Archive files containing:
  • full polarization observations of a single pulsar over a wide range in parallactic angles (Pulsar::Archive::get_type must return Signal::Pulsar).
  • one or more observations of the "linear" noise diode (CAL) made while pointing at or near the pulsar (Pulsar::Archive::get_type must return Signal::PolnCal).
  • [optionally] one or more observations of the CAL made while pointing at a strong flux calibrator with negligibly small degree of circular polarization, such as Hydra A (Pulsar::Archive::get_type must return Signal::FluxCalOn).
All observations must have the same observing parameters, such as centre frequency and bandwidth, as defined by the Pulsar::Archive::calibrator_match method. After gathering all of the required data:
  • Create a calibrator directory and database file:
    1. Copy all calibrator files (.pcal, .fcal) to one directory, say $MYCALS. The files can be organized into sub-directories if desired (see the pac manual).
    2. Run pac -wp $MYCALS to create the summary file, $MYCALS/database.txt.
  • Create a preliminary total integrated calibrated profile:
    1. Perform preliminary calibration using pac -d $MYCALS/database.txt psr*.ar
    2. Combine the calibrated output archives using psradd -T -o calib.TT psr*.calib

This last step produces a total integrated profile from which to choose the best pulse phase bins to be used as model constraints. It is best to choose these from a high S/N profile, but integration in both time and frequency will lead to depolarization (primarily due to the variation of differential phase as a function of frequency, and to the time-varying projection of the receptors onto the sky). The preliminary calibration step minimizes this depolarization.

As described in more detail in Section 4.1, it is possible to either manually choose individual phase bins or ranges of pulse phase that make good model constraints, or allow pcm to automatically choose the best pulse phase bins. When choosing phase bins manually, it is best to choose those with the highest polarized flux density and, if selecting more than one pulse phase bin, to choose states that have orthogonal polarization vectors in the Poincare space.

As more phase bins are used as constraints, more time will be required to converge to a solution. For starters, use only four phase bins; pcm will converge more quickly, providing a first order estimate of the instrumental parameters. More phase bins can then be added to descrease the experimental uncertainty of the results.

2.2 Running pcm

2.2.1 MEM mode
In MEM mode, pcm does the following (not necessarily in this order):
  • Loads all PolnCal calibrator files and solves the receiver using one of the basic models (SingleAxis or Polar, depending upon the chosen parameterization, Britton or Hamaker). The weighted mean of these solutions is used as the first guess of the instrumental response.
  • Loads the pulsar archive and prunes the Stokes parameters from the specified set of pulse phase bins. These are corrected using the best guess of the instrumental response, deparallactified, and added to a weighted mean that is used as the first guess of the Stokes parameters.
  • Loads all FluxCalOn flux calibrator files and uses the off-pulse Stokes parameters to constrain the mixing of Stokes I and V. This breaks the degeneracy described in van Straten (2004).
An example of MEM usage is provided in section 4.1.

In MTM mode, it is possible to fit single sub-integrations to the template or perform a global fit of multiple sub-integrations using a combination of MEM/MTM.

2.2.2 MTM mode
When run with the -1 option, pcm performs a MTM fit on each input sub-integration and outputs a file for each solution (named *.mtm). Without the -1 option, a single global MEM/MTM fit is performed using all of the input data as constraints.

2.3 Diagnostic outputs

pcm can optionally produce a number of diagnostic outputs. These are enabled with the -D name command line option, where name is any one of:

  • report print a report of the reduced chisq for each Stokes parameter of each pulse phase bin in pcm_report_*.txt. Please see fit report for more details.
  • guess plot the initial guess of the instrumental response in guess_response.ps, the calibrator Stokes parameters in guess_cal.ps, and the pulsar Stokes parameters in guess_psr.ps.
  • residual plot the residual between each measurement and the model in channel_*.ps.
  • total plot the total integrated pulse profile in uncalibrated.ps (before) and calibrated.ps (after).
  • result plot the best fit result of the instrumental response in result_response.ps, the calibrator Stokes parameters in result_cal.ps, and the pulsar Stokes parameters in result_psr.ps.

2.4 Modeling time variations

Intrinsic variations (including interstellar scintillation)

pcm can compensate for intrinsic variations in the intensity of the pulsar signal by normalizing the Stokes parameters of the pulsar observations by the mean invariant: the square root of the mean of the invariant intervals (I^2 - p^2) of a constant selection of on-pulse phase bins.

This feature is enabled with the -s command line option. The on-pulse phase bins are chosen from either the first archive loaded or the archive specified using the -c command line option, then held fixed for all subsequent archives.

When -s is used, the pulsar is put through a signal path with constant gain set to unity, and the free gain parameter is applied only to the calibrator signal path.

Instrumental variations

pcm can model the observations with an instrumental backend that varies over time. Each of the absolute gain, differential gain, or differential phase may be independently represented as either

  • a polynomial of arbitrary order; or
  • a series of step functions (jumps).
For the series of steps, the epoch of each step is defined by the first sub-integration of each CAL file encountered. This models the typical observing pattern with the DFB at Parkes, where a LEVCAL observation is made to set the signal levels, which remain fixed until the next LEVCAL.
  -u PAR     model PAR with a step at each CAL
  -o PAR:N   model PAR as N degree polyomial
Where PAR is a single-character code:
  • g = absolute gain
  • b = differential gain
  • r = differential phase
  • a = all of the above
For example, to model all three parameters as a third order polynomial, use -o a:3; to model absolute and differential gain variations with a step function at each CAL, add -u g -u b.

3.0 Algorithms

pcm implements the model of reception and the algorithm for solution described in van Straten, W. 2004, Radio Astronomical Polarimetry and Point-Source Calibration, Astrophys. J. Supp. 152, 129-135. astro-ph/0401536

4.0 Testing and examples

4.1 MEM Example

For this example, suppose that all of the pulsar observations are located in the current working directory and have the extension .ar and that all of your calibrator archives are summarized in the data base, $MYCALS/database.txt.

The simplest way to run pcm is to let it choose the optimal phase bins to use as model constraints. Assuming that calib.TT has been created as described in Section 2.1, run

pcm -d $MYCALS/database.txt -c calib.TT -s -t2 *.ar
Here, the -s option specifies that the Stokes parameters should be normalized to compensate for temporal flux variations and the -t2 option specifies to use two processing threads (not useful if your machine has only one single-core CPU).

4.2 Manaual selection of phase bins (MEM only)

Alternatively, suppose that the Stokes parameters at pulse phases equal to 0.45 and 0.51 look like they will make good constraints. If there are 2048 phase bins, then bin numbers 922 and 1044 are to be used. The command line is:
pcm -b 922 -b 1044 -d $MYCALS/database.txt *.ar

Alternatively, suppose that you would like to select 8 bins between pulse phases 0.39 and 0.51. The command line is:

pcm -p 0.39,0.51 -n 8 -d $MYCALS/database.txt *.ar



In the latter example, pcm will begin with something like:

Pulsar::Archive::Agent::init 
pcm: selecting input states from 0.39 to 0.51
pcm: selecting a maximum of 8 bins
pcm: assuming that System + Hydra A Stokes V = 0
pcm: allowing CAL Stokes Q to vary
pcm: normalizing Stokes parameters by invariant interval
pcm: constructing Calibration::Database from
     /export/home/user/pcm/cals/database.txt
pcm: searching for calibrator observations within 24 hours of midtime
pcm: midtime = 2003-08-29-19:02:00
pcm: adding n2003241194914.pcal
pcm: adding n2003241223100.fcal
pcm: adding n2003241222635.fcal
pcm: set calibrators
pcm: loading archives
pcm: adding phase bin 799
[...]
pcm: adding phase bin 1044
pcm: 8 states
Pulsar::ReceptionCalibrator::load_calibrators 
  loading /export/home/user/pcm/cals/n2003241194914.pcal

Note that pcm begins by loading the calibrators. At this stage, you may see error messages like:

Pulsar::ReceptionCalibrator::add_calibrator error adding ichan=0
Error::stack
        Calibration::ReceptionModel::add_data
Error::InvalidParam
Error::message
        source_index=0 ipol=3 variance=0.000000 < 0

Or also:

Pulsar::ReceptionCalibrator::add_data discarding ichan=0 ibin=1044

Unless all of the data are getting discarded, or appear to be corrupted, these error messages may be ignored; pcm can handle and flag a variety of problems in the data.

After the calibrators have been loaded, pcm will output on stderr lines such as:


Setting 128 channel receiver
Pulsar::ReceptionCalibrator::precalibrate
pcm: loaded archive: n2003200181319.cfb

These mean that pcm is calibrating the input archives with its current best guess of the receiver before adding their data to the best guess of the input polarizations.

After all the data is loaded, pcm will output something like:


pcm: plotting initial guess of receiver
Pulsar::ReceptionCalibrator::solve information:
  Parallactic angle ranges from -102.621536254883 to 98.1568908691406 degrees
Pulsar::ReceptionCalibrator::solve reference epoch: 52839.945158016725522
pcm: plotting uncalibrated pulsar total stokes
pcm: plotting uncalibrated CAL
pcm: plotting pulsar constraints
pcm: nstate=1
ichan=1 istate=1
pcm: nstate=1
ichan=11 istate=1
pcm: nstate=1
ichan=21 istate=1

[...]

At this stage, pcm creates a number of postscript files: guess.ps and channel_*.ps. In guess.ps is plotted the first guess of the instrumental response and the Stokes parameters of both the calibrator the pulsar. In channel_*.ps are plotted the variations of the observed Stokes parameters as a function of parallactic angle in a selection of up to 13 frequency channels, which are evenly spaced across the band.

Next, pcm will output lines like:


pcm: solving model
Pulsar::ReceptionCalibrator::solve ichan=0
Pulsar::ReceptionCalibrator::solve failure ichan=0
Error::stack
        Calibration::ReceptionModel::solve
Error::InvalidRange
Error::message
        input source 0 with free parameter(s) not observed

Pulsar::ReceptionCalibrator::solve ichan=1
Calibration::ReceptionModel::solve converged in 53 iterations. 
  chi_sq=785.590026855469/406=1.93495082855225
Pulsar::ReceptionCalibrator::solve ichan=2
Calibration::ReceptionModel::solve converged in 40 iterations.
  chi_sq=739.773132324219/406=1.822101354599
Pulsar::ReceptionCalibrator::solve ichan=3
Calibration::ReceptionModel::solve converged in 30 iterations.
  chi_sq=737.575866699219/406=1.81668937206268

[...]

Pulsar::ReceptionCalibrator::solve ichan=36
Calibration::ReceptionModel::solve converged in 5 iterations.
  chi_sq=593.349975585938/406=1.4614531993866
Pulsar::ReceptionCalibrator::solve ichan=37
Calibration::ReceptionModel::solve converged in 6 iterations.
  chi_sq=626.255004882812/406=1.54250001907349
Pulsar::ReceptionCalibrator::solve ichan=38
Calibration::ReceptionModel::solve converged in 5 iterations.
  chi_sq=614.626037597656/406=1.51385724544525


Note the error message that arises because channel 0 was corrupted in all of the calibrator archives (the PolnCal Stokes parameters are assigned an input source index of zero). Note also that corruption due to aliasing during downconversion causes slower convergence and a larger reduced chi squared near the leading edge of the passband (which corresponds to the lowest values of ichan shown above). On a 1.2 GHz Pentium III, the solution takes approximately:
  • less than a minute with one pulse phase bin
  • about an hour with 16 pulse phase bins
  • about 19 hours with 64 pulse phase bins
  • When all of the frequency channels have been fitted, pcm will output the solution in the FEEDPAR HDU of a PSRFITS file named pcm.fits. It will also over-write channel_*.ps by plotting the same data with the best fit model curves drawn through the data points. It will also output a new file, result.ps, which plots the best-fit model parameters that describe the instrumental response and the Stokes parameters of the flux calibrator and noise diode. pcm then re-calibrates all of the Pulsar, PolnCal, and FluxCalOn files, producing new files with a .calib extension. Finally, the mean of the calibrated pulsar data is output in the file, total.ar and the fscrunched and tscrunched calibrated pulse profile is plotted in calibrated.ps.

    5.0 Known bugs and features that require implementation

    • Currently, pcm can handle data from only one pulsar.