PaperlayerView exact revision on arXiv

Source-linked AI summary

PINT: A Modern Software Package for Pulsar Timing

Jing Luo, Scott Ransom, Paul Demorest, Paul S. Ray, Anne Archibald, Matthew Kerr, Ross J. Jennings, Matteo Bachetti, Rutger van Haasteren, Chloe A. Champagne, Jonathan Colen, Camryn Phillips, Josef Zimmerman, Kevin Stovall, Michael T. Lam, Fredrick A. Jenet

arXiv:2012.00074v2astro-ph.IM

TL;DR

High-precision pulsar timing requires careful time handling, detailed physical models, and independent software validation. The paper presents PINT, a modular Python toolkit built for nanosecond-scale timing analysis and cross-checking against established packages. PINT reaches approximately 1 ns numerical precision, while its fitted parameters agree with Tempo/Tempo2 within their fit uncertainties and its residuals differ at about 10 ns and 1 ns, respectively.

  • Problem

    Pulsar-timing precision requires careful data handling and sophisticated models, while independent software is needed to verify results from traditional timing packages.

  • Method

    PINT is a Tempo/Tempo2-independent, object-oriented and modular Python toolkit using established scientific libraries, automated testing, and interactive analysis components.

  • Results

    PINT achieves approximately 1 ns numerical precision; on the same test data, its fitted parameters agree with Tempo/Tempo2 within fit uncertainties, with residual differences of about 10 ns and 1 ns, respectively.

  • Takeaways & Limitations

    PINT provides an extensible platform for high-precision timing analysis, cross-checking, and timing-related applications.

  • Takeaways & Limitations

    PINT and Tempo/Tempo2 have known implementation differences, including how constant time-offset corrections from instruments and pulse-profile evolution are assigned to frames.

Abstract

from arXiv · show

Over the past few decades, the measurement precision of some pulsar-timing experiments has advanced from ~10 us to ~10 ns, revealing many subtle phenomena. Such high precision demands both careful data handling and sophisticated timing models to avoid systematic error. To achieve these goals, we present PINT (PINT Is Not Tempo3), a high-precision Python pulsar timing data analysis package, which is hosted on GitHub and available on Python Package Index (PyPI) as pint-pulsar. PINT is well-tested, validated, object-oriented, and modular, enabling interactive data analysis and providing an extensible and flexible development platform for timing applications. It utilizes well-debugged public Python packages (e.g., the NumPy and Astropy libraries) and modern software development schemes (e.g., version control and efficient development with git and GitHub) and a continually expanding test suite for improved reliability, accuracy, and reproducibility. PINT is developed and implemented without referring to, copying, or transcribing the code from other traditional pulsar timing software packages (e.g., TEMPO and TEMPO2) and therefore provides a robust tool for cross-checking timing analyses and simulating pulse arrival times. In this paper, we describe the design, usage, and validation of PINT, and we compare timing results between it and TEMPO and TEMPO2.

1. INTRODUCTION

Pulsar timing exploits highly regular pulses to probe astrophysical systems and nanohertz gravitational waves, but its precision requires detailed physical models and independently verifiable software. PINT addresses this need with an independent, modular Python toolkit designed for high-precision analysis and cross-checking.

  • Pulsar timing compares observed and predicted pulse arrival times using models of the pulsar signal and its propagation, probing pulsars, companions, the interstellar medium, and Galactic dynamics.
  • Millisecond pulsars can provide arrival-time measurements better than 1 µs, supporting searches for gravitational waves near 10^-9 Hz with residual amplitudes around 10 ns.
  • Timing models must account for pulsar-system dynamics, solar-system dynamics, and interstellar-medium effects, then be refined by fitting observed times of arrival.
  • Independent software is needed to verify future gravitational-wave detections because Tempo2 largely derives from Tempo algorithms, motivating a separate implementation.
  • PINT is a Tempo/Tempo2-independent Python toolkit targeting approximately 1 ns precision and timing effects with amplitudes of approximately 1 ns or greater.
  • Its object-oriented, modular, documented, and tested design uses established scientific libraries and exposes PINT functionality for interactive analysis and other timing applications.

2. OVERVIEW OF PULSAR TIMING

