shoogle-pulsar 0.1.0

A Gibbs sampler for timing gamma-ray pulsars

shoogle

Shoogle is a python package for timing gamma-ray pulsars using Fermi-LAT data. It uses introduces sets of latent variables that transform the gamma-ray timing likelihood into more a tractable Gaussian distribution that can be fit analytically using standard pulsar-timing Gaussian process approximations, and uses the technique of Gibbs Sampling to marginalise over these latent variables.

The full method is described in the shoogle paper:

Timing Gamma-ray Pulsars using Gibbs Sampling
Clark, C. J., Valtolina, S., Nieder, L. and van Haasteren, R.
(2026), A&A, in press, arXiv:2601.07592

Please cite our paper if you use shoogle in your work.

Installation

To install the default (CPU-only) version of shoogle, run

pip install shoogle-pulsar

(ideally after creating and/or activating a dedicated virtual environment)

shoogle uses JAX and BlackJAX for sampling. These are much faster if they can run on a GPU instead of a CPU. To install shoogle with GPU-acceleration via CUDA (for NVidia hardware only), run:

pip install "shoogle-pulsar[cuda12]"

or

pip install "shoogle-pulsar[cuda13]"

depending on the version of your CUDA driver.

If you would like to run shoogle in a jupyter notebook, add the "nb" option, e.g.

pip install "shoogle-pulsar[cuda12,nb]"

Usage

After installation, the scripts run_shoogle and plot_shoogle will be added to your PATH, and should be available whenever your python environment is activated.

Running the sampler

To run the sampler, you will need:

• An "FT1" file, which is a .fits file containing the Fermi photon data. These files can be obtained from the FSSC. You will need to run gtsrcprob from the Fermitools to generate a column in the FT1 file containing photon probability weights. Pre-made FT1 files containing these weights for pulsars included in the Third Pulsar Catalog are also available from the FSSC 3PC page.

• An "FT2" file: the "spacecraft" fits file containing telemetry. This can also be downloaded from the FSSC.

• Optionally, a PINT-compatible .tim file containing radio ToAs for the same pulsar, if you want to try the experimental joint radio/gamma-ray fitting capabilities.

• A PINT-compatible .par file containing the pre-fit pulsar timing model.

• Optionally, a file describing noise model hyperparameters and Gaussian priors on timing model parameters. See below for syntax.

• A file describing the pre-fit pulse profile template. This can be obtained from the FT1 file (assuming the PULSE_PHASE column has been populated using the initial timing model by PINT or tempo2) using the itemplate.py script from GeoTOA-2.0.

The sampler is run via the run_shoogle command, with the above inputs. It will start by tuning MCMC samplers specific to the pulse profile template (and optional noise hyperparameters), before beginning the actual Gibbs sampling. It will monitor the autocorrelation time of the resulting sample chains, running until --nacor autocorrelation times (approximately the number of statistically independent samples) have been accumulated.

run_shoogle will periodically output an output file containing these sampling chains. This can be analysed with the plot_shoogle command, which will output the best-fitting timing model and uncertainties, and some plots showing the results of the sampling process. Please see the help message for these scripts (run_shoogle -h) for more details.

The examples directory contains ready-made inputs, scripts and a jupyter notebook that can be used as a guideline.

Notes:

• The timing model should be in a PINT-compatible .par file, with lines following:

  [PARAMETER] [Initial value] [free] [Uncertainty]
  

  The uncertainties specified here are not used by shoogle.

• Timing model parameters included in the priors file, using the same PINT syntax above, will have a Gaussian prior applied to them, centred on the specified value and with the provided uncertainty as the width.

  For example:

  PMRA     0    1   10
  

  Will place a zero-mean Gaussian prior on PMRA, with width 10 mas/yr.

• The following hyperparameters can be added to the priors file to define a noise model:

  TN_REDAMP: log10(amplitude) of timing noise. Amplitude is in units of yr^{3/2}, at a reference frequency of 1 yr^-1

  TN_REDFC: log10(corner frequency / 1 yr^-1)

  TN_REDGAM: high-frequency spectral index, PSD(f) ~ f^{-gamma} at high frequencies, so TN_REDGAM should be positive

  TN_REDKAPPA: (optional) log10 of flat tail level, in units of yr^{3/2}. Defaults to -20, an extremely small value.

  For orbital period variations, replace TN_ with OPV_, in which case the amplitude now refers to variations in the pulsar's time of ascending node.

  Additional components can be added to the noise model by adding, TN2_REDAMP, TN2_REDFC, TN2_REDGAM, TN3_REDAMP ... etc.

  The syntax for these hyperparameters is:

  [HYPERPARAMETER] [Initial value] [free]
  

  e.g.:

  TN_REDAMP        -14              1
  TN_REDFC         -2               0
  TN_REDGAM         4.333           0
  

  will fit for a GWB-like power-law-like spectrum (with a corner frequency of 1/100 yr, well below the sensitive band), where only the amplitude is free to vary.

• To make use of these hyperparameters, the parameters for the relevant basis functions need to be included in the .par file.

  For timing noise, these are PINT's WAVEX parameters. For orbital period variations, these are PINT'S ORBWAVE parameters.

  For performance reasons, if you include the ORBWAVES model, then do not mark these as free variables in the .par file. PINT's design matrix evaluation is very slow for these parameters, so this is handled automatically by shoogle.

• shoogle can also (optionally) fit for energy dependence in the template pulse profile. The input pulse profile does not need to change, shoogle will start from a constant-in-energy template and fit for energy dependence. The dependence is modelled as linear changes in the template parameters as a function of log10(energy).

License

shoogle is available under the BSD-3-Clause Licence. By downloading, cloning or forking this repository or its artifacts you, as the licensee, agree to the additional license terms as defined in the "Agreement on the provision of free-of-charge open-source software via the Internet" (DE/EN)

Contributing

Please see CONTRIBUTING.md