ntpstats 2.5.0__py3-none-any.whl

ntpstats/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2012-2026 Thiago de Freitas <thiagodefreitas@gmail.com>
+"""ntpstats: NTP / network-time offset and stability analysis toolkit."""
+
+__version__ = "2.5.0"
+__author__ = "Thiago de Freitas"
+__email__ = "thiagodefreitas@gmail.com"
+__license__ = "MIT"
+
+from .parsers import load, load_one  # noqa: E402,F401
+from .series import TimeSeries  # noqa: E402,F401

ntpstats/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2012-2026 Thiago de Freitas <thiagodefreitas@gmail.com>
+import sys
+
+from .cli import main
+
+sys.exit(main())

ntpstats/analysis.py

@@ -0,0 +1,164 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2012-2026 Thiago de Freitas <thiagodefreitas@gmail.com>
+"""Descriptive statistics, detrending and outlier handling for offset series."""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+import numpy as np
+
+from .series import TimeSeries
+
+PERCENTILES = (1, 5, 50, 95, 99)
+
+
+def detrend(t: np.ndarray, x: np.ndarray, kind: Optional[str] = "linear") -> np.ndarray:
+    """Remove a least-squares polynomial trend.
+
+    ``linear`` removes a constant frequency offset; ``quadratic`` also
+    removes a linear frequency drift (aging). Time is centred first so the
+    fit stays well conditioned with POSIX timestamps.
+    """
+    if not kind or kind == "none":
+        return np.asarray(x, dtype=float)
+    deg = {"mean": 0, "linear": 1, "quadratic": 2}[kind]
+    t = np.asarray(t, dtype=float)
+    x = np.asarray(x, dtype=float)
+    if t.size <= deg:
+        return x - np.mean(x)
+    tc = t - t.mean()
+    coef = np.polyfit(tc, x, deg)
+    return x - np.polyval(coef, tc)
+
+
+def linear_fit(t, x):
+    """Least-squares slope (s/s) and intercept of offset vs time."""
+    t = np.asarray(t, dtype=float)
+    tc = t - t.mean()
+    slope, icpt = np.polyfit(tc, np.asarray(x, dtype=float), 1)
+    return float(slope), float(icpt)
+
+
+def theil_sen_slope(t, x, max_pairs: int = 200_000, seed: int = 0) -> float:
+    """Robust (median of pairwise slopes) frequency estimate, s/s.
+
+    Insensitive to up to ~29 % outliers, unlike least squares. Pairs are
+    randomly subsampled for long series.
+    """
+    t = np.asarray(t, dtype=float)
+    x = np.asarray(x, dtype=float)
+    n = t.size
+    if n < 2:
+        return float("nan")
+    if n * (n - 1) // 2 <= max_pairs:
+        i, j = np.triu_indices(n, 1)
+    else:
+        rng = np.random.default_rng(seed)
+        i = rng.integers(0, n, max_pairs)
+        j = rng.integers(0, n, max_pairs)
+    dt = t[j] - t[i]
+    ok = dt != 0
+    return float(np.median((x[j] - x[i])[ok] / dt[ok]))
+
+
+def mad_outliers(x: np.ndarray, k: float = 5.0, t: Optional[np.ndarray] = None) -> np.ndarray:
+    """Boolean mask of outliers: |x - median| > k * 1.4826 * MAD.
+
+    If ``t`` is given the test is applied to linearly detrended data so a
+    frequency offset is not mistaken for outliers.
+    """
+    x = np.asarray(x, dtype=float)
+    r = detrend(t, x, "linear") if t is not None and x.size > 2 else x
+    med = np.median(r)
+    mad = 1.4826 * np.median(np.abs(r - med))
+    if mad == 0:
+        return np.zeros(x.shape, dtype=bool)
+    return np.abs(r - med) > k * mad
+
+
+def remove_outliers(series: TimeSeries, k: float = 5.0) -> TimeSeries:
+    mask = mad_outliers(series.offset, k, series.t)
+    out = series.select(~mask)
+    out.meta["outliers_removed"] = int(mask.sum())
+    return out
+
+
+def summary(series: TimeSeries) -> Dict[str, object]:
+    """Summary statistics in the spirit of NTPsec's ``ntpviz`` report."""
+    x = series.offset
+    n = len(series)
+    out: Dict[str, object] = {
+        "name": series.name,
+        "format": series.source_format,
+        "samples": n,
+    }
+    if n == 0:
+        return out
+    out.update(
+        {
+            "start": float(series.t[0]),
+            "end": float(series.t[-1]),
+            "span_s": series.span,
+            "mean": float(np.mean(x)),
+            "std": float(np.std(x, ddof=1)) if n > 1 else 0.0,
+            "rms": float(np.sqrt(np.mean(x * x))),
+            "min": float(np.min(x)),
+            "max": float(np.max(x)),
+            "mean_abs": float(np.mean(np.abs(x))),
+        }
+    )
+    pct = np.percentile(x, PERCENTILES)
+    out["percentiles"] = {f"p{p}": float(v) for p, v in zip(PERCENTILES, pct)}
+    out["range_90"] = float(pct[3] - pct[1])  # p95 - p5
+    out["range_98"] = float(pct[4] - pct[0])  # p99 - p1
+    if n > 2:
+        out["median_interval_s"] = series.median_interval()
+        out["regularity"] = series.regularity()
+        slope, _ = linear_fit(series.t, x)
+        out["offset_slope_ppm"] = slope * 1e6
+        out["offset_slope_robust_ppm"] = theil_sen_slope(series.t, x) * 1e6
+        resid = detrend(series.t, x, "linear")
+        out["residual_rms"] = float(np.sqrt(np.mean(resid ** 2)))
+        out["outliers_5mad"] = int(mad_outliers(x, 5.0, series.t).sum())
+        d = series.intervals()
+        med = series.median_interval()
+        out["gaps"] = int(np.sum(d > 3 * med))
+        out["longest_gap_s"] = float(d.max())
+    for key, col in series.extra.items():
+        if col.size and np.isfinite(col).any():
+            out[f"{key}_median"] = float(np.nanmedian(col))
+    return out
+
+
+def format_seconds(v: Optional[float]) -> str:
+    """Pretty-print a time value with an SI prefix (e.g. 12.3 µs)."""
+    if v is None or not np.isfinite(v):
+        return "n/a"
+    a = abs(v)
+    for scale, unit in ((1, "s"), (1e-3, "ms"), (1e-6, "µs"), (1e-9, "ns")):
+        if a >= scale:
+            return f"{v / scale:.3g} {unit}"
+    return f"{v / 1e-12:.3g} ps"
+
+
+def compare(estimate: TimeSeries, reference: TimeSeries) -> Dict[str, float]:
+    """Score ``estimate`` against a ``reference`` (e.g. simulated truth, a
+    GNSS/PPS-disciplined clock or a better server).
+
+    The reference is linearly interpolated onto the estimate's times over
+    their common span. Returns error statistics of ``estimate - reference``.
+    """
+    r = reference.sorted()
+    e = estimate.sorted().between(r.t[0], r.t[-1])
+    if len(e) < 2:
+        raise ValueError("series do not overlap")
+    err = e.offset - np.interp(e.t, r.t, r.offset)
+    return {
+        "samples": int(err.size),
+        "bias": float(np.mean(err)),
+        "rms": float(np.sqrt(np.mean(err ** 2))),
+        "std": float(np.std(err)),
+        "max_abs": float(np.max(np.abs(err))),
+        "p95_abs": float(np.percentile(np.abs(err), 95)),
+    }

ntpstats/bench.py

@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2012-2026 Thiago de Freitas <thiagodefreitas@gmail.com>
+"""Benchmark synchronisation estimators against simulated ground truth.
+
+    rows = run_bench(load_scenarios(["internet", "examples/scenarios/route-change.toml"]),
+                     estimators=["kalman-dw", "regression", "rfc5905"], seeds=range(1, 6))
+    table = summarize(rows)
+
+Scenarios are preset names (:data:`ntpstats.simulate.PRESETS`) or TOML/JSON
+files (see :func:`ntpstats.simulate.scenario_from_dict`). Single-server
+estimators are scored on the first server; multi-server estimators get all.
+
+Metrics of the estimation error ``e = estimate - truth``: RMS, bias (mean),
+p95 and max of |e|, MTIE of e over 1 h windows, and wall-clock runtime.
+The first ``warmup`` seconds (default 30 min) are excluded, as usual when
+comparing synchronisation algorithms, so start-up transients do not dominate.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+import os
+import time
+from dataclasses import replace
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+import numpy as np
+
+from . import estimators as est_mod
+from .simulate import PRESETS, Scenario, scenario_from_dict, simulate_multi
+
+METRICS = ("rms", "bias", "p95_abs", "max_abs", "mtie_1h", "runtime_s")
+
+
+def _load_file(path: str) -> dict:
+    with open(path, "rb") as fh:
+        raw = fh.read()
+    if path.endswith(".json"):
+        return json.loads(raw)
+    import importlib
+
+    try:
+        toml: Any = importlib.import_module("tomllib")  # Python 3.11+
+    except ModuleNotFoundError:  # pragma: no cover
+        try:
+            toml = importlib.import_module("tomli")
+        except ModuleNotFoundError as exc:
+            raise SystemExit("TOML scenarios need Python 3.11+ or `pip install tomli`") from exc
+    return toml.loads(raw.decode("utf-8"))
+
+
+def load_scenarios(specs: Iterable[str]) -> List[Tuple[str, Scenario]]:
+    out = []
+    for spec in specs:
+        if spec in PRESETS:
+            out.append((spec, replace(PRESETS[spec], name=spec)))
+        elif os.path.exists(spec):
+            d = _load_file(spec)
+            name = d.get("name") or os.path.splitext(os.path.basename(spec))[0]
+            out.append((name, scenario_from_dict(dict(d, name=name))))
+        else:
+            raise ValueError(f"unknown scenario {spec!r} (presets: {', '.join(PRESETS)})")
+    return out
+
+
+def _mtie(t: np.ndarray, e: np.ndarray, window: float) -> float:
+    if t.size < 2:
+        return float("nan")
+    j = np.searchsorted(t, t + window, side="right")
+    best = 0.0
+    for i in range(t.size):
+        seg = e[i: max(j[i], i + 1)]
+        best = max(best, float(seg.max() - seg.min()))
+        if j[i] >= t.size:
+            break
+    return best
+
+
+def score(estimate, truth, warmup: float = 0.0) -> dict:
+    t = estimate.t
+    ok = (t >= truth.t[0] + warmup) & (t <= truth.t[-1]) & np.isfinite(estimate.offset)
+    t = t[ok]
+    e = estimate.offset[ok] - np.interp(t, truth.t, truth.offset)
+    if e.size == 0:
+        return {k: float("nan") for k in METRICS[:-1]}
+    return {
+        "rms": float(np.sqrt(np.mean(e * e))),
+        "bias": float(np.mean(e)),
+        "p95_abs": float(np.percentile(np.abs(e), 95)),
+        "max_abs": float(np.max(np.abs(e))),
+        "mtie_1h": _mtie(t, e, 3600.0),
+    }
+
+
+def run_bench(scenarios: Sequence[Tuple[str, Scenario]], estimators: Optional[Sequence[str]] = None,
+              seeds: Iterable[int] = (1, 2, 3), duration: Optional[float] = None, progress=None,
+              warmup: float = 1800.0) -> List[dict]:
+    names = list(estimators) if estimators else sorted(est_mod.available())
+    ests = [est_mod.get(n) for n in names]
+    rows = []
+    for sc_name, sc in scenarios:
+        for seed in seeds:
+            s2 = replace(sc, seed=int(seed))
+            if duration:
+                s2 = replace(s2, duration=float(duration))
+            meas, truth = simulate_multi(s2, name=sc_name)
+            for e in ests:
+                if e.multi is False and not meas:
+                    continue
+                t0 = time.perf_counter()
+                try:
+                    out = est_mod.run(e, meas)
+                    m = score(out, truth, warmup)
+                except Exception as exc:  # a failing plugin must not abort the benchmark
+                    m = {k: float("nan") for k in METRICS[:-1]}
+                    m["error"] = f"{type(exc).__name__}: {exc}"
+                m["runtime_s"] = time.perf_counter() - t0
+                row = {"scenario": sc_name, "seed": int(seed), "estimator": e.name, "multi": e.multi,
+                       "servers": len(meas), **m}
+                rows.append(row)
+                if progress:
+                    progress(row)
+    return rows
+
+
+def summarize(rows: Sequence[dict]) -> List[dict]:
+    """Mean and standard deviation of each metric over seeds."""
+    groups: Dict[tuple, List[dict]] = {}
+    for r in rows:
+        groups.setdefault((r["scenario"], r["estimator"]), []).append(r)
+    out = []
+    for (sc, est), rs in groups.items():
+        d = {"scenario": sc, "estimator": est, "runs": len(rs)}
+        for k in METRICS:
+            v = np.array([r[k] for r in rs], dtype=float)
+            d[k] = float(np.nanmean(v)) if np.isfinite(v).any() else float("nan")
+            d[k + "_std"] = float(np.nanstd(v)) if np.isfinite(v).sum() > 1 else 0.0
+        out.append(d)
+    out.sort(key=lambda d: (d["scenario"], d["rms"] if np.isfinite(d["rms"]) else np.inf))
+    return out
+
+
+def to_csv(rows: Sequence[dict]) -> str:
+    if not rows:
+        return ""
+    keys = list(rows[0].keys())
+    for r in rows:
+        for k in r:
+            if k not in keys:
+                keys.append(k)
+    buf = io.StringIO()
+    w = csv.DictWriter(buf, fieldnames=keys)
+    w.writeheader()
+    w.writerows(rows)
+    return buf.getvalue()