Pulsars and neutron stars/ptaSimulate manual

Introduction

The ptaSimulate software has been developed to simulate data files from radio pulsar observations. The majority of the code is based on simulating realistic pulse arrival times, but the code can also produce simulated pulse profiles. The code produces tempo2 parameter (.par) and arrival time (.tim) files. These files can then be run through other pipelines (such as gravitational wave detection pipelines) as if they were actual observations.

Getting the software

The code is relatively straightforward to compile as it is completely written in C and only uses the fftw external library. Compilation will be similar to:

$ gcc -lm -o ptaSimulate *.c -lfftw3 /usr/lib/libfftw3f.so

Basic usage

The software makes use of an input text file that must be created by the user. This input file can have any filename and provides a description of the pulsars and the observing system to be simulated. The software is then run as

$ ./ptaSimulate <filename>

The software automatically produces a set of directories in the local directory. It then partially fills those directories with output files and also produces a set of tcsh scripts that need to be run to complete the simulations. Typical usage would be:

$ source <name>/scripts/runScript_master

The output is placed in <name>/output/<real_X>/ where X is the realisation number of the simulation. That directory contains the .par and .tim files for each simulated pulsar. For general usage of ptaSimulate, the following programs are required:

psrcat (with up-to-date database file)
tempo2 with the $TEMPO2 environment variable correctly set

In order to make profile templates to simulate realistic error bar sizes then the "ptime" software is also required.

Simple single pulsar simulation

The following script demonstrates how to make a very simple simulation. A single pulsar (J0437-4715) is simulated. The data sampling is regular (20 day cadence) and all ToAs have the same frequency (1400 MHz) and uncertainty (1us).

# This is a comment line
# This "define" section defines the properties of the simulation. 
# The "name" will be used as the base directory name. Nproc is
# the number of processors available and "nreal" is the number of 
# realisations of the simulations required.
<define>
name: sim1
nproc: 1
nreal: 1
</define>

# If only pulsar names are given then their parameters
# are automatically obtained from running "psrcat" on the
# command line
#
<pulsars>
psr: name=J0437-4715
</pulsars>

# This section defines the telescope which obtained the simulated
# data (standard tempo2 telescope code names are used), the start and
# end times of the observation run, the observing sampling (the cadence
# is given in days) and which schedule is run during each observing session.
# Note that multiple <obsRun> definitions can be used
#
<obsRun>
name: pks
tel: pks
start: 53371
finish: 56000
sampling: cadence=20
sched: sched1
</obsRun>

# This is the schedule that gets run during each observing session.
# Here we just observe PSR J0437-4715 with a ToA uncertainty of 1us
# and a frequency of 1400 MHz.
#
<schedule>
name: sched1
observe: psr=J0437-4715,toaerr=1e-6,freq=1400
</schedule>

Multiple pulsar simulation

The following script demonstrates how easy it is to simulate multiple pulsars.

<define>
name: sim2
nproc: 1
nreal: 1
</define>

# Here we provide the names of the three pulsars that we wish to simulate
<pulsars>
psr: name=J0437-4715
psr: name=J1022+1001
psr: name=J1909-3744
</pulsars>

<obsRun>
name: pks
tel: pks
start: 53371
finish: 56000
sampling: cadence=20
sched: sched1
</obsRun>

# Here we provide the observation details of each pulsar
<schedule>
name: sched1
observe: psr=J0437-4715,toaerr=1e-7,freq=1400
observe: psr=J1022+1001,toaerr=1e-6,freq=1400,start=55000
observe: psr=J1909-3744,toaerr=3e-7,freq=1400,start=54000,finish=56000
</schedule>