An open-source package for neutron star X-ray Pulse Simulation and Inference.

X-PSI is designed to simulate rotationally-modified (pulsed) surface X-ray emission from neutron stars, taking into account relativistic effects on the emitted radiation. This can then be used to perform Bayesian statistical inference on real or simulated astronomical data sets. Model parameters of interest may include neutron star mass and radius (useful to constrain the properties of ultradense nuclear matter) or the system geometry and properties of the hot emitting surface-regions. To achieve this, X-PSI couples code for likelihood functionality (simulation) with existing open-source software for posterior sampling (inference).


The video below, generated by X-PSI, shows a neutron star with non-uniform surface temperature, as it rotates. In this specific case the star hosts a photospheric radiation field whose asymmetry is driven by an underlying ocean wave (a buoyant \(r\)-mode) of thermonuclear burning. The wave is effectively periodic over a small number of rotational cycles. The simulation was generated by feeding a wave solution, computed by Frank Chambers (University of Amsterdam),[1] in the form of a field of temperatures in surface local-comoving frames (\(\sim\! 10^{6}\,\mathrm{K}\)), to X-PSI for photospheric imaging. A number of simplifying assumptions are made in mode calculation and imaging, but this serves to illustrate the simulation and visualisation of a neutron star that pulses in the X-ray regime due to rotational modulation of some mode of radiative asymmetry at the surface.

Each panel displays a specific photon intensity sky map. Panels from top-left to bottom-right increase in photon energy. The intensity field in each panel is uniquely normalised to the maximum intensity over all phases and sky directions. The remarkable evolution of the image with photon energy is due to relativistic beaming: at energies much greater than the characteristic temperature, the contribution to the image is entirely dominated by the hottest region of the surface being relativistically beamed toward the observer as it approaches on the left-side of the star. This is the same effect seen in many other astrophysical simulations, particularly of images of (supermassive) accreting black holes (for instance by the Event Horizon Telescope collaboration), although it was interestingly omitted from the motion picture film Interstellar.[2]

The following image integrates (and thus averages) over waveband (a range of photon energies). We also decrease the mode frequency relative to the stellar spin frequency, such that the mode is not as equatorially trapped.[3]

If one integrates over solid angle (i.e., over sky directions), one is left with a specific photon flux in a joint space of photon energy and time (i.e., rotational phase). This is natural because galactic neutron stars subtend far too small a solid angle on the sky to be spatially resolved by any telescope: they are point sources. We must nevertheless account for the variation of intensity with sky direction if we are to compute the data-generating process. If one then integrates over phase, the phase-averaged spectrum of photons incident on a telescope is yielded; if one instead integrates over some waveband, a photon pulse-profile is yielded. The following displays several cycles of a phase-energy resolved pulse-profile generated by the more equatorially trapped, \(r\)-mode rendered above.


The integration over energy is, for likelihood function evaluation, modified by a kernel for the response of an X-ray telescope to the incident radiation field.


[1]See, e.g., Chambers & Watts 2020.
[2]See James et al. 2015.
[3]There are a number of visualisation possibilities. For instance, we could average the image(s) over phase and/or energy to yield a single static image; we could plot phase evolution in one spatial dimension (with energy variation in the second) or two spatial dimensions (perhaps with energy dependence rendered in time). We could also render in space and/or time, variation of the images with stellar parameters such as gravitational mass, and geometric parameters such as observer inclination to the stellar rotation axis. We could plot an image evolving in time, with other panels rendering a photon specrum and a pulse-profile evolving in time with the image; here is an example.


If X-PSI proves to be a useful tool for your work, please cite the project as a software acknowledgement, e.g.:

X-PSI (\url{https://github.com/ThomasEdwardRiley/xpsi})

A JOSS paper is being drafted for the first major release. The technical notes in the repository on path /docs/technical will be updated and made available on the arXiv in the future. The first version of a subset of these technical notes appeared in a PhD thesis which you could cite if you wish to cite a published work in the meantime:

    author = {{Riley}, Thomas E.},
    title = "{Neutron star parameter estimation from a NICER perspective}",
    school = {University of Amsterdam},
    year = 2019,
    address = {https://hdl.handle.net/11245.1/aa86fcf3-2437-4bc2-810e-cf9f30a98f7a},
    month = 12

Lastly, if you wish to point to the first published application of the X-PSI package, then please cite Riley et al. 2019 (ApJL, 887, L21):

    author = {{Riley}, T.~E. and {Watts}, A.~L. and {Bogdanov}, S. and {Ray}, P.~S. and {Ludlam}, R.~M. and {Guillot}, S. and {Arzoumanian}, Z. and {Baker}, C.~L. and {Bilous}, A.~V. and {Chakrabarty}, D. and {Gendreau}, K.~C. and {Harding}, A.~K. and {Ho}, W.~C.~G. and {Lattimer}, J.~M. and {Morsink}, S.~M. and {Strohmayer}, T.~E.},
    title = "{A NICER View of PSR J0030+0451: Millisecond Pulsar Parameter Estimation}",
    doi = {10.3847/2041-8213/ab481c},
    journal = {\apjl},
    month = dec,
    year = 2019,
    volume = 887,
    pages = {L21}

This article contains a wealth of relevant information, including a number of schematic diagrams that might be of use. There is also an ApJL Focus Issue of which this article is a member.

State of development

The targeted release for the first major version of X-PSI is September 2020. Future development plans and the project History provide a breakdown of the state of the project.

The initial development of X-PSI was checkpointed with the completion of Riley et al. 2019 (ApJL, 887, L21), and tagged as v0.1. X-PSI remains, however, in the initial development stage. Backwards incompatible changes will be committed without incrementing the major version. The package should not be considered stable, and as such has not been packaged for automatic installation via a package manager (namely Conda nor PyPI). To install X-PSI from source, and to install dependencies, see the Installation page.


These documentation pages are being rapidly updated during development.

These pages were generated from a local development build. The pages often reference v0.1 that is tagged on the master branch of the repo, but that version is not explicitly documented.

The tutorials and examples in these documentation pages however, use v0.5 of X-PSI. The required files (i.e., data files and NICER v1.01 instrument files) may be obtained from a different repository due to file size considerations:

git clone https://github.com/ThomasEdwardRiley/xpsi_workshop.git </path/to/clone>

This repository also contains unexecuted tutorial notebooks with less verbosity if this is preferred. Refer to the repository README for instructions regarding large files.

Other examples may be found on path xpsi/examples. Note, however, that these examples used v0.1 of X-PSI, which can be checked out via the tag on the master branch. Eventually, example files will be archived with Zenodo to accompany a JOSS paper. Moreover, the examples require cluster usage and will have to be updated for release of the first major version of X-PSI.