Pulsar timing models pulse arrival times by combining pulse-phase calculations with propagation delays, then iteratively compares predictions against observations to refine the model. PINT supports this workflow with precise timing calculations and tools aimed at pulsar-timing-array analyses.

  • Pulsar timing obtains pulse arrival times, models emission and propagation, compares predictions with observations, and improves the model iteratively.
  • 2.1. Measuring TOAs: Template matching measures the phase shift between an observed folded pulse profile and a known template, which is converted into a TOA.Folding averages many pulses to increase signal-to-noise and mitigate pulse-to-pulse variation.
  • 2.2.1. Rotational Phase: Rotational phase tracks the cumulative number of pulsar rotations and is modeled with a Taylor expansion using pulse frequency and its derivatives.The model can be extended to represent glitches and glitch relaxation.
  • 2.2.2. Pulse Delays: The delay model converts observatory arrival times to emission times using atmospheric, Solar System, pulsar-motion, frequency-dependent, and binary-system delays.PINT normally includes Solar System Shapiro delays from the Sun and major planets when they exceed 1 ns.
  • 2.3. Comparing model to the data: Because residuals are ambiguous modulo one rotation, timing requires a sufficiently accurate model and iterative phase-connected fitting as new or more complex data are incorporated.PINT scales phase residuals by the apparent pulse frequency at the observation time for a more correct time-residual calculation.
  • PINT provides high-quality timing and software tools for Pulsar Timing Array analyses, including use with NANOGrav’s gravitational-wave inference package.

3. PINT

PINT uses modular coordinate, time, and data-handling components for high-precision pulsar timing, with TOAs and timing models kept largely independent. Its timing pipeline converts observatory times toward TDB using PINT, Astropy, and standard clock-correction procedures, while barycentric light-travel corrections are applied later.

  • 3.1. PINT Coordinates and Time: PINT uses the Solar System Barycenter as the reference frame and performs internal calculations in the JPL ephemeris ICRS J2000 coordinate system.
  • 3. PINT: TOAs and timing models remain independent data objects, interacting through PINT operations such as residual creation and model fitting.This operational separation is part of PINT’s design and implementation model.
  • 3.1. PINT Coordinates and Time: PINT stores TOAs as high-precision MJD values, normally in the observatory timescale, while also accepting special reference frames such as the SSB or geocenter.Its two-part astropy.time.Time representation supports approximately 1 ns numerical precision.
  • 3.1. PINT Coordinates and Time: PINT converts observatory-clock TOAs from UTC(obs) toward TDB through UTC(GPS), leap-second and TT handling, and subsequent barycentric-time conversion.PINT handles local-clock and TT(BIPM) corrections, while Astropy performs other clock-conversion steps.
  • 3.1. PINT Coordinates and Time: PINT supports TDB, whereas Tempo2 defaults to TCB but permits TDB for compatibility, with future TCB support planned for PINT.
  • 3.1. PINT Coordinates and Time: Barycentric light-travel corrections occur after clock conversion because they require timing-model astrometry and a Solar System ephemeris, not TOAs alone.

3.2. PINT code architecture

PINT’s architecture separates timing analysis into modular components with public interfaces that can be used independently or together. Its TOA and observatory machinery supports reading, transforming, storing, and analyzing observations from diverse facilities.

  • PINT organizes timing analysis into four major modules: pint.toa, pint.models, pint.residuals, and pint.fitter.These modules respectively handle TOAs, timing models, residuals, and parameter fitting.
  • Public interfaces allow TOAs, TimingModel, and Residuals objects to be initialized independently, while fitter classes combine TOAs and TimingModel through Residuals.This supports analyzing timing-model details without requiring TOAs and accommodates different fitting methods.
  • PINT’s standard model-updating workflow uses TOAs, TimingModel, residuals, and fitter classes together as a Tempo/Tempo2 substitute.The workflow is illustrated with a code example that reads parameter and TOA files, computes pre-fit residuals, and supports fitting.
  • The TOA module reads and preprocesses Princeton, Parkes, and Tempo2-format files, storing observations and metadata in the publicly accessible TOAs.table Astropy table.Stored metadata includes observing frequencies, TOA errors, and observatories.
  • TOA processing applies clock corrections, computes TDB times, and calculates observatory-dependent positions and velocities through the observatory module.The observatory APIs support positions, velocities, clock corrections, and time transformations for stationary and moving observatories.
  • PINT distinguishes stationary ground observatories using TopoObs from geocenter, solar-system-barycenter, and spacecraft locations handled by SpecialLocation.SpecialLocation supports orbital or spacecraft flight data rather than Earth-fixed coordinate information.

3.4. Models Module

PINT’s models module represents physical timing effects as independently implemented components managed by a TimingModel. The design enforces required computation order while remaining extensible to noise models and other component types.

  • PINT separates physical timing effects into Component subclasses whose results are combined by the TimingModel interface.Delay contributions are added, while time-dependent components are evaluated in an enforced order because one delay can affect another component’s evaluation time.
  • The models module explicitly supports DelayComponent and PhaseComponent calculations through TimingModel.delay() and TimingModel.phase().These methods sum the results from the included delay and phase components.
  • PINT extends beyond delay and phase components with NoiseComponent support and APIs such as designmatrix() for fitting and Bayesian timing analyses.The component framework is designed to accommodate additional model types and custom extensions.
  • get_model() builds a TimingModel from a Tempo/Tempo2-style .par file by selecting and sorting components and parsing parameter values.The wrapper get_model_and_toas() can construct the model and TOAs together from .par and .tim inputs.
  • Figure 5 depicts inheritance from Component through DelayComponent and PhaseComponent, with TimingModel containing the selected model components.Astrometry, Dispersion, and Binary inherit from DelayComponent, while Spin_down and Glitch inherit from PhaseComponent.

