Skip to content

feat: updated accuracy of TCB-->TDB conversion - #2040

Draft
vhaasteren wants to merge 9 commits into
nanograv:masterfrom
vhaasteren:feat/tcb2tdb
Draft

vhaasteren wants to merge 9 commits into
nanograv:masterfrom
vhaasteren:feat/tcb2tdb

Conversation

@vhaasteren

Copy link
Copy Markdown
Member

PR description

This PR updates PINT’s TCB<-->TDB converter to support auditable, no-refit conversion at approximately nanosecond accuracy for the deterministic components that PINT explicitly supports.

My motivation is automatic pulsar-data combination in MetaPulsar. Combining releases from different PTAs sometimes requires converting TCB and TDB par files across timing engines. Refitting during ingestion is undesirable: it changes the scientific product and makes automated combinations harder to reproduce. For supported models, conversion should instead preserve the same physical timing solution.

The old converter used the legacy IFTE common-origin mapping. In particular, its epoch conversion omitted the approximately 65.5 μs TDB offset and used a slightly different rate from the IAU 2006 definition. Its DM scaling also did not match PINT’s actual fixed-frequency forward model.

This implementation follows several requirements we set before writing the code:

  • Match PINT’s existing TDB forward model rather than defining an independent convention.
  • Use Astropy/ERFA for IAU 2006 coordinate-time conversion.
  • Keep radio frequency undilated, consistent with PINT’s DILATEFREQ N behavior.
  • Avoid duplicated parameter lists where component-owned metadata can express the conversion.
  • Convert everything currently supported, while leaving unsupported terms unchanged and warning clearly.
  • Distinguish “conversion completed” from “conversion satisfies the tested no-refit contract.”
  • Keep PX and UTC/data-span selectors explicitly invariant.
  • Require discriminating delay or phase tests before certifying a component.

The resulting converter:

  • converts coordinate epochs through Astropy’s TCB/TDB scales, including TDB0;
  • applies order-aware scaling to DM Taylor coefficients;
  • converts FD and FDJUMP coefficients under PINT’s fixed-frequency convention;
  • records converted, invariant, unsupported, and unaudited terms in a TCBTDBConversionReport;
  • remains permissive when it encounters unsupported model terms;
  • reports accepted=True only when the model lies within the tested no-refit surface;
  • preserves that acceptance assessment on repeated/no-op conversion calls.

The documentation and CLI now state the convention and acceptance contract explicitly. The changelog notes that converted epochs and DM values differ from legacy-IFTE output.

MetaPulsar also ingests native tempo2 par files, some of which cannot initially be parsed by PINT. Therefore this PR is not intended to replace MetaPulsar’s tempo2 conversion path. What we actually need longer-term is a corresponding tempo2 PR: one that provides the same auditable, permissive-conversion/strict-acceptance structure, but derives its scaling rules from tempo2’s own forward model and DILATEFREQ semantics. I plan to work on that or coordinate with Mike separately.

Thanks to @tcromartie for bringing it to my attention again yesterday during the DWG; it had been on my radar for months. I enjoyed the discussions!

Verification performed:

  • Full PINT suite before review fixes: 2,502 passed, 20 skipped, 18 xfailed.
  • Updated TCB/TDB suite: 21 passed.
  • Parameter and model-construction regressions: 201 passed, 2 skipped, 2 xfailed.
  • Formatting, diff checks, and lint checks pass.

@vhaasteren

Copy link
Copy Markdown
Member Author

Extra comment:

IFTE_K is still exported as an alias of TCB_TDB_K. Nothing in the repo imports it, the IFTE epoch origin (IFTE_MJD0) is already gone, and the alias is no longer the Irwin & Fukushima rate. I am inclined to remove IFTE_K and leave TCB_TDB_K / TCB_TDB_F as the public constants. Does anyone rely on from pint.models.tcb_conversion import IFTE_K?

@vhaasteren vhaasteren changed the title feat: updated TCB-->TDB conversion functionality feat: updated accuracy of TCB-->TDB conversion Sep 4, 2026
Astropy 5.0.5 TCB<->TDB conversions land within a few ULPs of the
two-part JD (~0.05 ns), which is still well below the 1 ns no-refit
bound but exceeded the 0.01 ns checks.
conda osx-64 downcasts the tdbld/Quantity/Horner path to float64
(about 10 ns over 1250 d). Compare converted F0/F1 against Astropy
Time intervals instead so the no-refit check stays sub-ns.
Multiplying F0 by K (~1+1.55e-8) rounds the correction into the last
bits of a factor near 1. On conda osx-64 that is a ~10 ns phase error
over 1250 d. Apply x + x*(K^n-1) with K^n-1 formed from L_B, and
evaluate spindown closure from the same increments.
# Conflicts:
#	CHANGELOG-unreleased.md
80-bit x87 longdouble does not recover erfa.ELB from 1-(1-ELB), so the
exact equality in test_k_power_minus_one failed on CI.
@vhaasteren
vhaasteren marked this pull request as draft September 17, 2026 06:52
The exponents were hard-coded to the undilated rule, but the flag that
sets them is the one on the TCB side of the conversion, where the
Einstein-rate divisor carries the full K rather than departing from 1 by
~5e-10. TEMPO2 defaults to DILATEFREQ Y and writes it into the TCB pars
it produces, and validate() coerced it to N before the converter could
see it, so the common case was off by K^2-1 = 3.1e-8 of the dispersion
delay (~3 ns at 1.4 GHz, ~40 ns at 400 MHz for DM=50) -- chromatic, so
no phase offset absorbs it.

validate() now records the flag in meta["tcb_source_dilatefreq"],
parameters declare their frequency power via tcb2tdb_freq_power, and a
dilated source leaves the frequency-dependent components unaudited,
since PINT evaluates undilated frequencies and cannot certify that
branch by closure.

Also states the no-refit contract explicitly -- residuals reproduced to
better than 1 ns with nothing refitted, up to the phase offset each
package fixes by its own convention -- and documents that TEMPO2's
UNITS TDB is currently Teph, 64.5 ns plus a 2.8e-18 rate away from
IAU 2006 TDB.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant