commkit 3.7.0__tar.gz → 3.7.1__tar.gz

{commkit-3.7.0 → commkit-3.7.1}/CHANGELOG.md

@@ -4,6 +4,27 @@ Notable changes to CommKit, newest first. Performance figures are from the refer
 
 ## [Unreleased]
 
+## [3.7.1] - 2026-11-10
+
+Gardner clock recovery no longer runs away when its loop is too wide: the integrator is bounded to plausible clock offsets, and slips are reported. The notebooks on clock recovery, direct and coherent detection and the ADC now introduce their topics with figures.
+
+### Added
+
+- `timing.Gardner(max_offset_ppm=1000.0)`: the largest clock offset the loop tracks. The loop's integrator is held within it.
+- A WARNING when Gardner clock recovery slips whole symbols (the timing moves by more than 0.75 symbol within `8 / (B·T)` symbols), after which output symbols no longer match the transmitted ones in order. A second WARNING when the estimated offset sits at `max_offset_ppm`.
+
+### Performance
+
+- Gardner clock recovery checks its trajectory for slips after the loop: 1.01 to 1.04 of the former time (paired runs, 2^17 symbols).
+
+### Fixed
+
+- A Gardner loop too wide for its detector's noise, such as the classical detector at `normalized_bandwidth=1e-2` on a 0.1-rolloff signal, no longer runs away in frequency without notice. Once it slipped, nothing pulled its integrator back, and it reached tens of thousands of ppm on a 50 ppm clock, with thousands of extra symbols in the corrected output. The bounded loop keeps returning to lock and reports the slips.
+
+### Development
+
+- Notebooks 12 (sampling-clock recovery), 22 (direct and self-coherent detection, now also coherent detection and its LO gain) and the skew and ADC sections of 10 explain their topics with figures: the drifting eye, how the Gardner detector tells early from late, loop bandwidth and cycle slips, PAM-4 eyes and sensitivity, thermal against shot noise, laser RIN, balanced photodiodes, quantization and jitter.
+
 ## [3.7.0] - 2026-11-10
 
 The receiver's analog front end and the detector, at absolute power. The ADC clock, its jitter and quantizer, IQ skew and the photodiode join the impairments, with Gardner clock recovery as the inverse of the clock; coherent and square-law detection turn received and LO powers into the noise they give. Closed-form AWGN error rates and information rates sit next to the measured ones. Blind decision-directed equalizers no longer lock falsely on unipolar PAM and dense QAM, because their input scaling hands the slicer the right gain.