3.5. Residual Module

PINT computes phase and time residuals between observed TOAs and timing models, then uses fitter classes to adjust model parameters. The fitter API supports multiple optimization algorithms and preserves pre-fit models for reset and comparison.

  • The Residuals class computes phase and time residuals from TOAs and a TimingModel using calc_phase_resids() and calc_time_resids().Residuals quantify the difference between observations and the timing model for fitting and goodness-of-fit assessment.
  • PINT 0.8.0 lists its built-in TimingModel categories and fitting algorithms in Tables 3 and 4.These tables identify the available model components and implemented fitter choices.
  • Residuals are weighted by TOA uncertainty by default, with optional pulse-number-based calculations and convenience statistics including χ2 and reduced χ2.The weighting behavior can be disabled through a class-method argument.
  • The fitter module provides a base Fitter API and predefined subclasses whose fit_toas() methods implement specific optimization algorithms.New fitting algorithms can be added by overriding fit_toas() while retaining the common interface.
  • Fitter instances use TOAs and TimingModel objects, update post-fit model and residual attributes, and retain the initial model for reset through reset_model().This preserves a direct route back to the original timing model while fitting changes parameters.

4. COMPARISON OF PINT WITH Tempo/Tempo2

PINT is validated against Tempo and Tempo2 using PSR J1600−3053 data and controlled simulations. The results reproduce fitted parameters and reveal implementation-dependent residual differences, including clock corrections and precession-nutation models.

  • 4.1.1. Comparison with Tempo results: Tempo and PINT differ by an annual residual signature with peak amplitude about 20 ns, primarily due to their different precession-nutation models.PINT uses Astropy’s IAU 2000 model, whereas Tempo uses IAU 1976 precession and IAU 1980 nutation models.
  • 4.1.1. Comparison with Tempo results: Simulations attribute additional residual discrepancies to the absence of polar motion in the Tempo-style precession-nutation model.The expected difference is near ±30 ns with diurnal structure modulated by annual and 435-day periodicities.
  • 4.1.1. Comparison with Tempo results: PINT reproduces the published PSR J1600−3053 timing solution, with all post-fit parameters consistent with Tempo within 1-σ uncertainties.The PINT fit has WRMS 0.944 µs and χ2=12368.10 for 12307 degrees of freedom; Tempo gives WRMS 0.944 µs and χ2=12368.46.
  • 4.2. Other known implementation differences between PINT and Tempo/Tempo2: PINT applies a 10-nanosecond-level UTC(GPS)-to-standard-UTC correction that Tempo does not apply.This difference is documented as an implementation difference affecting TOA handling.
  • 4.2. Other known implementation differences between PINT and Tempo/Tempo2: PINT’s independently implemented framework and APIs support cross-checking physical models and identifying implementation differences with other timing software.The paper notes that this approach helped identify differences described in the comparison and long-standing Tempo2 bugs.

5. PERFORMANCE, TESTING, AND MAINTENANCE

PINT combines optimized numerical operations with profiling, automated testing, version control, and documentation. Its performance depends on workload: it is slower for some preprocessing-heavy small problems but can outperform Tempo and Tempo2 during fitting.

  • 5.1. Performance: PINT uses NumPy and SciPy vectorization and cached intermediate results to mitigate Python’s startup and interpreted-loop performance costs.The relative performance therefore depends on the particular problem and how PINT is used.
  • 5.1. Performance: PINT is slower and more RAM-intensive than Tempo and Tempo2 for small preprocessing-heavy problems dominated by text-file TOA loading and position calculations.PINT’s pickling functionality allows processed TOAs to be saved and reloaded quickly.
  • 5.1. Performance: PINT fitting outperforms Tempo and Tempo2 in the reported performance comparison.The paper attributes this possibility to differences in linear-algebra libraries or generalized-least-squares implementations.
  • 5.1. Performance: Profiling tools identify PINT bottlenecks, and the authors report reducing some benchmark times by over 15%.The package includes cProfile-based summary reports and flow-chart generation.
  • 5.2. Testing: PINT systematically runs most tests before code changes to support reliability, reproducibility, stability, and compatibility across operating systems and Python versions.As of version 0.8.0, the tests executed 58.05% of the code, with greater coverage identified as a future goal.
  • 5.3. Maintenance: PINT is distributed as open-source software under the BSD 3-clause license and maintained through GitHub-based version control and collaborative contributions.Documentation is automatically compiled and deployed after changes are merged.

