PSRCHIVE user documentation: `pcm`

1.0 Purpose

Based on the Pulsar Archive (PSRCHIVE) software library, 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. In order to run pcm, 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).
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 determined by the Pulsar::Archive::calibrator_match method.

What pcm does (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 all pulsar data and selects the Stokes parameters from a set of specified 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.

2.0 Usage

2.1 Before running `pcm`

Create a calibrator directory and database file using pac:
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 total integrated profile using psradd and either:
1. manually choose individual phase bins or ranges of pulse phase that make good model constraints, or
2. allow pcm to choose the best pulse phase bins, as described in section 4.1.

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.

The more phase bins used as constraints, the more time required to converge to a solution and the smaller the experimental uncertainty. For starters, use only two phase bins; pcm will converge more quickly, providing a first order estimate of the instrumental parameters before wasting hours of CPU time.

2.2 Running `pcm`

Currently, pcm can be run in two different modes:

Mode A: Fit multiple observations as a function of parallactic angle
Mode B: Fit a single observation to a single, well-calibrated standard, as described in van Straten 2004b (astro-ph/0402666).

An example of Mode A usage is provided in section 4.1.

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 Mode A Example

For this example, suppose that all of your pulsar observations are located in the current working directory and have the extension, .ar; all of your calibrator archives are summarized in the data base, $MYCALS/database.txt. Now, 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 have created a total integrated archive, total.ar, and would like pcm to choose the best constraints. The command line is:

pcm -c total.ar -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.

Last Updated 24/10/2004 by Willem van Straten

PSRCHIVE user documentation: pcm