Skip to content

ntpstats.estimators

Pluggable clock-offset estimators for benchmarking synchronisation algorithms.

An estimator turns noisy measurements into an estimate of the true offset (reference - local) at the measurement times::

class MyEstimator(Estimator):
    name = "mine"
    def fit(self, series):            # TimeSeries -> TimeSeries
        ...

register(MyEstimator())

Third-party packages can expose estimators through the entry-point group ntpstats.estimators (value: an :class:Estimator instance, class or factory); they are picked up by :func:available and ntpstats bench.

Multi-server estimators set multi = True and receive a list of series (one per server); they return one combined series.

Built-in reference algorithms

raw the measurements themselves kalman two-state Kalman filter (no delay information) kalman-dw Kalman filter with delay-weighted measurement noise rts-dw RTS smoother, delay weighted (offline optimum for the model) mindelay NTP clock filter: minimum delay of the last 8 samples (RFC 5905 s10) regression chrony-style weighted linear regression over a window sized by a runs test on the residuals feedforward RADclock-style: rate from long-baseline low-RTT packets, offset from a quality-weighted recent window hull Huygens-style: the max-margin line through the offset bounds (offset ± delay/2) of a sliding window ptp4l linuxptp-style slave: moving-median mean path delay and the PI (or linreg) servo, in closed loop sptp SPTP-style client: complete exchanges, path-delay outlier discard, PI servo rfc5905 (multi) clock filter + selection (intersection), cluster and combine algorithms of RFC 5905 s11 median (multi) median of the servers' clock-filter outputs kalman-combine (multi) ntpd-rs-style: per-source Kalman filters, interval intersection, inverse-variance combination ntpd, ntpd-rfc ntpd's clock discipline in closed loop, with the reference implementation's or the RFC 5905 appendix's constants lockclock J. Levine's NIST frequency-lock loop (J. Res. NIST 2020) levine-kalman LOCKCLOCK with Levine's scalar Kalman time estimate (PTTI 2011) (see :mod:ntpstats.disciplines)

regression(series, max_samples=64, min_samples=6, sigma=None)

Causal weighted linear regression per sample, chrony style.

Weights are 1 / (sigma^2 + q^2) with q the queueing error bound; the window shrinks (dropping the oldest half) while the residual signs fail a runs test, i.e. while a straight line no longer describes the recent phase (frequency change).

feedforward(series, rate_window=6 * 3600, offset_window=16, e_star=None)

Feed-forward estimator in the spirit of RADclock (Veitch, Ridoux et al.).

  • rate: slope between low-RTT packets separated by a long baseline (causal, up to rate_window seconds back), robust to queueing;
  • offset: for each sample, quality-weighted average of the last offset_window rate-corrected offsets, weights exp(-(q / E*)^2).

rfc5905_combine(series_list, nmin=1, maxclock=3, dispersion=0.001)

Selection, cluster and combine (RFC 5905 s11.2) over several servers.

At each epoch (times of the first server) the latest clock-filter output of every server gives an offset and a root distance lambda = delay/2 + dispersion + jitter. The intersection algorithm keeps the truechimers, the cluster algorithm prunes outliers by selection jitter down to maxclock survivors, and the survivors are combined weighted by 1/lambda.

convex_hull(series, samples=64, window=None)

Huygens-style estimator (Geng et al., NSDI 2018), for one server.

Every exchange bounds the true offset: θm − δ/2 ≤ θ ≤ θm + δ/2 (the error of a measurement is at most half its round trip). Over a sliding window of the last samples exchanges (or window seconds), the clock offset is taken as the straight line with the largest margin between those upper and lower bounds; the margin is equal on both sides because equal floor delays are assumed, as in the paper's SVM. The estimate at each exchange uses only that exchange and earlier ones.

kalman_combine(series_list, nmin=1, k_sigma=3.0)

Multi-server combination in the spirit of ntpd-rs (not its code).

Each source gets its own delay-weighted Kalman filter (offset and frequency with an uncertainty). At each epoch every source contributes the interval offset ± (k·σ + floor_delay/2): the filter's uncertainty plus the asymmetry no measurement can rule out. The largest set of intervals with a common point is kept (Marzullo intersection, as RFC 5905), and the survivors are averaged with inverse-variance weights.

ptp4l(series, delay_filter=10, servo='pi', servo_options=None)

A linuxptp-style slave: E2E delay mechanism with a moving-median delay filter and a servo.

Every Sync gives an offset mean_path_delay - (t2 - t1), where the mean path delay is the median of the last delay_filter Delay_Req exchanges (ptp4l's delay_filter moving_median, length 10); the servo (pi with linuxptp's default gains, or linreg) steers a clock with it, and the steered clock's correction is the estimate. On NTP-style series every sample is an exchange.

sptp(series, delay_filter=32, discard=3.0, servo='pi', servo_options=None)

An SPTP-style client (after Meta's Simple PTP): client-driven unicast exchanges, each giving all four timestamps at once.

Only complete exchanges are used. The mean path delay is the median of the last delay_filter exchanges; an exchange whose path delay exceeds that median by more than discard times the window's median absolute deviation is discarded (queueing outliers); the others give an offset mean_path_delay - (t2 - t1) that a servo (pi by default) tracks. A model of the approach, not of a particular release.