commkit 3.6.1__tar.gz → 3.7.0__tar.gz

{commkit-3.6.1 → commkit-3.7.0}/.github/workflows/ci.yml

@@ -120,13 +120,15 @@ jobs:
           tests/coding/test_convolutional.py tests/coding/test_turbo.py::TestEncoding
           tests/coding/test_turbo.py::TestDecoding::test_noiseless
           tests/coding/test_linear_codes.py::TestMaximumLikelihood
+          tests/timing/test_clock_recovery.py::TestEstimate::test_matches_oracle
+          tests/timing/test_clock_recovery.py::TestValidation
           -k "not waterfall and not threshold"
           --device=cpu --cov=commkit --cov-report=
 
       - name: Kernel coverage report
         run: >-
           uv run coverage report --show-missing --fail-under=85
-          --include="commkit/equalization/_numba_loops.py,commkit/equalization/_sequential/*,commkit/frequency.py,commkit/recovery/*,commkit/coding/ldpc.py,commkit/coding/shaping.py,commkit/coding/polar.py,commkit/coding/convolutional.py,commkit/coding/turbo.py"
+          --include="commkit/equalization/_numba_loops.py,commkit/equalization/_sequential/*,commkit/frequency.py,commkit/recovery/*,commkit/coding/ldpc.py,commkit/coding/shaping.py,commkit/coding/polar.py,commkit/coding/convolutional.py,commkit/coding/turbo.py,commkit/timing/_numba_loops.py"
 
 # GPU legs (--device=gpu / --device=all) require CuPy + CUDA and are run
 # manually or on a self-hosted runner; they are intentionally not part of

{commkit-3.6.1 → commkit-3.7.0}/AGENTS.md

@@ -54,6 +54,8 @@ uv run pytest
 uv run ruff format .
 ```
 
+A commit that changes only text that cannot change behaviour (docstrings, comments, Markdown) runs `ruff check` and `ruff format` alone. The full gate applies again as soon as code, tests or notebook cells change, or an edited docstring holds an example that runs.
+
 **Benchmarks** are explicit-only; `uv run pytest` never collects them. A commit that changes a public signature smoke-runs them once, untimed, so their call sites cannot rot:
 
 ```bash
@@ -101,6 +103,7 @@ Dependencies point downward only:
 - Construction does no hidden work: no mapping, no normalization, no device move, no shape guessing. Factories (`generate`, frames) do that work.
 - `sig.to("gpu")` and `sig.replace(...)` return new Signals sharing the arrays; `clone()` copies.
 - **Alignment invariant:** reference symbol *k* corresponds to symbol period *k* of the samples. A function that drops or shifts symbol periods slices the reference to match. Metrics raise on mismatch; they never guess.