@@ -503,7 +524,8 @@ See the [GitHub release](https://github.com/lokgar/commkit/releases/tag/v1.1.0)
 
 First release. See the [GitHub release](https://github.com/lokgar/commkit/releases/tag/v1.0.0).
 
-[Unreleased]: https://github.com/lokgar/commkit/compare/v3.7.0...HEAD
+[Unreleased]: https://github.com/lokgar/commkit/compare/v3.7.1...HEAD
+[3.7.1]: https://github.com/lokgar/commkit/compare/v3.7.0...v3.7.1
 [3.7.0]: https://github.com/lokgar/commkit/compare/v3.6.1...v3.7.0
 [3.6.1]: https://github.com/lokgar/commkit/compare/v3.6.0...v3.6.1
 [3.6.0]: https://github.com/lokgar/commkit/compare/v3.5.0...v3.6.0

{commkit-3.7.0 → commkit-3.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: commkit
-Version: 3.7.0
+Version: 3.7.1
 Summary: A Python library for high-performance digital communications research.
 Project-URL: Homepage, https://github.com/lokgar/commkit
 Project-URL: Repository, https://github.com/lokgar/commkit

{commkit-3.7.0 → commkit-3.7.1}/commkit/__init__.py

@@ -31,7 +31,7 @@ Matplotlib, change warning filters, or touch the GPU.
 import importlib
 from typing import Any
 
-__version__ = "3.7.0"
+__version__ = "3.7.1"
 
 from .backend import PrecisionWarning
 from .core import (

{commkit-3.7.0 → commkit-3.7.1}/commkit/timing/_numba_loops.py

@@ -111,9 +111,10 @@ def _clamp_step(step, sps):
 
 
 @_step
-def _track(x, c0, c1, pad, sps, p0, mu, beta, power, n_valid, pos, err):
+def _track(x, c0, c1, pad, sps, p0, mu, beta, nu_max, power, n_valid, pos, err):
     """One loop over channels ``c0 .. c1 - 1`` (their mean error drives it);
-    fills ``pos`` and ``err`` and returns the number of strobes."""
+    fills ``pos`` and ``err`` and returns the number of strobes.  The
+    integrator stays within ``±nu_max``."""
     nu = 0.0
     e_last = 0.0
     p = p0
@@ -131,14 +132,14 @@ def _track(x, c0, c1, pad, sps, p0, mu, beta, power, n_valid, pos, err):
         err[k] = e
         k += 1
         step = _clamp_step(sps * (1.0 + nu + mu * e_last), sps)
-        nu += beta * e_last
+        nu = min(max(nu + beta * e_last, -nu_max), nu_max)
         e_last = e
         p += step
     return k
 
 
 @numba.njit(cache=True, fastmath=True, nogil=True, parallel=True)
-def gardner_loop(x, pad, sps, p0, mu, beta, power, joint, n_valid, num_out):
+def gardner_loop(x, pad, sps, p0, mu, beta, nu_max, power, joint, n_valid, num_out):
     """Track the symbol strobes of every channel (or one joint loop).
 
     Parameters
@@ -155,6 +156,9 @@ def gardner_loop(x, pad, sps, p0, mu, beta, power, joint, n_valid, num_out):
     mu, beta : numpy.ndarray
         Proportional and integral gains per row, float64: the strobe spacing
         is ``sps · (1 + ν + μ·e)`` and ``ν += β·e``.
+    nu_max : float
+        Bound of the integrator ``|ν|``, the largest clock offset tracked
+        (fraction, not ppm).
     power, joint : bool
         Power detector; one loop driven by the mean error of all channels.
     n_valid : int
@@ -180,6 +184,18 @@ def gardner_loop(x, pad, sps, p0, mu, beta, power, joint, n_valid, num_out):
         c0 = 0 if joint else r
         c1 = C if joint else r + 1
         count[r] = _track(
-            x, c0, c1, pad, sps, p0[r], mu[r], beta[r], power, n_valid, pos[r], err[r]
+            x,
+            c0,
+            c1,
+            pad,
+            sps,
+            p0[r],
+            mu[r],
+            beta[r],
+            nu_max,
+            power,
+            n_valid,
+            pos[r],
+            err[r],
         )
     return pos, err, count

{commkit-3.7.0 → commkit-3.7.1}/commkit/timing/clock_recovery.py

@@ -40,6 +40,12 @@ _CAL_SYMBOLS = 2048
 # Below this first-harmonic amplitude of the S-curve (unit-power input) the
 # detector sees no clock tone.
 _MIN_CURVE_AMPLITUDE = 1e-3
+# Cycle-slip check: the timing may not move by more than _SLIP_THRESHOLD
+# symbol periods, beyond the record's mean drift, within _SLIP_WINDOW loop
+# time constants 1/(B·T).  The loop's own jitter stays below 0.5 symbol over
+# that window up to the bandwidths where slips begin; a slip moves it by 1.
+_SLIP_WINDOW = 8.0
+_SLIP_THRESHOLD = 0.75
 
 
 def _get_numba_gardner() -> Any:
@@ -74,8 +80,10 @@ class Gardner:
         ``β = 4(BT)² / K_d``, with the detector gain ``K_d`` measured on the
         input (see Notes).  Used when ``proportional_gain`` is not given.
         The detector's self-noise sets the timing jitter: 0.01 symbol rms at
-        ``1e-3`` for 16-QAM, 0.001 at ``1e-4``; at ``1e-2`` a 0.1-rolloff
-        signal slips whole symbols.
+        ``1e-3`` for 16-QAM (classical detector, rolloff 0.1), 0.006 at
+        ``1e-4``.  Too wide a loop slips whole symbols: the classical
+        detector at a rolloff of 0.1 from ``1e-2`` on, the power detector
+        at 0.1 from ``2e-2`` and at 0.5 from ``3e-3`` (16-QAM, 20 dB).
     proportional_gain : float, optional
         Raw proportional gain ``μ`` on the detector output of the input
         scaled to unit power; overrides ``normalized_bandwidth``.
@@ -83,6 +91,12 @@ class Gardner:
         Raw integral gain ``β``; requires ``proportional_gain``.  Defaults
         to 0 (a first-order loop, which keeps a timing lag ``ε / μK_d``
         under a clock offset) with ``proportional_gain``.
+    max_offset_ppm : float, default 1000.0
+        Largest clock offset the loop tracks, in ppm, in ``(0, 90000)``:
+        the integrator ``ν`` is held within ``±max_offset_ppm · 1e-6``.
+        Crystal clocks are within about 100 ppm.  The bound keeps a loop
+        that has lost lock from wandering off in frequency, which it
+        otherwise does without limit (see Notes).
     joint_channels : bool, default False
         MIMO: one loop driven by the mean detector output of all channels,
         for channels sampled by one clock.
@@ -109,6 +123,19 @@ class Gardner:
     pulse) while the power detector's stays at 0.34.  The strobe spacing is
     held within ±10 % of ``sps``.
 
+    A loop that slips leaves the S-curve's stable point, and while its
+    timing runs through the symbols the mean detector output is zero:
+    nothing pulls the integrator back, and its noise walks it away.
+    Unbounded, a classical loop at ``B·T = 1e-2`` on a 0.1-rolloff signal
+    reached tens of thousands of ppm on a 50 ppm clock; held within
+    ``max_offset_ppm`` it keeps returning to lock.  Two checks log a WARNING after the loop: the
+    timing moving by more than 0.75 symbol within ``8 / (B·T)`` symbols,
+    beyond the record's mean drift (a cycle slip, after which symbol ``k``
+    of the output is no longer the ``k``-th transmitted one), and an
+    estimated offset within 5 % of ``max_offset_ppm`` (a larger offset,
+    which the proportional path follows only with a static timing lag, or
+    a loop that lost lock).  ``B·T`` is ``μ K_d / 4`` for raw gains.
+
     Numba-compiled on the CPU; GPU input makes one host round trip.
 
     References
@@ -120,6 +147,7 @@ class Gardner:
     normalized_bandwidth: float = 1e-3
     proportional_gain: float | None = None
     integral_gain: float | None = None
+    max_offset_ppm: float = 1000.0
     joint_channels: bool = False
     method: Literal["classical", "power"] = "classical"
 
@@ -130,6 +158,11 @@ class Gardner:
                 f"Gardner: normalized_bandwidth must be in (0, 0.5) (a fraction "
                 f"of the symbol rate), got {bt}."
             )
+        if not (0.0 < self.max_offset_ppm < 9e4):
+            raise ValueError(
+                "Gardner: max_offset_ppm must be in (0, 90000), got "
+                f"{self.max_offset_ppm}."
+            )
         if self.integral_gain is not None and self.proportional_gain is None:
             raise ValueError("Gardner: integral_gain requires proportional_gain.")
         for name in ("proportional_gain", "integral_gain"):
@@ -224,6 +257,7 @@ def _track(
         pad + tau0 * sps,
         np.ascontiguousarray(gains[:, 0]),
         np.ascontiguousarray(gains[:, 1]),
+        how.max_offset_ppm * 1e-6,
         power,
         rows != C,
         n,
@@ -232,6 +266,7 @@ def _track(
     k = int(count.min())
     pos = pos[:, :k] - pad
     err = err[:, :k]
+    _check_lock(pos / sps - np.arange(k), gains[:, 0] * kd / 4.0, how)
     if rows != C:
         pos = np.repeat(pos, C, axis=0)
         err = np.repeat(err, C, axis=0)
@@ -239,6 +274,47 @@ def _track(
     return pos, kd, err
 
 
+def _first_slip(trajectory: np.ndarray, bandwidth: np.ndarray) -> np.ndarray:
+    """Per row, the first symbol where the timing moves by more than
+    _SLIP_THRESHOLD within _SLIP_WINDOW / bandwidth symbols beyond the
+    row's median drift over that window; -1 where it never does."""
+    k = trajectory.shape[-1]
+    first = np.full(trajectory.shape[0], -1, dtype=np.int64)
+    for r, bt in enumerate(bandwidth):
+        if not bt > 0.0:
+            continue
+        span = int(max(64.0, _SLIP_WINDOW / bt))
+        if span >= k:
+            continue
+        moved = trajectory[r, span:] - trajectory[r, :-span]
+        bad = np.abs(moved - np.median(moved)) > _SLIP_THRESHOLD
+        if bad.any():
+            first[r] = int(np.argmax(bad))
+    return first
+
+
+def _check_lock(trajectory: np.ndarray, bandwidth: np.ndarray, how: Gardner) -> None:
+    """Log a WARNING for cycle slips and for an offset at the loop's bound."""
+    first = _first_slip(trajectory, bandwidth)
+    if np.any(first >= 0):
+        logger.warning(
+            "Gardner clock recovery slipped whole symbols (first near symbol "
+            "%d): after a slip, output symbols no longer match the transmitted "
+            "ones in order.  Use a smaller normalized_bandwidth (B·T = %s).",
+            int(first[first >= 0].min()),
+            ", ".join(f"{bt:.1e}" for bt in np.unique(bandwidth)),
+        )
+    ppm = _offset_ppm(trajectory)
+    if np.any(np.abs(ppm) > 0.95 * how.max_offset_ppm):
+        logger.warning(
+            "Gardner clock recovery: the offset %s ppm is at the loop's bound "
+            "max_offset_ppm=%g: the loop lost lock, or the clock is further off and "
+            "the timing lags; raise max_offset_ppm.",
+            np.array2string(ppm, precision=1),
+            how.max_offset_ppm,
+        )
+
+
 def _offset_ppm(trajectory: np.ndarray) -> np.ndarray:
     """Least-squares slope of the trajectory over its last three quarters,
     in ppm."""