Configuration file

The configuration file is a Python file that allows to adjust several parameters of the run. The parameters that can be set in the configuration file are:

pta_data

Default: 'NG15'– This variable needs to be assigned to a string specifying the PTA dataset which will be used in the analysis. The datasets currently implemented in PTArcade are NANOGrav 15-year (pta_data = "NG15"), NANOGrav 12.5-year (pta_data = "NG12"), and IPTA DR2 (pta_data = "IPTA2").

N_samples

Default: int(2e6) – This variable can be assigned to an integer specifying the number of points that will be generated by the Monte Carlo sampler.

Thinning

In order to reduce the autocorrelation length, the MC chains are automatically thinned by a factor of 10. Therefore, the number of MC samples that will be saved is given by N_samples/10.

mode

Default: ceffyl – PTArcade can be run in two modes:

  • mode = "enterprise": In this configuration, the code will analyze the full PTA dataset in the time domain by using the numerical techniques implemented in ENTERPRISE.

  • mode = "ceffyl": In this configuration, the code will analyze PTA data at the level of the Bayesian peridograms (1), and fit the user-specified signal to these periodograms using the numerical techniques implemented in Ceffyl.

    1. Probability density reconstructions of the pulsar-timing-residual power-spectral-density at each frequency (commonly referred to as the "violin plot"). See here for more details.

Ceffyl and Deterministic Signals

The Ceffyl mode can only be used to analyze stochastic signals. If your signal is deterministic, you have to run the code in ENTERPRISE-mode.

Additional Citations

If you use PTArcade in ENTERPRISE-mode, please add the following citations:

