Metadata-Version: 2.4
Name: shoogle-pulsar
Version: 0.1.0
Summary: A Gibbs sampler for timing gamma-ray pulsars
Author-email: Colin Clark <colin.clark@aei.mpg.de>, Serena Valtolina <svaltolina@mpifr-bonn.mpg.de>, Lars Nieder <lars.nieder@aei.mpg.de>, Rutger van Haasteren <rutger.v.haasteren@aei.mpg.de>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/coclar/shoogle
Project-URL: Issues, https://github.com/coclar/shoogle/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.md
License-File: OSSAgreement.pdf
License-File: OSSVereinbarung.pdf
License-File: AUTHORS.md
License-File: CONTRIBUTING.md
Requires-Dist: pint-pulsar>=1.0.0
Requires-Dist: numpy>=1.23.0
Requires-Dist: astropy>=5.0.5
Requires-Dist: scipy>=1.9.0
Requires-Dist: matplotlib>=3.4.3
Requires-Dist: emcee>=3.0.1
Requires-Dist: corner>=2.0.1
Requires-Dist: scikit-learn>=1.5.1
Requires-Dist: tqdm>=4.67.1
Requires-Dist: jax[cpu]>=0.9.0
Requires-Dist: blackjax>=1.3.0
Provides-Extra: nb
Requires-Dist: jupyterlab; extra == "nb"
Requires-Dist: ipywidgets; extra == "nb"
Requires-Dist: widgetsnbextension; extra == "nb"
Provides-Extra: cuda12
Requires-Dist: jax[cuda12]>=0.9.0; extra == "cuda12"
Provides-Extra: cuda13
Requires-Dist: jax[cuda13]>=0.9.0; extra == "cuda13"
Dynamic: license-file

# 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](https://arxiv.org/abs/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](https://fermi.gsfc.nasa.gov/ssc/data/). You will need to run `gtsrcprob` from the
  [Fermitools](https://fermi.gsfc.nasa.gov/ssc/data/analysis/) 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](https://fermi.gsfc.nasa.gov/ssc/data/access/lat/3rd_PSR_catalog/).

* An "FT2" file: the "spacecraft" fits file containing telemetry. This can also be downloaded from
  the [FSSC](https://heasarc.gsfc.nasa.gov/FTP/fermi/data/lat/mission/spacecraft/).

* 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](https://fermi.gsfc.nasa.gov/ssc/data/analysis/user/).

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](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](OSSVereinbarung.pdf)/[EN](OSSAgreement.pdf))

## Contributing

Please see [CONTRIBUTING.md](CONTRIBUTING.md)