+- **Absolute power.** Samples are dimensionless, and a Signal holds no power. Impairments never rescale the signal component: noise and distortion are added in the samples' units. A function whose model depends on absolute power takes `<where>_power_dbm` (`launch_power_dbm`, `received_power_dbm`, `lo_power_dbm`), the mean power its input stands for, summed over channels, and returns samples in the input's units (a square-law detector: the input's power units). A PSD is in the samples' units per Hz, not dBm/Hz.
 
 ### Function signatures
 
@@ -153,7 +156,7 @@ Dependencies point downward only:
   - `method=` strings name only a numerical flavor of one algorithm (`method="maxlog" | "exact"`); algorithms are objects.
   - Output scaling has three names: `normalize` (bool) measures the power and rescales to the library's convention; `correct_power` (bool) applies the exact, known gain of a rate change without measuring; `<thing>_normalization` (a string) chooses how coefficients are scaled (`taps_normalization="unit_energy" | "unity_gain"`).
   - A search window is `search_range`, a `(start, stop)` pair in the axis's unit, or `search_band`, a half-width in Hz around a nominal frequency.
-  - Values are in SI units without a suffix (`linewidth` in Hz, `drift_rate` in rad/s, `taus` in s). A result holding one quantity in two units suffixes the SI one (`lags` in samples, `lag_s`). A conventional non-SI unit goes into the name: `_db`, `_dbm`, `_deg`, `_nm`, `_km`, `_ps_nm_km`. Normalized quantities say so (`normalized_bandwidth`). No second name for one quantity in another unit (no `center_frequency_ghz`); `center_wavelength_nm` is a different, derived quantity.
+  - Values are in SI units without a suffix (`linewidth` in Hz, `drift_rate` in rad/s, `taus` in s). A result holding one quantity in two units suffixes the SI one (`lags` in samples, `lag_s`). A conventional non-SI unit goes into the name: `_db`, `_dbm`, `_deg`, `_nm`, `_km`, `_ps_nm_km`, `_ppm`, `_db_hz`. Normalized quantities say so (`normalized_bandwidth`). No second name for one quantity in another unit (no `center_frequency_ghz`); `center_wavelength_nm` is a different, derived quantity.
 
 ### Docstrings
 
@@ -184,7 +187,7 @@ Docstrings describe the code as it is; a change in behavior updates them in the
   - **Transforms keep the input's precision** throughout (filters, impairments, the fiber solver and DBP, resampling, delays, carrier-phase correction): complex64 in and out, complex128 in and out.
   - **Fixed-precision blocks** compute in single precision whatever the input: the equalizers in complex64, `compute_llr` / `Constellation.llr` in float32. Double input emits `commkit.PrecisionWarning` (`_array.warn_if_double`, attributed to the caller's line). The test suite turns it into an error (`pytest_configure` in `tests/conftest.py`; not pyproject's `filterwarnings`, which imports commkit before coverage starts), so a library path feeding double data to these blocks fails CI. Training and reference symbols are not checked.
   - **Deliberate float64 / complex128**, documented where it happens, only on phases, small arrays or accumulators, never on sample-rate data that is then cast back:
-    - phases before `xp.unwrap()` (float32 rounding causes spurious quadrant slips), phase trajectories and ramps (wrapped in float64, rotated in the data's precision), frequency grids and estimates;
+    - phases before `xp.unwrap()` (float32 rounding causes spurious quadrant slips), phase trajectories and ramps (wrapped in float64, rotated in the data's precision), the strobe positions of clock recovery (symbol rate; the sampling instants built from them are an integer index and a fraction in the data's precision), frequency grids and estimates;
     - recursion state: PLL, Tikhonov/Kalman block transitions, the IIR filter's sections and state (poles near z = 1);
     - RLS keeps `P`, the gain `k` and the regressor buffers in complex128 (in single precision `P` loses positive definiteness and the filter diverges);
     - LMS/CMA/RDE accumulate dot products and gradient updates in complex128 around complex64 inputs and weights; the block equalizers stay complex64, as their tap sums run inside the FFTs;
@@ -202,7 +205,7 @@ Docstrings describe the code as it is; a change in behavior updates them in the
 | --- | --- | --- |
 | Vectorized: filters, resampling, spectra, impairments, metrics, frequency-domain equalizers | NumPy/CuPy via `x, xp, sp = dispatch(samples)` | follows the input |
 | Per-symbol searches over a small table: LLRs (all points, or per axis for separable QAM; max-log without a prior in closed form), hard decisions without a square lattice | CPU: Numba `parallel=True` over blocks of symbols (LLRs), chunked NumPy (decisions). GPU: one thread per symbol (`llr`, `llr_separable`, `llr_separable_maxlog`, `bps_min_d2`'s nearest-point mode); decisions on double input or above 1024 points use the chunked search on both devices; LLRs above 16 bits per symbol raise on the GPU | follows the input |
-| Sequential recursions: LMS/RLS/CMA/RDE, PLL, Tikhonov, cycle slips, the Mengali-Morelli bootstrap, per-codeword decoders on trellises and trees (CCDM, polar SC/SCL, Viterbi, BCJR, turbo, recursive systematic encoding) | Numba `@njit(cache=True, fastmath=True, nogil=True)`, independent rows in `prange`. The equalizers' kernel with inline carrier recovery compiles strict (unwrap, running sums) and calls fast-math tap and distance loops as separate functions (an `inline="always"` helper takes its caller's flags) | CPU; GPU input does one round trip |
+| Sequential recursions: LMS/RLS/CMA/RDE, PLL, Gardner clock recovery, Tikhonov, cycle slips, the Mengali-Morelli bootstrap, per-codeword decoders on trellises and trees (CCDM, polar SC/SCL, Viterbi, BCJR, turbo, recursive systematic encoding) | Numba `@njit(cache=True, fastmath=True, nogil=True)`, independent rows in `prange`. The equalizers' kernel with inline carrier recovery compiles strict (unwrap, running sums) and calls fast-math tap and distance loops as separate functions (an `inline="always"` helper takes its caller's flags) | CPU; GPU input does one round trip |
 | Linear recursions: IIR filtering | CPU: Numba without `fastmath`, so double input matches SciPy bit for bit. GPU: `iir` kernel: each block's state from a zero start in parallel, states carried across blocks in two levels (groups, then across groups), blocks filtered again, in double precision | follows the input |
 | Binary linear algebra of codes: encoding, syndromes, ML-decoding correlations on the GPU, Chase's test patterns | one float32 GEMM per chunk (`coding._gf2.matmul_mod2`), exact below an inner dimension of 2^24, parity in place (CPU) or by one elementwise kernel writing int8 (GPU); small tables cached per code and device (`backend._device_tables`) | follows the input |
 | Algebraic decoding (BCH, Reed-Solomon): Berlekamp-Massey, Chien search to the locator's degree, Forney | CPU: Numba `parallel=True` over codewords. GPU: `algebraic_correct`, one thread per codeword in integer table arithmetic, so both agree exactly | follows the input |
@@ -212,7 +215,7 @@ Docstrings describe the code as it is; a change in behavior updates them in the
 | Elementwise chains between multi-core FFTs (fiber solver's Kerr and PMD stages) | NumPy: a Numba `parallel=True` pass competes with `scipy.fft`'s threads; adopt one only on a paired end-to-end A/B | CPU |
 | Other hot spots limited by intermediates, launches or round trips | CUDA C++ via CuPy `RawModule` (`commkit/_cuda/src`) | GPU |
 
-**Numba kernels live at module level** in a private module (`equalization/_numba_loops.py`, `coding/_numba_loops.py`, `mapping/_numba_llr.py`) that a getter `_get_numba_<name>()`, defined in the module that calls the kernel, imports on first use, so `import commkit` does not load Numba and `cache=True` works across processes. A kernel defined inside a function that calls another kernel defined there recompiles in every process (Numba's cache key misses the captured dispatcher); a getter may build a closure that captures only constants (`_get_numba_sos`).
+**Numba kernels live at module level** in a private module (`equalization/_numba_loops.py`, `coding/_numba_loops.py`, `mapping/_numba_llr.py`, `timing/_numba_loops.py`) that a getter `_get_numba_<name>()`, defined in the module that calls the kernel, imports on first use, so `import commkit` does not load Numba and `cache=True` works across processes. A kernel defined inside a function that calls another kernel defined there recompiles in every process (Numba's cache key misses the captured dispatcher); a getter may build a closure that captures only constants (`_get_numba_sos`).
 
 **Host-sync hygiene:**
 

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

@@ -4,6 +4,42 @@ Notable changes to CommKit, newest first. Performance figures are from the refer
 
 ## [Unreleased]
 
+## [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.
+
+### Changes that may need code updates
+
+- The adaptive equalizers (`lms`, `rls`, `cma`, `rde`, `block_lms`, `block_cma`, `block_rde`, `apply_taps(normalize=True)`) divide each input channel by its RMS instead of `rms * sqrt(sps)`. The old scale applied the transmit convention `E|x|^2 = 1/sps` at the slicer and handed it a gain of `1/sqrt(sps)` (0.71 at 2 sps), below the decision margins of unipolar PAM-4 (0.83) and 64-QAM (0.86), where blind decision-directed adaptation settled at a shrunk false solution (BER 0.25 and 0.20). After a matched filter the symbol instants now reach the slicer within `beta/4` of unit power at any timing phase, and blind adaptation reaches the trained BER. Consequences:
+  - an explicit `step_size` of the sequential equalizers acts `sps` times stronger (the regressor power is 1): halve it at 2 sps for the former behaviour;
+  - the block equalizers' default steps are divided by `sps`, so the defaults behave as before; explicit block steps act `sps` times stronger, and their stability ceilings read `step_size * block_size * sps`;
+  - `EqualizerResult.input_norm_factor` and `EqualizerState.input_norm_factor` are the plain per-channel RMS; the docstring gives the exact rebuild of `y_hat` from the raw samples, the taps and this factor.
+- `commkit.timing` is a package (`synchronization`, `clock_recovery`). Import from `commkit.timing` and nothing changes.
+- The example notebooks are renumbered: the new 12 (sampling-clock recovery) and 22 (direct and self-coherent detection) move the former 12-28 to 13-30.
+
+### Added
+
+- `timing.estimate_sampling_clock_offset` and `timing.correct_sampling_clock_offset` with `timing.Gardner(normalized_bandwidth=, proportional_gain=, integral_gain=, joint_channels=, method="classical" | "power")`: Gardner clock recovery in one Numba loop. The offset in ppm comes from the slope of the tracked timing trajectory (`SamplingClockOffsetEstimate`); the correction resamples along the strobes, or by a constant factor from an earlier capture's estimate. An open-loop fit of the S-curve sets the gains from the loop bandwidth and starts the loop at the right phase; the power detector keeps its gain at small rolloffs. Measured within 0.06 ppm on 2^17 symbols at 20 dB; after recovery the SNR is the AWGN's plus the jitter's ISI, as predicted.
+- `impairments.apply_sampling_clock_offset(offset_ppm=)`: an ADC clock off its nominal rate, by band-limited resampling (48-tap windowed sinc, error below -119 dB up to 0.4 cycles per sample).
+- `impairments.apply_sampling_jitter(jitter=)` and `impairments.apply_quantization(num_bits=, full_scale=, enob=)`: sampling at jittered instants (SNR `-20 log10(2 pi f sigma)` of a tone) and a mid-rise quantizer with clipping and the converter's lumped noise.
+- `apply_iq_imbalance(skew=)`: a time skew of Q against I, the frequency-dependent part of IQ imbalance (image `tan^2(pi f tau)`), which the memoryless corrections cannot remove.
+- `metrics.awgn_ser`, `awgn_ber`, `awgn_mi`, `awgn_gmi(constellation, *, esn0_db)`: closed-form performance over AWGN in the conventions of the measured metrics. Error rates are exact for one-dimensional and separable constellations (PAM bipolar and unipolar, square QAM including shaped, BPSK, QPSK) and union bounds otherwise; MI and GMI by Gauss-Hermite quadrature, converged to 3e-7 bit.
+- `impairments.apply_coherent_detection(received_power_dbm=, lo_power_dbm=, responsivity=, thermal_noise_density=, cmrr_db=, lo_rin_db_hz=, balanced=)`: the shot and thermal noise of a phase-diversity receiver from physical parameters (shot-noise limit `Es/N0 = eta n_p`), the common-mode leak of the signal's own power and of the LO's RIN through a finite CMRR, and single-ended detection.
+- `impairments.apply_photodetection(received_power_dbm=, ...)`: the square law in the input's power units with signal-dependent shot noise, thermal noise, dark current, saturation and `sum_channels`; real output, and a Signal becomes digital baseband. `impairments.apply_intensity_noise(rin_db_hz=)`: laser RIN as a real amplitude factor.
+- A WARNING when the power of an equalizer's decided symbols differs from the decision constellation's by more than 1.5 dB: a false lock, or a constellation that does not match the signal.
+- Notebooks: 12 sampling-clock recovery, 22 direct and self-coherent detection; notebook 10 covers IQ skew and the ADC, notebook 06 uses the closed forms.
+
+### Fixed
+
+- `upsample`, `decimate` and `resample` promoted float32 to float64 (complex64 to complex128) on the GPU, because `cupyx` designs its polyphase filter in float64; the GPU now applies the CPU's filter in the data's precision.
+- Equalizer docstrings: `weights_history` row `n` of the sequential equalizers holds the taps after the update at symbol `n`; an explicit `constellation` applies to the call only and the returned Signal keeps the input's description; real input is equalized as complex64. `Constellation.pam` states the unipolar energy penalty `2(2M - 1)/(M + 1)` (3.01 dB for OOK, 4.47 dB for PAM-4).
+
+### Development
+
+- `AGENTS.md`: the absolute-power rule (samples are dimensionless, a Signal holds no power, physical functions take `<where>_power_dbm` and return samples in the input's units), the `_ppm` and `_db_hz` suffixes, text-only commits skip mypy and pytest.
+- Tests: a GN-model oracle for the split-step solver (first-order NLI with the coherent span factor, within 0.5 dB and the `P^3` law), the scaling chain of every equalizer rebuilt from raw samples, an IM-DD receiver chain with blind LMS on unipolar PAM-4, a plain-Python oracle for the Gardner loop.
+- `benchmarks/bench_gardner.py` (no baseline recorded yet).
+
 ## [3.6.1] - 2026-11-05
 
 ### Added
@@ -467,7 +503,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.6.1...HEAD
+[Unreleased]: https://github.com/lokgar/commkit/compare/v3.7.0...HEAD
+[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
 [3.5.0]: https://github.com/lokgar/commkit/compare/v3.4.0...v3.5.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: commkit
-Version: 3.6.1
+Version: 3.7.0
 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
@@ -146,7 +146,7 @@ CommKit never picks a device for you: data stays where you put it, and each func
 | [`commkit.multirate`](https://github.com/lokgar/commkit/blob/main/commkit/multirate.py) | `resample` (fractional), `decimate`, `upsample`, `decimate_to_symbol_rate`. |
 | [`commkit.spectral`](https://github.com/lokgar/commkit/blob/main/commkit/spectral.py) | Welch PSD, spectrograms, frequency shifting, pilot tones. |
 | [`commkit.impairments`](https://github.com/lokgar/commkit/tree/main/commkit/impairments) | AWGN at an Es/N0 (measured as energy per symbol) or of an absolute variance, ASE at an OSNR (`apply_ase`), phase noise, IQ imbalance (blind estimate; Löwdin and Gram-Schmidt correction), chromatic dispersion, PMD and polarization mixing, and nonlinear fiber propagation over amplified spans (split-step Kerr effect with dispersion, loss, PMD and ASE) of a `Fiber`. |
-| [`commkit.timing`](https://github.com/lokgar/commkit/blob/main/commkit/timing.py) | Barker and Zadoff-Chu sequences, `estimate_timing` / `correct_timing`, fractional delay estimation and correction. |
+| [`commkit.timing`](https://github.com/lokgar/commkit/tree/main/commkit/timing) | Barker and Zadoff-Chu sequences, `estimate_timing` / `correct_timing`, fractional delay estimation and correction. |
 | [`commkit.frequency`](https://github.com/lokgar/commkit/blob/main/commkit/frequency.py) | `estimate_frequency_offset` / `correct_frequency_offset` with `MthPower`, `MengaliMorelli`, `PilotSlope` and `SpectralPeak`; static and blockwise. |
 | [`commkit.recovery`](https://github.com/lokgar/commkit/tree/main/commkit/recovery) | `estimate_carrier_phase` / `correct_carrier_phase` with `ViterbiViterbi`, `BPS`, `PLL`, `Tikhonov`, `ConstantPhase`, `PilotInterpolation`, `PilotTone(s)`; cycle-slip correction; `resolve_phase_ambiguity` and `resolve_channel_permutation`. |
 | [`commkit.equalization`](https://github.com/lokgar/commkit/tree/main/commkit/equalization) | Sequential `lms`, `rls`, `cma`, `rde` (Numba) and frequency-domain `block_lms`, `block_cma`, `block_rde` (CuPy, CUDA graphs), butterfly MIMO, inline carrier recovery (`cpr=PLL()` / `BPS()`), continuation with `state=`, `zf_equalizer`; pilot-aided CMA and RDE from a frame's pilots (`EqualizerPilots`); polarization demultiplexing on pilot tones (`estimate_polarization_tones` / `correct_polarization`). |

{commkit-3.6.1 → commkit-3.7.0}/README.md

@@ -110,7 +110,7 @@ CommKit never picks a device for you: data stays where you put it, and each func
 | [`commkit.multirate`](https://github.com/lokgar/commkit/blob/main/commkit/multirate.py) | `resample` (fractional), `decimate`, `upsample`, `decimate_to_symbol_rate`. |
 | [`commkit.spectral`](https://github.com/lokgar/commkit/blob/main/commkit/spectral.py) | Welch PSD, spectrograms, frequency shifting, pilot tones. |
 | [`commkit.impairments`](https://github.com/lokgar/commkit/tree/main/commkit/impairments) | AWGN at an Es/N0 (measured as energy per symbol) or of an absolute variance, ASE at an OSNR (`apply_ase`), phase noise, IQ imbalance (blind estimate; Löwdin and Gram-Schmidt correction), chromatic dispersion, PMD and polarization mixing, and nonlinear fiber propagation over amplified spans (split-step Kerr effect with dispersion, loss, PMD and ASE) of a `Fiber`. |
-| [`commkit.timing`](https://github.com/lokgar/commkit/blob/main/commkit/timing.py) | Barker and Zadoff-Chu sequences, `estimate_timing` / `correct_timing`, fractional delay estimation and correction. |
+| [`commkit.timing`](https://github.com/lokgar/commkit/tree/main/commkit/timing) | Barker and Zadoff-Chu sequences, `estimate_timing` / `correct_timing`, fractional delay estimation and correction. |
 | [`commkit.frequency`](https://github.com/lokgar/commkit/blob/main/commkit/frequency.py) | `estimate_frequency_offset` / `correct_frequency_offset` with `MthPower`, `MengaliMorelli`, `PilotSlope` and `SpectralPeak`; static and blockwise. |
 | [`commkit.recovery`](https://github.com/lokgar/commkit/tree/main/commkit/recovery) | `estimate_carrier_phase` / `correct_carrier_phase` with `ViterbiViterbi`, `BPS`, `PLL`, `Tikhonov`, `ConstantPhase`, `PilotInterpolation`, `PilotTone(s)`; cycle-slip correction; `resolve_phase_ambiguity` and `resolve_channel_permutation`. |
 | [`commkit.equalization`](https://github.com/lokgar/commkit/tree/main/commkit/equalization) | Sequential `lms`, `rls`, `cma`, `rde` (Numba) and frequency-domain `block_lms`, `block_cma`, `block_rde` (CuPy, CUDA graphs), butterfly MIMO, inline carrier recovery (`cpr=PLL()` / `BPS()`), continuation with `state=`, `zf_equalizer`; pilot-aided CMA and RDE from a frame's pilots (`EqualizerPilots`); polarization demultiplexing on pilot tones (`estimate_polarization_tones` / `correct_polarization`). |

{commkit-3.6.1 → commkit-3.7.0}/benchmarks/bench_block_blind.py

@@ -30,16 +30,16 @@ from commkit.mapping import Constellation
 ROUNDS = dict(rounds=3, warmup_rounds=1, iterations=1)
 N_SYM = 100_000
 
-# Converging step sizes per (equalizer, block_size).  RDE on 16-QAM from a
-# cold start (no CMA pre-convergence) converges slowly at 2048: at 4e-4 it is
-# error-free from about symbol 70 000, so its SER is scored after that (7e-4
-# never settled, still 2-5 % SER at the end); its cost does not depend on
-# the data.
+# Converging step sizes per (equalizer, block_size), on input normalized to
+# unit mean power at 2 sps.  RDE on 16-QAM from a cold start (no CMA
+# pre-convergence) converges slowly at 2048: at 2e-4 it is error-free from
+# about symbol 70 000, so its SER is scored after that (3.5e-4 never
+# settled, still 2-5 % SER at the end); its cost does not depend on the data.
 STEP_SIZE = {
-    ("cma", 256): 2e-4,
-    ("cma", 2048): 3e-4,
-    ("rde", 256): 3e-3,
-    ("rde", 2048): 4e-4,
+    ("cma", 256): 1e-4,
+    ("cma", 2048): 1.5e-4,
+    ("rde", 256): 1.5e-3,
+    ("rde", 2048): 2e-4,
 }
 SKIP = {("rde", 2048): 70_000}
 MAX_SER = {"cma": 1e-2, "rde": 1e-2}

{commkit-3.6.1 → commkit-3.7.0}/benchmarks/bench_block_lms.py

@@ -54,9 +54,10 @@ CPR_CONFIGS = [
 ]
 
 
-# Converging step sizes for the 30-degree mixing of the workload: the block
-# update's stability ceiling falls with block_size.
-STEP_SIZE = {256: 3e-3, 2048: 5e-4}
+# Converging step sizes for the 30-degree mixing of the workload, on input
+# normalized to unit mean power at 2 sps: the block update's stability
+# ceiling falls with block_size.
+STEP_SIZE = {256: 1.5e-3, 2048: 2.5e-4}
 
 
 def _bench_block_lms(benchmark, xp, sync, cpr_kwargs, block_size, n_train=None):

commkit-3.7.0/benchmarks/bench_gardner.py

@@ -0,0 +1,36 @@
+"""Benchmarks: Gardner clock recovery (CPU Numba loop; GPU input makes one
+round trip and resamples on the device)."""
+
+from types import SimpleNamespace
+
+import pytest
+from benchutils import assert_converged
+from workloads import clock_offset_workload
+
+from commkit.mapping import Constellation
+from commkit.multirate import decimate_to_symbol_rate
+from commkit.timing import Gardner, correct_sampling_clock_offset
+
+ROUNDS = dict(rounds=3, warmup_rounds=1, iterations=1)
+N_SYM = 2**18
+
+
+@pytest.mark.parametrize("method", ["classical", "power"])
+def bench_correct_sampling_clock_offset(benchmark, backend_device, xp, sync, method):
+    samples, symbols = clock_offset_workload(N_SYM)
+    x = xp.asarray(samples)
+
+    def run():
+        out = correct_sampling_clock_offset(x, Gardner(method=method), sps=2)
+        sync()
+        return out
+
+    y = benchmark.pedantic(run, **ROUNDS)
+    sym = decimate_to_symbol_rate(y, sps=2)
+    assert_converged(
+        SimpleNamespace(y_hat=sym),
+        symbols,
+        Constellation.qam(16),
+        skip=1000,
+        max_ser=1e-3,
+    )

{commkit-3.6.1 → commkit-3.7.0}/benchmarks/workloads.py

@@ -168,3 +168,32 @@ def coded_workload(code, num_codewords: int, esn0_db: float, seed: int = 0):
     rx = apply_awgn(sig, esn0_db=esn0_db, rng=seed + 1)
     llrs = compute_llr(rx, noise_var=10 ** (-esn0_db / 10))
     return np.asarray(llrs, dtype=np.float32), sig.reference.info_bits
+
+
+def clock_offset_workload(
+    n_sym: int, num_ch: int = 2, ppm: float = 20.0, seed: int = 0
+):
+    """Matched-filtered dual-pol 16-QAM at 2 SPS (RRC 0.1, 20 dB Es/N0, a
+    0.37-sample delay) sampled by a clock ``ppm`` fast, for the clock-recovery
+    benches.  Returns ``(samples (num_ch, ~2 n_sym) complex64, symbols)``."""
+    from commkit import RRC
+    from commkit.core import generate
+    from commkit.filtering import matched_filter
+    from commkit.impairments import apply_sampling_clock_offset
+    from commkit.timing import fft_fractional_delay
+
+    tx = generate(
+        Constellation.qam(16),
+        num_symbols=n_sym,
+        symbol_rate=FS,
+        sps=2,
+        pulse=RRC(rolloff=0.1),
+        num_channels=num_ch,
+        rng=seed,
+    )
+    rx = apply_awgn(tx, esn0_db=20.0, rng=seed + 1)
+    rx = apply_sampling_clock_offset(
+        fft_fractional_delay(rx, delay=0.37), offset_ppm=ppm
+    )
+    mf = matched_filter(rx)
+    return np.asarray(mf.samples, dtype=np.complex64), np.asarray(tx.reference.symbols)

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

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

{commkit-3.6.1 → commkit-3.7.0}/commkit/_constants.py

@@ -1,3 +1,4 @@
 """Physical constants shared across the package."""
 
 SPEED_OF_LIGHT = 299_792_458.0  # m/s, exact (SI definition)
+ELEMENTARY_CHARGE = 1.602_176_634e-19  # C, exact (SI definition)

{commkit-3.6.1 → commkit-3.7.0}/commkit/_dispersion.py

@@ -110,7 +110,7 @@ def spread_samples(
 
     ``τ(ω) = β₂ L ω`` over ``|f| <= bandwidth / 2`` spans
     ``2π |β₂ L| · bandwidth`` seconds; over the whole sampled band
-    (``bandwidth = fs``) this is Savory's FIR length (Opt. Express 16, 2008).
+    (``bandwidth = fs``) this is the FIR length that covers the whole spread.
     """
     return 2.0 * np.pi * abs(beta2_length) * bandwidth * sampling_rate
 
@@ -143,8 +143,7 @@ def compensation_taps(
 
     Minimizes ``∫_{|θ|<W} |Σ h[n] e^{-jθn} - exp(j a θ²)|² dθ`` with
     ``θ = ω / fs``, ``W = π · bandwidth / fs`` and ``a = β₂ L fs² / 2``, for
-    ``n`` centred on tap ``(num_taps - 1) // 2`` (Eghbali et al., J.
-    Lightw. Technol. 32, 2014): ``Q h = p`` with the Toeplitz Gram matrix
+    ``n`` centred on tap ``(num_taps - 1) // 2``: ``Q h = p`` with the Toeplitz Gram matrix
     ``Q[m, k] = (W/π) sinc(W (m-k) / π)`` and ``p[m]`` the band integral of
     the response, exact through Fresnel integrals.  Over the whole band
     (``W = π``) ``Q`` is the identity and ``h = p``, the truncated

{commkit-3.6.1 → commkit-3.7.0}/commkit/_fiber.py

@@ -15,7 +15,7 @@ fast birefringence of the fiber into ``8/9 · γ · (|x|² + |y|²)``.  In
 CommKit's sign convention (``_dispersion``: propagation multiplies a spectrum
 by ``exp(-j β₂ ω² L / 2)``) the field obeys
 
-    dA/dz = -α/2 A - j β₂/2 ∂²A/∂t² + β₃/6 ∂³A/∂t³ - j γ |A|² A,
+    dA/dz = -α/2 A + j β₂/2 ∂²A/∂t² + β₃/6 ∂³A/∂t³ - j γ |A|² A,
 
 the complex conjugate of the textbook (Agrawal) form, so the Kerr phase is
 ``exp(-j γ |A|² L)``.  Matching the dispersion sign is what keeps solitons

{commkit-3.6.1 → commkit-3.7.0}/commkit/analysis/_common.py

@@ -21,7 +21,7 @@ __all__ = [
     "_whittle_fit",
 ]
 
-# β-separation-line slope (Di Domenico 2010): S_f(f) = (8 ln2 / π²) · f
+# β-separation-line slope: 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)

{commkit-3.6.1 → commkit-3.7.0}/commkit/coding/exit.py

@@ -655,12 +655,6 @@ def ldpc_exit_curves(
       code run so close together that the closed-form fits of ``J``
       (within 1e-3) move its threshold by 0.02 bit.
 
-    References
-    ----------
-    S. ten Brink, G. Kramer, A. Ashikhmin, "Design of low-density
-    parity-check codes for modulation and detection," IEEE Trans. Commun.
-    52(4), 2004.
-
     Examples
     --------
     >>> code = LDPCCode.dvbs2("1/2", "short")

{commkit-3.6.1 → commkit-3.7.0}/commkit/coding/linear.py

@@ -236,8 +236,7 @@ class Chase:
     ``sum_i (1 - 2 c_i) LLR_i`` is the decision.  The soft output of bit
     ``i`` is half the metric difference between the best candidates with
     ``c_i = 0`` and ``c_i = 1`` (max-log), or, when no candidate disagrees
-    with the decision there, ``beta`` with the decision's sign (Pyndiah,
-    1998).  For codes with a hard decoder: linear block codes and BCH codes.
+    with the decision there, ``beta`` with the decision's sign.  For codes with a hard decoder: linear block codes and BCH codes.
 
     Parameters
     ----------

{commkit-3.6.1 → commkit-3.7.0}/commkit/coding/polar.py

@@ -10,8 +10,8 @@ list decoding (CA-SCL).  Encoding is ``n`` butterfly passes on the data's
 device.
 
 Decoding is successive cancellation (:class:`SC`) or its list version
-(:class:`SCL`), with min-sum check-node updates and the path metric of
-Balatsoukas-Stimming et al. (2015): sequential per codeword, so Numba over
+(:class:`SCL`), with min-sum check-node updates and an LLR-based path
+metric: sequential per codeword, so Numba over
 codewords on the CPU, and GPU input makes one round trip.  LLRs and partial
 sums are kept level by level in buffers of ``2N`` (level ``s`` at offsets
 ``2^s ... 2^(s+1) - 1``), so a list path is copied in ``O(N)``.

{commkit-3.6.1 → commkit-3.7.0}/commkit/coding/shaping.py

@@ -7,10 +7,8 @@ target distribution, invertibly.  Both classes are code objects, so
 (Maxwell-Boltzmann priors, ``Constellation.shaped``) is in
 :mod:`commkit.mapping.shaping`.
 
-:class:`CCDM` (constant-composition distribution matching, Schulte and
-Böcherer, 2016) maps ``k`` bits to ``num_symbols`` points whose counts are
-fixed: the composition that best approximates the constellation's pmf
-(Böcherer and Geiger, 2016).  Each block of bits selects a point of
+:class:`CCDM` (constant-composition distribution matching) maps ``k`` bits to ``num_symbols`` points whose counts are
+fixed: the composition that best approximates the constellation's pmf.  Each block of bits selects a point of
 ``[0, 1)``; the sequences of that composition partition ``[0, 1)`` by
 arithmetic coding over the remaining counts, and the matcher outputs the
 sequence whose interval holds the point.  The coder is a 64-bit range coder:
@@ -24,8 +22,7 @@ sequential recursion per block: Numba over blocks on the CPU; GPU input to
 :func:`~commkit.coding.decode` makes one round trip, and ``generate`` runs
 it on the host before moving the payload.
 
-:class:`PAS` (probabilistic amplitude shaping, Böcherer, Steiner and
-Schulte, 2015) combines a CCDM over the amplitudes of one real dimension
+:class:`PAS` (probabilistic amplitude shaping) combines a CCDM over the amplitudes of one real dimension
 with a systematic FEC code, whose parity bits supply the signs.  It needs
 labels with a sign bit per real dimension and the same amplitude label for
 ``±a``: Gray QAM and bipolar PAM as the factories build them.
@@ -202,7 +199,7 @@ class CCDM(_Code):
 
 
 def _composition(pmf: np.ndarray, n: int) -> np.ndarray:
-    """KL-optimal counts ``c`` (sum ``n``) for ``pmf`` (Böcherer and Geiger)."""
+    """KL-optimal counts ``c`` (sum ``n``) for ``pmf``."""
     p = np.asarray(pmf, dtype=np.float64)
     c = np.floor(n * p).astype(np.int64)
     for _ in range(n - int(c.sum())):

{commkit-3.6.1 → commkit-3.7.0}/commkit/equalization/_block/_blind.py

@@ -86,7 +86,7 @@ def _block_fdaf_blind(
     pilot positions overridden by the LMS residual.  ``r2`` is the Godard radius
     (CMA) and ``radii_np`` the unique ring radii (RDE), decided by their
     squared midpoints (``_rde_rings``).  ``step_size=None``
-    is the default of both, ``min(1e-3, 0.5 / block_size)``.
+    is the default of both, ``min(1e-3, 0.5 / block_size) / sps``.
     """
     use_pilots = pilot_ref is not None and pilot_mask is not None
     equalizer = f"block_{kind}"
@@ -105,7 +105,7 @@ def _block_fdaf_blind(
         pilot_gain_db=pilot_gain_db,
     )
     xp, C, n_sym, sps = run.xp, run.C, run.n_sym, run.sps
-    mu = min(1e-3, 0.5 / run.block_size) if step_size is None else step_size
+    mu = min(1e-3, 0.5 / run.block_size) / sps if step_size is None else step_size
     logger.info(
         "%s: C=%s, num_taps=%s, sps=%s, block_size=%s, fftsize=%s, mu=%s, "
         "n_sym=%s, pilot_aided=%s",
@@ -312,7 +312,7 @@ def block_cma(
         Step size on the scale of :func:`cma`.  The weights are frozen
         across each block, so the stability ceiling is about ``block_size``
         times lower than per symbol; reduce it if the run raises divergence.
-        Defaults to ``min(1e-3, 0.5 / block_size)``, as for
+        Defaults to ``min(1e-3, 0.5 / block_size) / sps``, as for
         :func:`block_rde`.
     block_size : int, default 256
         Output symbols per weight update.
@@ -396,9 +396,9 @@ def block_rde(
     step_size : float, optional
         Step size on the scale of :func:`rde`, with the about ``block_size``
         times lower stability ceiling of frozen-block adaptation.  Defaults
-        to ``min(1e-3, 0.5 / block_size)``: the per-symbol step, capped at
-        half the ceiling (``step_size * block_size`` below about 1) for large
-        blocks.
+        to ``min(1e-3, 0.5 / block_size) / sps``: the per-symbol step, capped
+        at half the ceiling (``step_size * block_size * sps`` below about 1,
+        on input normalized to unit mean power) for large blocks.
     block_size : int, default 256
         Output symbols per weight update.
     constellation : Constellation, optional

{commkit-3.6.1 → commkit-3.7.0}/commkit/equalization/_block/_dd.py

@@ -23,6 +23,7 @@ from ..result import (
     EqualizerResult,
     EqualizerState,
     _attach_equalized_signal,
+    _check_decision_power,
     _log_equalizer_exit,
 )
 from ._engine import (
@@ -386,12 +387,13 @@ def block_lms(
         ``block_size``.
 
         Because the weights are frozen across the block, the stability
-        ceiling falls as ``1/block_size``: ``μ·block_size`` must stay below
-        about 1.5 (whatever ``num_taps`` and the channel count).  The default
-        ``min(0.5 / block_size, 8e-3)`` sits at a quarter of that ceiling,
-        where convergence takes a few blocks and the steady-state MSE is
-        within a few tenths of a dB of the best step; for ``block_size``
-        below 64 the cap ``8e-3`` limits the per-symbol misadjustment.
+        ceiling falls as ``1/block_size``: on input normalized to unit mean
+        power, ``μ·block_size·sps`` must stay below about 1.5 (whatever
+        ``num_taps`` and the channel count).  The default
+        ``min(0.5 / block_size, 8e-3) / sps`` sits at a quarter of that
+        ceiling, where convergence takes a few blocks and the steady-state
+        MSE is within a few tenths of a dB of the best step; for
+        ``block_size`` below 64 the cap limits the per-symbol misadjustment.
     block_size : int, default 256
         Output symbols per weight update.  Larger blocks use the GPU better
         but adapt more slowly.  Independent of the BPS window
@@ -399,7 +401,14 @@ def block_lms(
     constellation : Constellation, optional
         Decision constellation, at unit power (a shaped constellation brings
         its pmf).  Defaults to the Signal's ``constellation``; required for
-        array input.
+        array input.  A WARNING is logged when the decided symbols of the
+        last half of the decision-directed output lack its power by more
+        than 1.5 dB: a lock at a wrong gain, or a constellation that does
+        not match the signal.  An explicit choice applies to this call
+        only: ``signal`` of the result keeps the input Signal's
+        ``constellation``, which describes its reference symbols, so pass
+        the same choice to the metrics, or set it on the Signal with
+        ``replace`` (with matching reference symbols) before equalizing.
     store_weights : bool, default False
         Record the weights at the start of every block in
         ``weights_history``.
@@ -465,7 +474,7 @@ def block_lms(
     **Stability.**  ``step_size`` multiplies the gradient summed (not
     averaged) over the block.  That keeps ``μ`` on the scale of :func:`lms`
     (the same ``μ`` converges at the same speed per symbol), but it makes the
-    stability ceiling, ``μ·block_size`` below about 1.5, about
+    stability ceiling, ``μ·block_size·sps`` below about 1.5, about
     ``block_size`` times lower than for per-symbol LMS, because the weights
     are frozen across the block.  Above the ceiling the run diverges (NaN
     weights, detected at the end, raise) or stays bounded without
@@ -553,7 +562,7 @@ def block_lms(
     xp, C, n_sym, sps, block_size = run.xp, run.C, run.n_sym, run.sps, run.block_size
     num_taps = run.num_taps
     training = run.training
-    mu = min(0.5 / block_size, 8e-3) if step_size is None else step_size
+    mu = min(0.5 / block_size, 8e-3) / sps if step_size is None else step_size
 
     if constellation is None:
         raise ValueError(
@@ -757,18 +766,19 @@ def block_lms(
         raise RuntimeError(
             f"block_lms diverged (step_size={mu}, block_size={block_size}). "
             f"Because the weights are frozen across the block, step_size * "
-            f"block_size must stay below about 1.5; the default "
-            f"min(0.5 / block_size, 8e-3) = {min(0.5 / block_size, 8e-3):.2e} "
-            f"sits at a quarter of that ceiling."
+            f"block_size * sps must stay below about 1.5; the default "
+            f"min(0.5 / block_size, 8e-3) / sps = "
+            f"{min(0.5 / block_size, 8e-3) / sps:.2e} sits at a quarter of that "
+            f"ceiling."
         )
     weights, carrier = snap[0]
     state_out = _block_state(
         run, equalizer="block_lms", cpr=cpr, weights=weights, carrier=carrier
     )
     result = _assemble_block(run, y_all, e_all, w_hist, phi_all, n_train, state_out)
-    return _attach_equalized_signal(
-        _log_equalizer_exit(result, name="Block-LMS"), sig, state
-    )
+    result = _log_equalizer_exit(result, name="Block-LMS")
+    result = _check_decision_power(result, constellation, "block_lms()")
+    return _attach_equalized_signal(result, sig, state)
 
 
 def _block_bps(

{commkit-3.6.1 → commkit-3.7.0}/commkit/equalization/_block/_engine.py

@@ -248,7 +248,6 @@ def _prepare_block(
     samples, training_symbols, eq_norm = _normalize_inputs(
         samples,
         training_symbols,
-        sps,
         input_norm_factor=None if state is None else state.input_norm_factor,
     )
 

{commkit-3.6.1 → commkit-3.7.0}/commkit/equalization/_common.py

@@ -22,15 +22,21 @@ from .result import EqualizerResult, EqualizerState
 
 
 def _normalize_inputs(
-    samples: Any, training_symbols: Any, sps: int, input_norm_factor: Any = None
+    samples: Any, training_symbols: Any, input_norm_factor: Any = None
 ) -> tuple[Any, Any, Any]:
-    """Scale samples to unit symbol power; training symbols pass through.
-
-    At more than one sample per symbol the timing phase is unknown, and the
-    strided power ``samples[..., ::sps]`` can land on zero crossings of the
-    Nyquist pulse, underestimating the power and destabilizing the
-    adaptation.  The power of all samples over the whole record is used
-    instead; it does not depend on whether training symbols are given.
+    """Scale samples to unit mean power per channel; training symbols pass.
+
+    The automatic gain control in front of the equalizer: each channel is
+    divided by its RMS over the whole record, so the regressor has unit
+    power per tap and a centre tap of 1 hands the slicer the samples at
+    about the constellation's unit power.  After a matched filter the
+    samples at the symbol instants have the symbols' power and those
+    between them ``1 - β/2`` of it for a raised-cosine response of roll-off
+    ``β``, so unit mean power puts the symbol instants within ``β/4`` of
+    unit power, at any timing phase.  (The transmit convention ``E|x|² =
+    1/sps`` describes energy per symbol spread over ``sps`` samples; applied
+    here it would hand the slicer a gain of ``1/sqrt(sps)``, below the
+    decision margins of 64-QAM and unipolar PAM-4.)
 
     Parameters
     ----------
@@ -38,8 +44,6 @@ def _normalize_inputs(
         Complex samples, ``(N,)`` or ``(C, N)``, NumPy or CuPy.
     training_symbols : array_like or None
         Training symbols at one sample per symbol, ``(K,)`` or ``(C, K)``.
-    sps : int
-        Samples per symbol.
     input_norm_factor : float or numpy.ndarray, optional
         Factor to divide by instead of measuring the RMS: the
         ``EqualizerResult.input_norm_factor`` of an earlier call, to keep
@@ -49,15 +53,13 @@ def _normalize_inputs(
     Returns
     -------
     samples : ndarray
-        The samples at unit symbol power, same shape and device.
+        The samples at unit mean power, same shape and device.
     training_symbols : ndarray or None
         Unchanged: known symbols are already on the constellation's scale.
     input_norm_factor : float or numpy.ndarray
-        Per-channel factor ``rms(channel)·sqrt(sps)`` the samples were divided
-        by: a ``float`` for SISO, ``(C,)`` for MIMO.  Stored in
-        ``EqualizerResult.input_norm_factor``, so that another capture (vacuum
-        noise) passed through the same frozen taps can be put on the same
-        absolute power scale.
+        Per-channel RMS ``sqrt(mean(|x_c|²))`` the samples were divided by:
+        a ``float`` for SISO, ``(C,)`` for MIMO.  Stored in
+        ``EqualizerResult.input_norm_factor``.
     """
     if input_norm_factor is not None:
         # Caller supplies scale - skip RMS and just apply it.
@@ -82,7 +84,7 @@ def _normalize_inputs(
 
     ref_samples = samples
 
-    norm_vec = _rms(ref_samples, axis=-1) * (sps**0.5)
+    norm_vec = _rms(ref_samples, axis=-1)
     if samples.ndim == 1:
         input_norm_factor = float(norm_vec)
         samples = samples / float(norm_vec)