commkit 1.0.0__py3-none-any.whl

commkit/_cuda/src/cs_block.cu

@@ -0,0 +1,119 @@
+// Per-symbol cycle-slip correction for one block_lms equalizer block.
+//
+// Faithful port of the Numba kernel `cs_block` (equalization.py): for each
+// symbol, predict the expected phase from an online OLS regression over the
+// last H corrected phases (relative coordinates, closed-form Sx/Sxx), snap
+// the BPS phase by the nearest integer multiple of `quantum` when |diff|
+// exceeds `threshold`, then push the corrected phase into the per-channel
+// circular history using the O(1) rolling-sum identities:
+//
+//   full buffer: Sxy_new = Sxy_old - Sy_old + y_old + (H-1) * y_new
+//                Sy_new  = Sy_old - y_old + y_new
+//   filling:     Sxy += n * y_new ; Sy += y_new
+//
+// Within a channel the recursion is strictly sequential; channels are
+// independent. Total work is C*B trivial scalar iterations per launch, so
+// the kernel runs as a single block with one thread per channel - the goal
+// is not throughput but keeping the block loop free of host synchronization
+// (it replaces a per-block D2H -> CPU Numba -> H2D round trip).
+//
+// Layout contract (enforced by the Python wrapper):
+//   phi_blk    (C, B) float64 - BPS phase before correction (input)
+//   phi_corr   (C, B) float64 - corrected phase (output)
+//   cs_buf_y   (C, H) float64 - circular buffer of past corrected phases
+//   cs_buf_ptr (C,)   int64   - write pointer (monotonically increasing)
+//   cs_buf_n   (C,)   int64   - number of valid entries (<= H)
+//   cs_stats   (C, 4) float64 - [0]=Sy, [1]=Sxy (relative coords); [2..3] unused
+//
+// Launch contract: grid = (1, 1, 1), block = (C, 1, 1), C <= 1024.
+// All arithmetic is float64, matching the Numba kernel - the GeForce FP64
+// throughput cliff is irrelevant at C*B ~ 512 sequential iterations.
+
+__global__ void cs_block(const double* __restrict__ phi_blk,
+                         double* __restrict__ phi_corr,
+                         double* cs_buf_y,
+                         long long* cs_buf_ptr,
+                         long long* cs_buf_n,
+                         double* cs_stats,
+                         const double quantum,
+                         const double threshold,
+                         const int cs_H,
+                         const int B) {
+    const int ci = threadIdx.x;  // one thread per channel; blockDim.x == C
+
+    const double H_f = static_cast<double>(cs_H);
+    const double Sx_full = H_f * (H_f - 1.0) / 2.0;
+    const double Sxx_full = H_f * (H_f - 1.0) * (2.0 * H_f - 1.0) / 6.0;
+    const double denom_full = H_f * Sxx_full - Sx_full * Sx_full;
+
+    // Channel-local state in registers; written back once after the loop.
+    long long n_b = cs_buf_n[ci];
+    long long ptr = cs_buf_ptr[ci];
+    double sy = cs_stats[ci * 4 + 0];
+    double sxy = cs_stats[ci * 4 + 1];
+    double* buf_y = cs_buf_y + static_cast<long long>(ci) * cs_H;
+    const double* phi_in = phi_blk + static_cast<long long>(ci) * B;
+    double* phi_out = phi_corr + static_cast<long long>(ci) * B;
+
+    for (int i = 0; i < B; ++i) {
+        double y_b = phi_in[i];
+        double phi_expected;
+
+        if (n_b == 0) {
+            phi_expected = y_b;
+        } else if (n_b < 10) {
+            const long long last_pos = (ptr - 1 + cs_H) % cs_H;
+            phi_expected = buf_y[last_pos];
+        } else {
+            const double n_f = static_cast<double>(n_b);
+            double Sx_c, denom;
+            if (n_b < cs_H) {
+                Sx_c = n_f * (n_f - 1.0) / 2.0;
+                const double Sxx_c = n_f * (n_f - 1.0) * (2.0 * n_f - 1.0) / 6.0;
+                denom = n_f * Sxx_c - Sx_c * Sx_c;
+            } else {
+                Sx_c = Sx_full;
+                denom = denom_full;
+            }
+            double slope, intercept;
+            if (fabs(denom) > 1e-30) {
+                slope = (n_f * sxy - Sx_c * sy) / denom;
+                intercept = (sy - slope * Sx_c) / n_f;
+            } else {
+                slope = 0.0;
+                intercept = sy / n_f;
+            }
+            phi_expected = slope * n_f + intercept;
+        }
+
+        const double diff = y_b - phi_expected;
+        // llrint = round-half-even, matching Python round() in the Numba kernel.
+        const long long k_slip = llrint(diff / quantum);
+        if (fabs(diff) > threshold && k_slip != 0) {
+            y_b -= static_cast<double>(k_slip) * quantum;
+        }
+        phi_out[i] = y_b;
+
+        // Update circular buffer - relative coords, only y needed.
+        const long long write_pos = ptr % cs_H;
+        if (n_b == cs_H) {
+            const double old_y = buf_y[write_pos];
+            const double old_sy = sy;
+            sxy = sxy - old_sy + old_y + (H_f - 1.0) * y_b;
+            sy = old_sy - old_y + y_b;
+        } else {
+            sxy += static_cast<double>(n_b) * y_b;
+            sy += y_b;
+        }
+        buf_y[write_pos] = y_b;
+        ptr += 1;
+        if (n_b < cs_H) {
+            n_b += 1;
+        }
+    }
+
+    cs_buf_n[ci] = n_b;
+    cs_buf_ptr[ci] = ptr;
+    cs_stats[ci * 4 + 0] = sy;
+    cs_stats[ci * 4 + 1] = sxy;
+}

