Discussion: NHARMS (PINT) vs NHARM (Tempo2), silent ELL1H harmonic-count mismatch #2030

Summary

For the MetaPulsar work I am doing cross-checks of (binary) models between PINT and tempo2. This one stumbled me a bit. PINT and Tempo2 use different par-file spellings for the same ELL1H / T2 Shapiro harmonic-count control:

There is no alias in either direction today. A shared .par that works in one package can be silently misinterpreted in the other.

Evidence (current trees)

Tempo2 (readParfile.C / initialise.C):

• Parses NHARM only (strcasecmp(str, "NHARM")).
• Short label is "NHARM".

PINT (binary_ell1.py):

• Parameter name is NHARMS, aliases=[].
• Docs already note: default in PINT is 7, in Tempo2 is 4.
• A line NHARM 7 produces: Unrecognized parfile line 'NHARM 7' and does not set NHARMS.

Observed residual impact (PINT-idealized TOAs → Tempo2 residuals, otherwise aligned conventions): ELL1H with H3+H4 and only NHARMS 7 in the par left Tempo2 at nharm=4 → ~5–6 ns RMS disagreement. Writing both NHARM 7 and NHARMS 7 brought Tempo2 RMS back under ~1 ns.

Why this is ugly

This is not a “MetaPulsar should dual-write” problem alone. Anyone who:

1. fits / writes an ELL1H H3+H4 model in PINT (emits NHARMS), then
2. evaluates or combines with Tempo2,

gets a different delay with no hard error in Tempo2 (unknown keyword → default 4). The reverse (NHARM from Tempo2/EPTA-style pars into PINT) is also ignored unless PINT’s floor happens to match the intended value.

Proposed direction (for discussion)

Prefer non-breaking interchange fixes over a rename:

1. PINT

   • Accept NHARM as an alias of NHARMS on read.
   • On write: emit NHARM for Tempo2-format pars (canonical Tempo2 spelling); consider emitting NHARM (or both) for interchange / PINT format after a deprecation window.
   • Keep the Python attribute NHARMS for API compatibility (optional later soft rename).

2. Tempo2 (separate upstream issue/PR)

   • Accept NHARMS as a synonym of NHARM in readParfile.C.

Canonical interchange name should be NHARM (Tempo2 / historical ELL1H spelling). PINT’s plural NHARMS is the outlier.

Alternatives considered

Ask

Is the preferred path:

1. PINT alias + Tempo2-format write of NHARM (recommended), and/or
2. a small Tempo2 synonym for NHARMS, and/or
3. a documented breaking rename?

Happy to open a PINT PR for (1) if that matches project preference.

Related

• Local motivation / parity suite: MetaPulsar cross-engine ELL1H round-trips (consistency-pint-tempo2 / alignment work).
• Related ELL1H Tempo2 parity: ell1h_shapiro="absorbed" (FW10 Eq. 28 vs Eq. 29).