bounds

Validate clock-error bounds (uncertainty windows) against a reference.

Services such as AWS ClockBound, Meta's fbclock or a TrueTime-style API report a window [earliest, latest] that should contain true time. Given a better reference for the same host (a PTP/PPS comparison, or NTS measurements when the bound is much wider than their delay), this module checks how often the window really contains true time, and how tight it is.

Inputs are :class:TimeSeries with offset = window centre - local clock (reference - local convention) and an extra["bound"] half-width:

• ClockBound example output, one line per call (... true time was somewhere within A and B seconds since Jan 1 1970 ...). ClockBound builds its window around the system clock reading, so the centre is the local time and the offset is 0.
• a CSV with earliest and latest columns (POSIX seconds) and optionally unix_time, the local clock reading taken together with the window (needed for windows that are not centred on the system clock, e.g. fbclock, which is PHC-based) and status.

parse_bounds(lines, name='bounds')

ClockBound example lines, or a CSV with earliest/latest columns.

validate(bounds, reference, max_gap=None, reference_uncertainty=None)

Check how often true time (from reference) lies inside the windows.

reference offsets (reference - local) are interpolated linearly to each window time, only between reference samples closer than max_gap seconds (default: 3 median reference intervals). The reference's own uncertainty is reference_uncertainty if given, else half its round-trip delay column when present, else 0. Each window is then:

• inside when |error| + u <= bound,
• violated when |error| - u > bound,
• indeterminate otherwise (the reference is not good enough to tell),

where error is true time minus the window centre.