commkit/_cuda/src/selftest.cu

@@ -0,0 +1,14 @@
+// Trivial templated kernel validating the _cuda compile/specialize/launch
+// infrastructure (compiler.py + get_kernel). Not used by any DSP path.
+
+template <typename T>
+__global__ void selftest_scale(const T* __restrict__ x,
+                               T* __restrict__ y,
+                               T alpha,
+                               long long n) {
+    const long long i =
+        static_cast<long long>(blockIdx.x) * blockDim.x + threadIdx.x;
+    if (i < n) {
+        y[i] = alpha * x[i];
+    }
+}

commkit/analysis/__init__.py

@@ -0,0 +1,55 @@
+"""
+Signal analysis and characterization.
+
+Post-processing and diagnostic routines that operate on recovered signals to
+quantify their properties, as opposed to the DSP stages that *produce* those
+signals (synchronization, equalization, recovery, ...).  Functions here are
+grouped by the property they characterize; new analyses can be added as
+independent groups without disturbing the others.
+
+Backend policy
+--------------
+Every function dispatches on the input array type (NumPy -> CPU, CuPy -> GPU)
+and all sample-rate work - phase extraction, unwrapping, filtering, Welch
+PSDs, variance reductions - runs on that backend.  Host-side NumPy inside this
+package is deliberate and limited to three cases:
+
+* **metadata**: lag lists, Welch segment sizing, tau grids - scalar shapes,
+  never data;
+* **tiny post-reduction fits**: e.g. ``np.polyfit`` on an ``(n_lag, C)``
+  variance matrix after a single device->host transfer - cheaper than a device
+  least-squares launch;
+* **report packaging**: summary functions (``linewidth_*``,
+  ``allan_deviation``, ``frequency_drift_metrics`` scalars) return Python
+  floats and *plot-sized* NumPy arrays (Welch/Allan grids, ≤ ``nperseg``
+  bins) after one transfer, because their consumers are prints and plots.
+
+Sample-rate arrays returned to the caller (``carrier_phase_trajectory``,
+``separate_drift_phase_noise``, ``frequency_drift_metrics['df']``,
+``dsh_phase``, ``fm_noise_psd``, ``dsh_fm_noise_psd``) always stay on the
+input backend - chain them without paying transfers.
+"""
+
+from .allan import allan_deviation
+from .drift import frequency_drift_metrics, separate_drift_phase_noise
+from .interferometry import dsh_beat, dsh_fm_noise_psd, dsh_phase, linewidth_dsh
+from .linewidth import (
+    fm_noise_psd,
+    linewidth_beta_separation,
+    linewidth_increment,
+)
+from .trajectory import carrier_phase_trajectory
+
+__all__ = [
+    "allan_deviation",
+    "carrier_phase_trajectory",
+    "dsh_beat",
+    "dsh_fm_noise_psd",
+    "dsh_phase",
+    "fm_noise_psd",
+    "frequency_drift_metrics",
+    "linewidth_beta_separation",
+    "linewidth_dsh",
+    "linewidth_increment",
+    "separate_drift_phase_noise",
+]

