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_windowseconds back), robust to queueing; - offset: for each sample, quality-weighted average of the last
offset_windowrate-corrected offsets, weightsexp(-(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.