holdover-test (scenario kind)

Scenario kind of the engine v0.38.0, family Clocks, timing and holdover. Advisory: analysis output from a research and engineering tool, not type-approved navigation equipment and not a safety-of-life service. Every label here is the engine's or the verification matrix's; a kind is MODELLED unless the matrix says otherwise (how a label is earned: the README's Evidence section).

What it does#

MODELLED holdover test of a timing system, scored from a time-error record the OPERATOR supplies (a linuxptp ptp4l, phc2sys or ts2phc log, a chrony tracking or statistics log, a TICC, TimeLab or RINEX clock log, or time_s,time_error_ns pairs). The test has four steps and Kshana performs none of them: a locked BASELINE, GNSS REMOVED by the operator (the antenna cable or the simulator output; Kshana transmits and drives nothing) at a stated time, HOLDOVER on the system's own oscillator, and RECOVERY after the operator restores GNSS at a second stated time. The record is split at those two times. Baseline: time-error statistics and the ITU-T masks written for a locked clock. Holdover: statistics, the fractional frequency offset the system held (a least-squares line), the masks written for holdover or an autonomous clock, the ePRTC-A holdover envelope from the stated locked duration, and the time to exceed each time-error budget. Recovery: whether and when |TE| came inside a stated band and stayed there, the peak and the largest step. Every limit is transcribed from a public ITU-T table (the telecom-timing masks); the words are 'measured against the mask', and the two times are the operator's statement, not verified. A record too short for a mask is INCOMPLETE, never extrapolated. See docs/TIMING-HIL.md.

One run of scenarios/holdover-test-ptp4l.toml summarises as: holdover-test: holdover 1795 s, max|TE| 59.0 ns; prtc-a PASS, eprtc-a-holdover FAIL; recovered 0 s after GNSS returned (MODELLED, measured against the mask)

Inputs#

From the schema (kshana kinds --json):

• Required fields: test, series
• Optional fields: masks, budgets

The example scenarios/holdover-test-ptp4l.toml sets, among others:

Run it#

kshana scenarios/holdover-test-ptp4l.toml

2 bundled scenarios use this kind; the others are in scenarios/.

What it gives#

The scalar results of that run, with the units the engine states:

Result label (the engine's): MODELLED — a holdover test scored from a time-error record the operator supplied. Every limit is transcribed from the named public ITU-T Recommendation and the result is measured against the mask; it says nothing about whether any clock or system meets a Recommendation, and nobody has rated or appro

Evidence#

MODELLED: the verification matrix rows that name this kind.

• MODELLED The holdover-test kind: a time-error record (a linuxptp, chrony, TICC, TimeLab or RINEX clock log, or time_s,time_error_ns pairs) is split at the two times the operator states for GNSS removal and restoration into a baseline, a holdover a

The rows the run itself exercised, with the oracle the matrix gives each (the public sources are named there):

• MODELLED Deterministic, scenario-hashed, SBOM + cross-platform golden gates. Oracle (ExternalDataset): SBOM conformance to the official CycloneDX 1.5 JSON Schema (+ valid SPDX identifiers) — an external published standard, zero validation errors over the full dependency graph; the FoM-determinism / byte-reproducibility part remains a pinned self-consistency check, so the row stays MODELLED
• VALIDATED The maximum time interval error and time deviation the telecom-timing scenario kind reports, on a telecom-scale holdover record: an O(n) monotonic-queue slidi. Oracle (ExternalDataset): allantools 2024.06 — an independent third-party frequency-stability library — mtie() and tdev() on tests/fixtures/telecom_timing/holdover_te_series.csv, the series parsed from the same 17-significant-figure text on both sides; the reference records the series' SHA-256 and is regenerable offline via tests/fixtures/telecom_timing/generate_telecom_timing_reference.py. Validates the ESTIMATORS on this record, not the syn
• MODELLED Transcribed limits of ITU-T G.8272 (07/2025) PRTC-A/B, G.8272.1 (2024) Amd. 1 (07/2025) ePRTC locked and ePRTC-A holdover (including the Table 3 time-error enve. Oracle (InternalConsistency): Transcription of the named Recommendations (freely downloadable from itu.int), each limit carrying its table or clause, listed with every unconfirmed or unimplemented item in docs/TELECOM-TIMING.md; the breakpoint-continuity identities the tables imply are checked in the tests. A standards transcription with internal consistency checks, not a conformance test and not an external validation. 0.30 round 2 (pre-register
• MODELLED The holdover-test kind: a time-error record (a linuxptp, chrony, TICC, TimeLab or RINEX clock log, or time_s,time_error_ns pairs) is split at the two times th. Oracle (InternalConsistency): Hand computation on records built from formulas whose slope, step, extremum and recovery time are known before the run (the tests state them), and the masks, envelope and budgets of the telecom-timing rows above. No laboratory measurement of a real holdover was scored and no external oracle was compared, so the kind makes no claim about any clock or system; a timing-lab partner is needed before any per-clock-class fi

Limitations#

What the run's own report says is not modelled or not validated:

• MODELLED — a holdover test scored from a time-error record the operator supplied. Every limit is transcribed from the named public ITU-T Recommendation and the result is measured against the mask; it says nothing about whether any clock or system meets a Recommendation, and nobody has rated or approved it. The times at which GNSS was removed and restored are the operator's statement and are not verified. Advisory sof (result label)
• MODELLED holdover test of a timing system, scored from a time-error record the OPERATOR supplies (a linuxptp ptp4l, phc2sys or ts2phc log, a chrony tracking or statistics log, a TICC, TimeLab or RINEX clock log, or time_s,time_error_ns pairs). (kind catalogue (kshana kinds --json))
• Reproducibility & software assurance is MODELLED, not validated: a sub-claim is externally checked, but the whole capability composes modelled pieces, so the capability stays Modelled. (verification matrix (docs/MODELLED-RATIONALE.md))
• ITU-T telecom synchronisation masks with PASS/FAIL and margin is MODELLED, not validated: checked against its own closed-form / analytic identity — catches transcription and coefficient errors, but is not an external oracle. (verification matrix (docs/MODELLED-RATIONALE.md))
• Holdover test scored from an operator-supplied time-error record is MODELLED, not validated: checked against its own closed-form / analytic identity — catches transcription and coefficient errors, but is not an external oracle. (verification matrix (docs/MODELLED-RATIONALE.md))

See also#

• Family page: Clocks, timing and holdover
• All kinds: KINDS.md
• Topic page: TIMING-HIL.md
• Topic page: HARDWARE-SAFETY.md