@misc{enterprise,
    author       = {Justin A. Ellis and Michele Vallisneri and Stephen R. Taylor and Paul T. Baker},
    title        = {ENTERPRISE: Enhanced Numerical Toolbox Enabling a Robust PulsaR Inference SuitE},
    month        = sep,
    year         = 2020,
    howpublished = {Zenodo},
    doi          = {10.5281/zenodo.4059815},
    url          = {https://doi.org/10.5281/zenodo.4059815}
    }

@misc{enterprise-ext,
    author       = {Stephen R. Taylor and Paul T. Baker and Jeffrey S. Hazboun and Joseph Simon and Sarah J. Vigeland},
    title        = {enterprise_extensions},
    year         = {2021},
    url          = {https://github.com/nanograv/enterprise_extensions},
    note         = {v2.3.3}
    }

If you use PTArcade in Ceffyl mode, please cite

@misc{lamb2023need,
    title={The Need For Speed: Rapid Refitting Techniques for Bayesian Spectral Characterization of the Gravitational Wave Background Using PTAs}, 
    author={William G. Lamb and Stephen R. Taylor and Rutger van Haasteren},
    year={2023},
    eprint={2303.15442},
    archivePrefix={arXiv},
    primaryClass={astro-ph.HE}
    }
out_dir

Default: './chains/' – This variable can be assigned to a string to specify the output directory.

resume

Default: False – If resume = True, the code will look for MCMC chains in the output directory and, if it finds any, it will restart sampling from those instead of starting from scratch. If resume = True, but no chains are found in the output directory, the sampler will start from scratch.

Warning

If resume = False (which is the default value), any chain that is present in the output directory at the start of your run will be overwritten.

mod_sel

Default: False – PTArcade can also be used to compare new-physics interpretations of PTA signals against the astrophysical interpretation in terms of SMBHBs. If mod_sel = True, a model-indexing variable controlling which model likelihood is active at each MCMC iteration will be sampled along with the parameters of the competing model. This will then allow to derive the Bayes factor between models by simply taking the ratio of samples spent in each bin of the model-indexing variable.

Get the Bayes factor

After running with mod_sel = True, you can easily derive the Bayes factor using the function get_bf defined in the PTArcade chains_utils module.

Mod sel and Ceffyl

At the moment mod_sel can only be used with mode="enterprise". We are currently working on adding the mod_sel option to the Ceffyl-mode.

corr

Default: False – This parameter controls the inter-pulsar correlations for any user-specified stochastic signal. If corr=False, spatial correlations between pulsars are set to zero and the overlap reduction function is taken to be a delta function in the pulsar space. If corr=True, Hellings & Downs correlations are assumed.

Running time

When mode = "enterprise", running with corr = True is approximately one order of magnitude slower than running with corr = False. If you want to run with corr = True, we suggest either using mode = "ceffyl" or running the code on a cluster.

NG12 and IPTA2 in ceffyl mode

For the NANOGrav 12.5-year and IPTA DR2 data sets, the KDEs for the free spectra were derived only without spatial correlations (for these data sets the inclusion of pulsar-correlations is not expected to impact the spectral reconstruction significantly). Therefore, for these datasets, ceffyl mode can run only with corr=False.

red_components

Default: 30 – This variable can be assigned to an integer specifying the number of frequency components that will be used to model intrinsic red noise. (1)

  1. Intrinsic red noise is modeled using a Fourier basis of frequencies \(i/T_{\textrm{obs}}\), where \(i\) indexes the harmonics of the basis and \(T_{\textrm{obs}}\) is the timing baseline. The red_components parameter sets the harmonics at which this expansion is truncated.
gwb_components

Default: 14 – This variable can be assigned to an integer specifying the number of frequency components that will be used to model common red noise. (1)

  1. The common red noise produced induced by a GWB is modeled using a Fourier basis of frequencies \(i/T_{\textrm{obs}}\), where \(i\) indexes the harmonics of the basis and \(T_{\textrm{obs}}\) is the timing baseline. The gwb_components parameter sets the harmonics at which this expansion is truncated.

Suggested Number of GWB Components

We suggest using gwb_components = 13.

We suggest using gwb_components = 5.

We suggest using gwb_components = 14.

As we already mentioned, the GWB signal specified by the user can be superimposed with the signal from SMBHBs or compared to it. The GWB signal from SMBHBs is modeled as a power-law:

\[ h^2\Omega_{\textrm{GW}}(f) = \frac{2 \pi^2 A_{\textrm{BHB}}^2}{3 H_0^2} \left(\frac{f}{\textrm{year}^{-1}}\right)^{5-\gamma_{\textrm{BHB}}}\textrm{year}^{-2}. \]

The prior distributions for \(A_{\textrm{BHB}}\) and \(\gamma_{\textrm{BHB}}\) can be controlled with the following parameters in the configuration file:

bhb_th_prior

Default: True – If bhb_th_prior = True, the prior for the SMBHB signal parameters will be chosen to reflect predictions from astrophysical models. This is only relevant if you have selected smbhb = True in the model file or mod_sel = True in the configuration file. (1)

  1. For more information on the astrophysical models used to derived these priors, see here and here
A_bhb_logmin

Default: -18 – Can be assigned to a floating point or integer number to set the lower bound of the log-uniform prior for the SMBHB-signal amplitude. This is only relevant if bhb_th_prior = False and you have selected smbhb = True in the model file or mod_sel = True in the configuration file.

A_bhb_logmax

Default: -14 – Can be assigned to a floating point or integer number to set the upper bound of the log-uniform prior for the SMBHB-signal amplitude. This is only relevant if bhb_th_prior = False and you have selected smbhb = True in the model file or mod_sel = True in the configuration file.

gamma_bhb

Default: None – Can be assigned to a floating point or integer number to set the value of \(\gamma_{\textrm{BHB}}\). If gamma_bhb = None, a uniform prior between \(0\) and \(7\) will be used instead.

Default Configuration File

If no configuration file is specified by the user, the following file will be used instead

pta_data = 'NG15'

mode = 'ceffyl'

mod_sel = False

out_dir = './chains/'
resume = False 
N_samples = int(2e6) 

# intrinsic red noises parameters
red_components = 14 

# bhbh signal parameters
corr = False 
gwb_components = 14 
bhb_th_prior = True