commkit/analysis/_common.py

@@ -0,0 +1,236 @@
+"""Shared helpers and constants for the carrier-phase analysis package."""
+
+import numpy as np
+
+__all__ = [
+    "_BETA_SLOPE",
+    "_FWHM_FROM_AREA",
+    "_as_2d",
+    "_pairing_variance",
+    "_plateau_mask",
+    "_scalar_or_array",
+    "_welch_median_bias",
+]
+
+# β-separation-line slope (Di Domenico 2010): S_f(f) = (8 ln2 / π²) · f
+_BETA_SLOPE = 8.0 * np.log(2.0) / (np.pi**2)
+# FWHM linewidth from the integrated FM-noise area above the β-line:
+# Δν = sqrt(8 ln2 · A)
+_FWHM_FROM_AREA = 8.0 * np.log(2.0)
+
+
+def _as_2d(arr):
+    """Promote SISO ``(N,)`` to ``(1, N)``; return ``(arr2d, was_1d)``."""
+    return (arr[None, :], True) if arr.ndim == 1 else (arr, False)
+
+
+def _scalar_or_array(values):
+    """Collapse a length-1 per-channel result to a Python float."""
+    values = np.asarray(values, dtype=np.float64)
+    return float(values[0]) if values.size == 1 else values
+
+
+def _welch_median_bias(n_samples: int, nperseg: int) -> tuple[float, int]:
+    r"""Median/mean ratio of mean-averaged Welch PSD bins (Hann, 50 % overlap).
+
+    Per-bin Welch estimates are ``S·χ²_ν/ν``-distributed with ``ν = 2·K_eff``
+    effective degrees of freedom, so every *median*-based floor summary
+    (plateau cell medians, fenced-band medians) reads the true level ``S``
+    low by ``median(χ²_ν)/ν`` - ``ln 2 ≈ 0.69`` for a single segment,
+    ``≈ 1 - 1/(3K)`` for ``K`` segments.  Callers divide their median-based
+    floor by the returned factor.
+
+    ``K_eff = K/1.056`` accounts for the ``ρ = (1/6)²`` power correlation of
+    adjacent Hann half-overlapped segments (variance factor ``1 + 2ρ``); the
+    χ² median uses the Wilson-Hilferty approximation
+    ``median(χ²_ν) ≈ ν·(1 - 2/(9ν))³`` (< 1.3 % error even at ``ν = 2``).
+
+    Parameters
+    ----------
+    n_samples : int
+        Length of the sequence handed to Welch (for ``fm_noise_psd`` this is
+        the phase length minus one - the first difference).
+    nperseg : int
+        Welch segment length actually used.
+
+    Returns
+    -------
+    factor : float
+        ``median/mean`` ratio in ``(0, 1]``.
+    n_segments : int
+        Welch segment count ``K``.
+    """
+    step = max(nperseg // 2, 1)
+    k = max((int(n_samples) - int(nperseg)) // step + 1, 1)
+    k_eff = k / 1.056 if k > 1 else float(k)
+    nu = 2.0 * k_eff
+    return (1.0 - 2.0 / (9.0 * nu)) ** 3, k
+
+
+def _plateau_mask(
+    f,
+    s2,
+    base2,
+    *,
+    points_per_octave=24,
+    tolerance=1.8,
+    min_cells=6,
+    max_rel_iqr=2.0,
+):
+    """Auto-detect the white-FM plateau of FM-noise PSDs (level + region).
+
+    Laser FM-noise PSDs are bathtub-shaped: drift/flicker rise toward DC and
+    the detection-noise ``f²`` tail rises toward Nyquist, so the white-FM
+    plateau is the **minimum-level region** in between.  Detection works on a
+    **log-frequency grid**: linearly spaced Welch bins are median-reduced
+    into log-spaced cells, the floor is located as the minimum of the
+    median-filtered cell levels, the level is re-centered on the median of
+    the near-floor cells, and the plateau is every cell within a **two-sided**
+    ``tolerance`` factor of that level.  The log-uniform weighting is
+    essential - a plain median over linear bins is dominated by the highest
+    decade, so the slowly-rising ``f²`` tail would bias it high even when it
+    is barely above the plateau.  The two-sided acceptance keeps the region
+    tight: cells already visibly climbing the tail (or dipping below the
+    floor) are excluded, not merely down-weighted.
+
+    A per-cell **dispersion screen** (relative IQR) rejects cells whose bins
+    are not statistically homogeneous before the floor search.  This guards
+    the DSH deconvolution against a slightly wrong delay: at high frequency
+    the assumed and true notch combs decorrelate (argument error ``πfΔτ``)
+    and the deconvolved PSD develops fake-low/fake-high stripes *within* a
+    cell - huge relative IQR - whereas genuine plateau cells carry uniform
+    Welch scatter (relative IQR ≲ 1.6 even for a single-average chi²₂).
+
+    Host-side NumPy by design (plot-sized Welch spectra, one prior transfer).
+
+    Parameters
+    ----------
+    f : ndarray, (nf,)
+        One-sided frequency axis.
+    s2 : ndarray, (C, nf)
+        FM-noise PSD per channel (NaN allowed at masked bins).
+    base2 : ndarray of bool, (C, nf)
+        Eligibility per bin (validity mask and any user fences).
+    points_per_octave : int, default 24
+        Log-grid density for the cell reduction.
+    tolerance : float, default 1.8
+        Two-sided cell-acceptance factor around the re-centered plateau
+        level (±2.6 dB): wide enough for Welch scatter of sparse low-f
+        cells, tight enough that cells visibly on the 1/f or f² slopes are
+        excluded.
+    min_cells : int, default 6
+        Minimum accepted cells; channels with fewer return an all-False row
+        and NaN level (caller falls back and warns).
+    max_rel_iqr : float, default 2.0
+        Dispersion screen: cells with ``IQR/median`` above this (evaluated
+        for cells holding ≥ 5 bins) are excluded from the floor search and
+        the plateau.
+
+    Returns
+    -------
+    used2 : ndarray of bool, (C, nf)
+        Linear bins belonging to accepted cells (all-False where detection
+        failed) - the display/consistency mask.
+    levels : ndarray, (C,)
+        Plateau level per channel: median of accepted cell levels (NaN where
+        detection failed).  ``Δν = π · level``, after the caller divides out
+        the χ²-median bias of Welch bins (``_welch_median_bias``).
+    """
+    used2 = np.zeros_like(base2, dtype=bool)
+    levels = np.full(base2.shape[0], np.nan)
+
+    for c in range(base2.shape[0]):
+        el = base2[c] & np.isfinite(s2[c]) & (f > 0)
+        idx_el = np.flatnonzero(el)
+        if idx_el.size < min_cells:
+            continue
+        fe, se = f[idx_el], s2[c][idx_el]
+
+        n_cells = max(int(np.ceil(np.log2(fe[-1] / fe[0]) * points_per_octave)), 1)
+        edges = np.geomspace(fe[0], fe[-1], n_cells + 1)
+        cell_of = np.clip(np.searchsorted(edges, fe, side="right") - 1, 0, n_cells - 1)
+        occupied = np.unique(cell_of)
+
+        cell_med = np.empty(occupied.size)
+        homogeneous = np.ones(occupied.size, dtype=bool)
+        for i, k in enumerate(occupied):
+            vals = se[cell_of == k]
+            q1, q2, q3 = np.percentile(vals, (25.0, 50.0, 75.0))
+            cell_med[i] = q2
+            if vals.size >= 5 and q2 > 0.0:
+                homogeneous[i] = (q3 - q1) / q2 <= max_rel_iqr
+
+        occ_h, med_h = occupied[homogeneous], cell_med[homogeneous]
+        if med_h.size < min_cells or not (med_h > 0.0).all():
+            continue
+
+        # Robust floor: min of the median-filtered cell levels, so a single
+        # low-outlier cell (e.g. one noisy bin alone in a cell) cannot set it.
+        w = min(5, med_h.size)
+        filt = np.array(
+            [
+                np.median(med_h[max(0, i - w // 2) : i + w // 2 + 1])
+                for i in range(med_h.size)
+            ]
+        )
+        floor = float(filt.min())
+
+        # Re-center: the min is biased low by scatter; the plateau level is
+        # the median of the near-floor cells.
+        near = med_h <= 2.0 * floor
+        if int(near.sum()) < min_cells:
+            continue
+        level0 = float(np.median(med_h[near]))
+
+        # Adaptive two-sided acceptance: a cell joins the plateau only if its
+        # level is consistent with level0 *given its own standard error*
+        # (median SE ≈ 1.2533·σ_bin/√n).  Densely populated cells get a tight
+        # gate (floor ±0.6 dB) that cuts the f² tail where it visibly departs
+        # from the plateau; sparse low-frequency cells keep a wide gate up to
+        # ``tolerance`` so genuine Welch scatter is not speckled out.
+        n_bins = np.array([int((cell_of == k).sum()) for k in occ_h])
+        rich = near & (n_bins >= 8)
+        if rich.any():
+            iqr_rel = np.array(
+                [
+                    float(np.subtract(*np.percentile(se[cell_of == k], (75.0, 25.0))))
+                    / med
+                    for k, med in zip(occ_h[rich], med_h[rich])
+                ]
+            )
+            sigma_bin = float(np.median(iqr_rel)) / 1.349
+        else:
+            sigma_bin = 0.5  # sparse everywhere: fall back to wide gates
+        sem = 1.2533 * sigma_bin / np.sqrt(n_bins)
+        tol_log = np.clip(3.0 * sem, 0.15, np.log(tolerance))
+        accepted = np.abs(np.log(med_h / level0)) <= tol_log
+        if int(accepted.sum()) < min_cells:
+            continue
+
+        # Keep the largest connected accepted region (gaps of up to 6 cells -
+        # notch dropouts - are bridged) so isolated outlier cells far from
+        # the plateau cannot stretch the reported band.
+        idx_acc = np.flatnonzero(accepted)
+        splits = np.flatnonzero(np.diff(idx_acc) > 6) + 1
+        clusters = np.split(idx_acc, splits)
+        best = max(clusters, key=len)
+        if best.size < min_cells:
+            continue
+        final = np.zeros_like(accepted)
+        final[best] = True
+
+        levels[c] = float(np.median(med_h[final]))
+        used2[c, idx_el[np.isin(cell_of, occ_h[final])]] = True
+
+    return used2, levels
+
+
+def _pairing_variance(y2, d2, xp):
+    """Total wrapped phase-error increment variance for a channel pairing.
+
+    Returns a 0-d array on the input backend (no host sync); the caller
+    compares the candidate pairings and pays a single device->host transfer
+    for the final boolean decision.
+    """
+    pe = xp.angle(y2 * xp.conj(d2)).astype(xp.float64)
+    return xp.sum(xp.var(xp.diff(pe, axis=-1), axis=-1))

commkit/analysis/allan.py

@@ -0,0 +1,108 @@
+"""Overlapping Allan deviation of an instantaneous-frequency series."""
+
+import numpy as np
+
+from ..backend import ArrayType, dispatch, to_device
+from ._common import _as_2d
+
+__all__ = ["allan_deviation"]
+
+
+def allan_deviation(
+    df: ArrayType,
+    symbol_rate: float,
+    *,
+    taus: np.ndarray | None = None,
+    n_taus: int = 30,
+    debug_plot: bool = False,
+) -> dict[str, np.ndarray]:
+    r"""Overlapping Allan deviation of an instantaneous-frequency series.
+
+    The log-log slope of sigma_y(tau) classifies the dominant noise
+    process by averaging time: white-FM proportional to tau^(-1/2),
+    flicker-FM proportional to tau^0, random-walk-FM proportional to tau^(+1/2),
+    linear drift proportional to tau^(+1).
+
+    Parameters
+    ----------
+    df : array_like
+        Instantaneous frequency samples in Hz (e.g. ``frequency_drift_metrics``
+        ``df``), ``(N,)`` or ``(C, N)``, sampled at ``symbol_rate``.
+    symbol_rate : float
+        Sample rate of ``df`` in Hz (``τ_0 = 1/symbol_rate``).
+    taus : array_like, optional
+        Explicit averaging times in seconds.  Default: ``n_taus`` values
+        geometrically spaced from ``τ_0`` to ``N//4·τ_0``.
+    n_taus : int, default 30
+        Number of log-spaced averaging times when ``taus`` is None.
+    debug_plot : bool, default False
+        If True, plot the Allan deviation
+        (``allan_deviation``).
+
+    Returns
+    -------
+    dict
+        ``{'tau_s', 'adev'}`` where ``adev`` is ``(n_tau,)`` (SISO) or
+        ``(C, n_tau)`` (MIMO).  NumPy arrays.
+
+    Notes
+    -----
+    **Limitations.**
+
+    * ``df`` is in **Hz**, not the dimensionless fractional frequency
+      ``y = δf/ν₀`` of clock metrology; ``adev`` is therefore in Hz.  Divide
+      by the optical carrier frequency (~193 THz) to compare against
+      oscillator specs quoted fractionally.
+    * The overlapping estimator improves confidence but the largest-τ points
+      still average only ``~N/(2m)`` second differences - the last decade of
+      the curve is statistically fragile (hence the ``N//4`` default cap).
+      No confidence intervals are computed.
+    * ADEV cannot distinguish white-PM from flicker-PM noise (both fall as
+      ``~τ⁻¹`` after the frequency differencing); the modified Allan deviation
+      would be needed for that.  For laser work this matters at small τ where
+      AWGN angle noise (white-PM) dominates.
+    * A deterministic sinusoidal wander of period ``T_m`` produces the classic
+      scalloped ADEV with nulls at ``τ = k·T_m`` - do not read those dips as
+      noise-floor improvements.
+    """
+    df_arr, xp, _ = dispatch(df)
+    y2, was_1d = _as_2d(df_arr)
+    c, n = y2.shape
+    tau0 = 1.0 / float(symbol_rate)
+
+    # Cumulative phase (time error) x_i = Σ y · τ0.
+    zeros_col = xp.zeros((c, 1), dtype=xp.float64)
+    x = xp.concatenate(
+        [zeros_col, xp.cumsum(y2.astype(xp.float64), axis=-1) * tau0], axis=-1
+    )
+
+    if taus is None:
+        m_max = max(1, n // 4)
+        ms = np.unique(np.round(np.geomspace(1, m_max, n_taus)).astype(int))
+    else:
+        taus_cpu = np.asarray(to_device(taus, "cpu"), dtype=np.float64)
+        ms = np.unique(np.maximum(1, np.round(taus_cpu / tau0).astype(int)))
+        ms = ms[ms <= max(1, (x.shape[-1] - 1) // 2)]
+
+    tau_s = ms * tau0
+    adev = xp.full((c, ms.size), xp.nan, dtype=xp.float64)
+    # One vectorized second-difference per τ across all channels (the C-loop
+    # would launch C·n_tau tiny kernels on GPU for no benefit).
+    for j, m in enumerate(ms):
+        m = int(m)
+        if x.shape[-1] - 2 * m < 1:
+            continue
+        d2 = x[:, 2 * m :] - 2.0 * x[:, m:-m] + x[:, : -2 * m]
+        avar = xp.mean(d2**2, axis=-1) / (2.0 * (m * tau0) ** 2)
+        adev[:, j] = xp.sqrt(avar)
+
+    tau_s_cpu = np.asarray(tau_s, dtype=np.float64)
+    adev_cpu = to_device(adev, "cpu")
+    adev_out = adev_cpu[0] if was_1d else adev_cpu
+
+    if debug_plot:
+        from .. import plotting as _plotting
+
+        _plotting.plot_allan_deviation(tau_s_cpu, adev_out, show=True)
+
+    return {"tau_s": tau_s_cpu, "adev": adev_out}