PINT: Pulsar Timing Package

PINT is a pulsar timing solution developed in Python using modern libraries. It is designed to be a robust, independent alternative to TEMPO and Tempo2 for checking high-precision timing results.

Key features include:

• High Precision: Produces residuals from most 'normal' timing models that agree with Tempo and Tempo2 to within approximately 10 nanoseconds.
• Extensibility: Built with a modern design to be easily modified and extended.
• Flexible Usage: Can be used directly within Python scripts, Jupyter notebooks, or via several included command-line tools.

The following software packages utilize PINT in their workflows or as dependencies:

• APT
• baseband-tasks
• chimera
• darkmatter_and_pint
• ENTERPRISE
• enterprise_extensions
• enterprise_outliers
• GammaPulsar
• HENDRICS
• NICERSoft
• nustar-clock-utils
• pint_pal
• PsrSigSim
• pymars
• stingray
• tat-pulsar
• TOAextractor
• Vela.jl

When using TimeDomainSWNoise, note the following hyperparameter behaviors:

• TDSWLOGSIG: This is the amplitude hyperparameter, defined as $\log_{10}\sigma$, where $\sigma$ is in $\text{cm}^{-3}$ (not seconds). Physically sensible values are around unity (e.g., TDSWLOGSIG 0.0 implies $\sigma = 1\text{ cm}^{-3}$, which is comparable to the mean density NE_SW).
• Relationship to NE_SW: Because the interpolation basis is a partition of unity, a constant set of GP coefficients is mathematically equivalent to a shift in the NE_SW parameter. Therefore, the GP should be used to model departures from the mean density.
• Resolution: The resolution of the model is determined by the node spacing (TDSWDT), rather than the number of Fourier modes used in spectral models.

PINT is designed to support multiple Python versions. When writing code:

• Supported Versions: Python 2.7, 3.5, 3.6, 3.7, and later.
• Modern Constructs: Use modern Python features like sets, iterators, and the .format() string method.
• Cross-Version Compatibility: Use the six library to manage compatibility issues between Python 2 and Python 3.

TimeDomainSWNoise is the first PINT component to use a non-diagonal prior $\Phi$. To support this, several core PINT components have been updated to accept either a 1-D weight vector (for diagonal models) or a 2-D covariance matrix (for dense models). This includes:

• pint.models.timing_model.TimingModel.noise_model_basis_weight
• GLS fitters
• pint.utils.woodbury_dot
• pint.residuals.whiten_residuals

When mixing diagonal and dense components, PINT treats the prior $\Phi$ as a block-diagonal matrix, with one block per component.

Pulsar timing models often have an overall phase offset between the reference TOA (TZR TOA) and measured TOAs. PINT handles this in three ways:

1. Implicit subtraction: By default, PINT subtracts the weighted mean from the timing residuals.
2. Fittable TZR TOA: Making the TZRMJD parameter fittable (noting this is complex due to clock corrections).
3. Explicit phase offset (PHOFF): Adding a PHOFF parameter to the pulsar ephemeris (.par) file.

Note: If you provide an explicit PHOFF parameter, PINT's default behavior of implicit residual mean subtraction is disabled.

Example PHOFF entry in a .par file: PHOFF 0.1 1 0.001

PINT primarily uses Barycentric Dynamical Time (TDB). Because of relativistic effects and Earth's gravity, time scales must be handled carefully.

• TDB vs TCB: TEMPO2 uses Barycentric Coordinate Time (TCB) by default. TCB and TDB do not advance at the same rate and have a multi-second offset.
• Conversions:
  • Use the PINT command-line tool tcb2tdb to approximately convert TCB timing models to TDB.
  • PINT can optionally perform approximate TCB to TDB conversion upon reading timing models.
• Leap Seconds: PINT relies on up-to-date leap second data (via astropy). If you see timing anomalies on days with leap seconds, ensure your leap-second data files are current.
• Observatory Clocks: PINT requires up-to-date observatory clock correction files (e.g., GPS-tracked maser drifts) to produce accurate results.

A TimingModel is the central object used to calculate pulse arrival times. It provides access to a collection of Parameter objects.

Computation is performed by Component objects. These components are selected automatically during the parsing of a parameter file based on the parameters present:

• Binary Models: Selected explicitly using the BINARY parameter.
• Non-binary Components: Selected if a parameter unique to that component is included (e.g., including ELAT selects the AstrometryEcliptic component).
• Hierarchical Triples: An outer orbit can be selected using the BINARY2 parameter (parameters for this orbit use a _2 suffix, such as PB_2).

Note that if a parameter file contains ambiguous or contradictory parameters, PINT will raise an exception.

When code cannot continue and cannot produce a sensible result, raise an exception.

• Standard errors: Use ValueError with a descriptive message for most issues.
• Custom exceptions: If you want users to catch specific errors (e.g., to detect when a container is empty), define a new exception class inheriting from ValueError.

Example of a custom exception:

class PulsarProblem(ValueError): 
    pass

Catching specific errors:

try:
    # code that might raise PulsarProblem
    pass
except PulsarProblem:
    # handle the specific pulsar-related error
    pass