Pulsars and neutron stars/ptaSimulate manual
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
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>