6. EXAMPLE PINT USE CASES

PINT is usable both as a Python library and through distributed command-line and graphical tools. Its examples cover radio timing, barycentering, simulation, interactive fitting, and high-energy photon-event analysis.

  • 6. EXAMPLE PINT USE CASES: PINT provides command-line scripts that let users perform common timing tasks without explicitly writing Python code.The scripts are distributed both as examples and as practical interfaces for users.
  • 6.1. Radio timing scripts: pintempo reads timing models and TOAs, fits parameters, and can generate residual plots with functionality similar to Tempo and Tempo2.It is intended for standard pulsar-timing workflows.
  • 6.1. Radio timing scripts: pintbary converts specified times to the TDB timescale and applies Solar System delays for a chosen observatory and observing frequency.This provides a focused barycentering workflow.
  • 6.1. Radio timing scripts: pintk supports interactive model and TOA editing, fitting, residual visualization, TOA subset selection, JUMPs, phase wraps, and phase-connection checks.It can also display random models drawn from each fit’s covariance matrix to assess extrapolation.
  • 6.1. Radio timing scripts: zima generates simulated TOAs from an input timing model.This supports simulation-based timing workflows.
  • 6.2. High-energy photon data: PINT treats photon arrival events as TOAs and provides tools for pulse-phase computation and photon-data model fitting.Supported workflows include NICER, XMM-Newton, NuSTAR, RXTE, and Fermi data, with photon weights available for Fermi processing.

7. CONCLUSION AND DISCUSSION

PINT provides a modular, object-oriented platform for high-precision pulsar-timing analysis, with numerical precision near 1 ns and algorithmic precision of a few ns or better. On the same test data, its fitted parameters agree with Tempo/Tempo2 within their uncertainties, while residual differences are at the 10 ns and 1 ns levels.

  • PINT processes high-precision pulsar-timing data with numerical precision of ∼1 ns and algorithmic precision of a few ns or better.
  • PINT is built as an object-oriented, modular platform using well-debugged Python libraries and modern git and GitHub development practices.
  • PINT’s four core modules are toa, models, fitter, and residuals, covering TOA processing, model organization, fitting, and residual analysis.
  • PINT’s post-fit parameters agree with Tempo/Tempo2 within their fit uncertainties on the same test dataset.
  • Residuals from PINT differ from Tempo and Tempo2 at the levels of 10 ns and 1 ns, respectively, with known discrepancy sources described.

A. CREATE A TIMING MODEL COMPONENT

PINT model components combine parameters, model functions, and derivative functions within registered APIs. These conventions let TimingModel collect component outputs and derivatives while supporting new components and automatic model construction.

  • PINT’s independently implemented framework is expandable to new timing models, with a complete component implementation illustrated in Figure 14.
  • A timing model component comprises model parameters, model functions, and derivative functions.Parameters represent astrophysical quantities, while model functions compute outputs such as delays, phases, or noise effects.
  • Component outputs must use accepted formats and registered model functions so TimingModel can collect and combine them correctly.For example, delay functions return time-valued Astropy quantities, while phase functions return PINT Phase objects.
  • Derivative functions use a consistent registration API, allowing TimingModel to enumerate derivatives across components and sum them for each target parameter.

A.1. Parameter module

PINT’s Parameter module represents diverse timing-model values with typed subclasses, units, uncertainties, file I/O, and optional Bayesian priors. Its quantity-based interface performs unit-aware arithmetic and conversions automatically.

  • Parameter subclasses handle strings, angles, floating-point values, dates, prefixed families, and TOA-masked parameters such as JUMPs.
  • Parameter objects integrate values with units and uncertainties, supporting automatic conversions while retaining raw numerical access in declared units.Values and uncertainties can be read or changed through quantity-based or numerical properties.
  • Parameters can be parsed from and serialized to .par-style file lines using from_parfile_line() and as_parfile_line().
  • A parameter’s prior probability density can be stored in its prior attribute for Bayesian timing estimation such as MCMC fitting.
  • Component.add_param() registers a parameter with the component and parameter namespace, enabling automatic model selection by parameter names.

A.2. Connecting components to the TimingModel

PINT’s model builder constructs TimingModel instances from parameter files by selecting and ordering compatible components. The get_model() interface handles component instantiation and parameter loading.

  • get_model() uses ModelBuilder to instantiate timing components, register derivatives, select components, order them, and read parameter values.
  • The model-building workflow is illustrated with code examples for the parameter module and TimingModel module.
  • ModelBuilder identifies components through component-specific parameters found in the input .par file and enforces category-compatible selections.
Loading 2012.00074v2…