commkit 3.2.0__tar.gz → 3.2.1__tar.gz

{commkit-3.2.0 → commkit-3.2.1}/AGENTS.md

@@ -33,6 +33,7 @@ uv sync --all-extras                     # environment incl. GPU packages
 uv run nbstripout --install              # once per clone: strip notebook outputs on commit
 uv run pytest                            # CPU + GPU tests (default --device=all)
 uv run pytest --device=cpu               # what CI runs
+uv run pytest --run-slow                 # also the long statistical validation (marker slow)
 uv run pytest tests/equalization/ -k lms # subset
 uv run pytest --cov=commkit              # coverage
 NUMBA_DISABLE_JIT=1 uv run pytest tests/equalization tests/recovery \
@@ -111,7 +112,7 @@ uv run python benchmarks/record_baseline.py NAME   # record a new baseline
 
 **Release:**
 
-1. On `main`: the CPU and GPU suites pass with no failures or skips (`uv run pytest -rs`), `uv build` succeeds and `uv run --with twine twine check dist/*` passes.
+1. On `main`: the CPU and GPU suites pass with no failures or skips, slow validation included (`uv run pytest -rs --run-slow`; strict xfails, if any, are listed in §9), `uv build` succeeds and `uv run --with twine twine check dist/*` passes.
 2. `CHANGELOG.md`: a `## [X.Y.Z] - YYYY-MM-DD` section for the release, written for users. Changes that may need code updates come first, with how to migrate, then Added, Performance (measured, as a ratio of new to old time), Fixed and Development. Add its compare link at the bottom, and commit it.
 3. `uv run bump-my-version bump {patch|minor|major}`. This commits the new version and tags it `vX.Y.Z`.
 4. `git push origin main --tags`. The ruleset on `main` requires pull requests; repository admins bypass it for these two commits.
@@ -298,13 +299,24 @@ Docstrings describe the code as it is; a change in behavior updates them in the
 
 ## 7. Tests
 
-- **Fixtures:** use `backend_device`, `xp` and `xpt` from `tests/conftest.py`. Assert with `xpt.assert_allclose(...)`, because `numpy.testing` raises on CuPy arrays. Cast expectations with `xp.asarray`, and reductions with `float(...)`.
+- **Fixtures:** use `backend_device`, `xp` and `xpt` from `tests/conftest.py`. The GPU legs skip when CuPy is not installed, except under an explicit `--device=gpu`, which fails; an installed CuPy that does not work fails under any setting. That is the only skip: a test that does not belong to the selected run is deselected at collection (`pytest_collection_modifyitems`: `gpu_only` under `--device=cpu`, `cpu_only` under `--device=gpu`, `slow` without `--run-slow`), so a run with CuPy reports no skips, and a new test never calls `pytest.skip` for a configuration. Assert with `xpt.assert_allclose(...)`, because `numpy.testing` raises on CuPy arrays. Cast expectations with `xp.asarray`, and reductions with `float(...)`.
 - **Layout mirrors the source:** `tests/<subpackage>/test_<module>.py`, and `tests/test_<module>.py` for flat modules. Test basenames must be globally unique (pytest prepend import mode), hence names like `channel/test_channel_linear.py`. Split a large test file by concern.
 - **Shared builders** live in `tests/common/` and use the public API.
 - **Contract registry** (`tests/test_api_contracts.py`): every public function has a row. Generic checks run per row: array in/out, Signal in/out, device preserved, input not mutated, keyword-only parameters, `TypeError` on unsupported arrays, fact-conflict errors, return rules.
   - Do not duplicate these checks in per-module tests.
 - **Oracles:** sequential kernels are tested against plain-Python reference implementations in `tests/common/reference_impl.py`. CUDA kernels are tested against their CPU reference. Kernel tests skip only on the CPU parametrization (`skip_unless_gpu`), never because a kernel is unavailable, so a kernel that fails to compile fails its tests.
 - **Mathematical meaning:** test documented definitions, such as a pulse width, a dispersion sign, or noise-variance scaling, with independently derived expectations, not only shapes and energies.
+- **A test of what an algorithm achieves** (an equalizer converges, carrier recovery tracks, a decoder corrects, an estimator is calibrated) must fail on a plausibly wrong implementation:
+  - **Score against the truth**: the transmitted reference, the true phase, delay or offset, never the receiver's own decisions or another estimate from the same family. Constellation symmetry hides a wrong quadrant, a slip or a duplicated stream from a distance to the nearest point. `tests/common/scoring.py` has the helpers (`ser`, `blind_ser`, `phase_rms`, `block_rotations`, `stream_correlation`).
+  - **Resolve only the legitimate ambiguities**, each once over the whole scored interval: one rotation per stream (by the constellation's symmetry, or any angle for a phase-blind equalizer), one bijective channel permutation for blind MIMO, a documented fixed delay. Never per segment.
+  - **A baseline must fail**: the same test runs without the block it credits (step size 0, `cpr=None`, the corrector off, no compensation) and asserts that this fails.
+  - **Tolerances are derived**, from AWGN theory, a Cramér–Rao bound, a Wiener or loop-noise prediction or a binomial interval, and the docstring states the derivation and the measured value. `tests/common/theory.py` holds the closed forms, written with NumPy and SciPy only.
+  - **Real channels**: convergence tests use `make_channel_signal` (RRC pulses, ISI, a fractional delay, polarization rotation, DGD, AWGN). The repeat-upsampled builders have no channel and serve plumbing tests only.
+  - **Check the test by breaking the code**: while writing it, monkeypatch a plausible wrong result (zeros, a factor of two, the feature disabled) and confirm the test fails.
+  - A strengthened test that exposes a library fault is marked `pytest.mark.xfail(strict=True, reason=...)` with the measured numbers and listed in §9; the fix lands in its own commit, which removes the mark.
+- **Monte Carlo tests** state what their sample bounds (0 failures in 12 frames bounds the FER below 0.22 at 95 %) and check the operating point (the pre-FEC BER against theory). The default run keeps a cheap smoke size; a `slow` parametrization (deselected unless `--run-slow`) repeats it with enough trials to mean something.
+- **End-to-end chains** in `tests/test_receiver_chain.py` run several impairments and their receiver at once, scored against the source bits or AWGN theory, each with one correction left out as a failing baseline.
+- **Warnings are failures**: a WARNING from the `commkit` logger during a test fails it, unless the test is marked `allow_warnings` (it provokes a suspect result on purpose) or takes `caplog` to assert the log. There is no list of tolerated messages: a WARNING that reports what the caller asked for, not a suspect result, is a library log-level bug, fixed in the library.
 - **API changes never change expected values.** A commit that changes a signature only changes how tests call the code. Numerical changes land in their own commit with independent validation.
 - **Examples** are Jupyter notebooks in `examples/`, committed without outputs: `.gitattributes` routes them through the `nbstripout` filter, which each clone enables once with `uv run nbstripout --install` (git does not ship filter configuration). `tests/test_examples.py` executes each one, so an API change updates the notebooks in the same commit.
   - They form a course: one topic per notebook, named `NN-lowercase-words.ipynb`, numbered in teaching order (signals and DSP, channel and metrics, receiver algorithms, fiber systems, characterization). Each opens with what it covers, links the notebooks it builds on and ends with a link to the next. `examples/README.md` indexes them; a new notebook takes its place in the order and updates the index and the neighbors' links.
@@ -370,6 +382,10 @@ Steps, once CuPy 14.3 (with cp315 wheels for `cupy-cuda13x`) and a fixed `jupyte
 1. **oFEC** (OpenROADM, ITU-T G.709.3) is not implemented: its block structure is specified in the OpenROADM MSA documents, which were not available in a form to implement from. It would build on `BCHCode` (extended BCH(256, 239)), `Chase` with soft output and the staircase decoder's iteration over a window.
 2. **NR rate matching for polar codes** (sub-block interleaving, the circular buffer, puncturing and shortening with their frozen-set rules, parity-check bits) and **LTE rate matching for turbo codes** are not included: `PolarCode` and `TurboCode` are the mother codes. `Punctured` and `Shortened` cover generic rate matching.
 
+### Test suite: open items
+
+- **Standard tables against the standards.** The NR polar reliability sequence (TS 38.212 Table 5.3.1.2-1), the LTE QPP interleaver parameters (TS 36.212 Table 5.1.3-3) and the DVB-S2 and PON parity-check address tables are tested against commkit's own tables. They should be compared, in full, with fixtures under `tests/data/standards/` transcribed from the specification documents, each with a provenance header (document, version, table). ETSI's download pages refuse scripted access; the documents have to be supplied.
+
 ### Nonlinear fiber channel: future features
 
 Each is an addition that leaves the current API unchanged.

{commkit-3.2.0 → commkit-3.2.1}/CHANGELOG.md

@@ -2,7 +2,30 @@
 
 Notable changes to CommKit, newest first. Performance figures are from the reference machine (RTX 4070 Ti, Ryzen 7 7800X3D, WSL2) unless stated otherwise, as a ratio of new to old time (below 1 is faster).
 
-## [Unreleased]
+## [3.2.1] - 2026-11-02
+
+Fixes found by a rework of the test suite, which now checks what each algorithm achieves against the transmitted truth and theory. Five numerical defaults or models were wrong and change results (PLL cycle-slip repair, Tikhonov smoothing, `block_cma`'s step, `ols_fir_filter`'s alignment of even taps, `MthPower` near 0 Hz); no signature changes. Plots take their sizes from the theme.
+
+### Changes that alter results
+
+- **`Tikhonov` uses the actual variance of a Viterbi-Viterbi block phase** as its observation variance, computed from the constellation and `snr_db`: the noise through the M-th power plus the data self-noise of QAM. It used `1/(M²·SNR·N)`, too small by `M²/2` for PSK and by three to four orders of magnitude for QAM, so the smoother followed the raw block phases: on 16-QAM it now lowers the Viterbi-Viterbi error (static phase, 30 dB, 16-symbol blocks: 0.101 rad before and after smoothing, now 0.048 rad).
+- **`PLL(cycle_slip=CycleSlip())` defaults to a history of `8/μ` symbols** (twice the loop memory, between 10 and 640), standalone and inline in `lms` / `rls`; it used 640 symbols, as the block methods do. A PLL trajectory is smoothed by the loop, and the long linear fit lagged the phase noise enough to declare false slips: 16-QAM, `2π·Δν·T = 2π·1e-4`, 16 dB, `B·T = 2e-2`, four records of 2·10⁴ symbols: 10 rotation changes against the transmitted symbols with the repair, 3 without; now 3 with it. The repair does not undo the loop's own slips, which drift over about `1/(B·T)` symbols; the `CycleSlip` docstring says so. An explicit `history` is unchanged.
+- **`block_cma` defaults to `step_size=min(1e-3, 0.5 / block_size)`**, as `block_rde` does; it used 2e-4. On QPSK, where CMA and RDE are the same algorithm, the old default left the worst channel at 2.3 times the AWGN symbol error rate over the second half of 8·10⁴ symbols (dual polarization through rotation and DGD, Es/N0 10 dB; now 1.3 times) and at 16 times on 2·10⁴ symbols (now 2 times); on 16-QAM at 18 dB the SER of 2·10⁴-symbol records falls from 0.13 to 0.008. Above 2500-symbol blocks the new default is the smaller step, inside the stability ceiling that 2e-4 crossed (16-QAM, 4096-symbol blocks: SER 0.02 before, 0.004 now). Pass `step_size=2e-4` for the previous behavior.
+- **`ols_fir_filter` centres even-length taps on tap `(L - 1) // 2`**, as `fir_filter` (SciPy's `mode="same"`) does and as its docstring promised; it used `L // 2`, one sample later. Odd-length taps and `causal=True` are unchanged. The docstrings of both now state the centre tap; they said `L // 2`.
+
+- **Plots take line widths, marker sizes and fonts from the theme.** The plot functions no longer set their own line widths and marker sizes, so `apply_default_theme` and the user's rcParams control them; the theme's text is larger (16 pt, legends 14 pt, titles 18 pt) with longer ticks. SI-prefix tick labels show the prefix only (`10 k`, not `10 kHz`), as the axis labels already carry the unit.
+
+### Fixed
+
+- **`MthPower` estimates offsets near 0 Hz.** It zeroed bin 0 of the M-th power spectrum and, for constellations without a constant envelope, subtracted the mean of `x^M`, which for QAM is the tone itself: an offset with `|M Δf|` under half a bin was never found (QPSK, 4096 symbols at 1 MS/s: 0 Hz read as -82 kHz, 10 Hz as 30.5 Hz). Both steps are removed; at other offsets the estimates do not change, also with a DC offset of -20 dB in the input.
+- Messages that report what the caller asked for log at INFO, not WARNING, so a WARNING from commkit always means a suspect result: the block equalizers' advice to move CPU data to the GPU, RLS's tail trim, `correct_timing(mode="slice")` shortening the record and the plotting theme's font fallback. The advice to use more taps for fractionally spaced equalization is no longer logged at `sps=1`, where it does not apply.
+- `rls()`: `weights_history` has one row per returned symbol, so it matches `y_hat` after the tail trim (it kept the `num_taps // 2` trimmed rows). A run whose inverse correlation matrix loses positive definiteness (a forgetting factor far below 1) raises the documented `RuntimeError` instead of a bare `ZeroDivisionError` from the kernel, and the message now advises raising the forgetting factor toward 1, not lowering it.
+
+### Development
+
+- The test suite checks what the code achieves, not how it is written. Equalizers converge on RRC records through ISI, fractional delays, polarization rotation and DGD, scored against the transmitted symbols with only the legitimate rotation and permutation removed, and each "improves" test also runs a baseline that must fail; carrier recovery is scored against the true phase; estimators and metrics against Cramér–Rao bounds and AWGN theory; Chase and shortened-code decoding against brute force. New end-to-end receiver chains (coded single carrier, dual polarization, 80 km of fiber) each show that leaving out one correction breaks them. Monte Carlo tests state what their frame counts bound and gain `--run-slow` validation runs. A WARNING log from commkit fails the test. Tests that only repeated the contract registry's shape and device checks are removed.
+- The library faults these tests found are fixed above: the PLL's cycle-slip repair adding slips, Tikhonov's noise model on QAM, the dead zone of `MthPower` around 0 Hz, the alignment of even-length taps (`ols_fir_filter` against `fir_filter`) and RLS's `weights_history` length.
+- `benchutils.assert_converged` checks the symbol error rate of the worst channel (it compared bit errors before), and the 2048-tap block RDE benchmark uses a workload that converges.
 
 ## [3.2.0] - 2026-10-30
 
@@ -318,7 +341,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.2.0...HEAD
+[Unreleased]: https://github.com/lokgar/commkit/compare/v3.2.1...HEAD
+[3.2.1]: https://github.com/lokgar/commkit/compare/v3.2.0...v3.2.1
 [3.2.0]: https://github.com/lokgar/commkit/compare/v3.1.3...v3.2.0
 [3.1.3]: https://github.com/lokgar/commkit/compare/v3.1.2...v3.1.3
 [3.1.2]: https://github.com/lokgar/commkit/compare/v3.1.1...v3.1.2

{commkit-3.2.0 → commkit-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: commkit
-Version: 3.2.0
+Version: 3.2.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.2.0 → commkit-3.2.1}/benchmarks/bench_block_blind.py

@@ -31,16 +31,18 @@ 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 and is still settling
-# after the skipped symbols at 2048, hence its looser SER bound; its cost does
-# not depend on the data.
+# 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.
 STEP_SIZE = {
     ("cma", 256): 2e-4,
     ("cma", 2048): 3e-4,
     ("rde", 256): 3e-3,
-    ("rde", 2048): 7e-4,
+    ("rde", 2048): 4e-4,
 }
-MAX_SER = {"cma": 1e-2, "rde": 5e-2}
+SKIP = {("rde", 2048): 70_000}
+MAX_SER = {"cma": 1e-2, "rde": 1e-2}
 
 EQUALIZERS = [
     ("cma", block_cma),
@@ -66,7 +68,12 @@ def _bench_block_blind(benchmark, xp, sync, label, eq_fn, block_size):
 
     r = benchmark.pedantic(run, **ROUNDS)
     assert_converged(
-        r, syms, Constellation.qam(16), skip=20_000, max_ser=MAX_SER[label], blind=True
+        r,
+        syms,
+        Constellation.qam(16),
+        skip=SKIP.get((label, block_size), 20_000),
+        max_ser=MAX_SER[label],
+        blind=True,
     )
 
 

{commkit-3.2.0 → commkit-3.2.1}/benchmarks/bench_fiber.py

@@ -26,16 +26,18 @@ LINK = dict(
 )
 
 
+# The plain/fused split exists on the GPU only; its CPU items are deselected.
+PATHS = ["auto", pytest.param("plain", marks=pytest.mark.gpu_only)]
+
+
 def _stages(backend_device, monkeypatch, path):
     if path == "plain":
-        if backend_device != "gpu":
-            pytest.skip("the plain/fused split exists on the GPU only")
         monkeypatch.setattr(
             _fiber, "_make_ops", lambda x, xp, *args: _fiber._Ops(xp, x.dtype, *args)
         )
 
 
-@pytest.mark.parametrize("path", ["auto", "plain"])
+@pytest.mark.parametrize("path", PATHS)
 @pytest.mark.parametrize("n", [2**16, 2**20], ids=["N64k", "N1M"])
 def bench_fiber_propagation(benchmark, backend_device, xp, sync, monkeypatch, n, path):
     _stages(backend_device, monkeypatch, path)
@@ -49,7 +51,7 @@ def bench_fiber_propagation(benchmark, backend_device, xp, sync, monkeypatch, n,
     benchmark.pedantic(run, **ROUNDS)
 
 
-@pytest.mark.parametrize("path", ["auto", "plain"])
+@pytest.mark.parametrize("path", PATHS)
 @pytest.mark.parametrize("steps", [1, 10])
 def bench_dbp(benchmark, backend_device, xp, sync, monkeypatch, steps, path):
     _stages(backend_device, monkeypatch, path)

{commkit-3.2.0 → commkit-3.2.1}/benchmarks/benchutils.py

@@ -64,14 +64,22 @@ def assert_converged(result, syms, constellation, *, skip, max_ser, blind=False)
     storms, divergence) instead of the operating point, so every equalizer
     benchmark checks its symbol error rate after ``skip`` symbols.  Blind
     equalizers leave a phase ambiguity, which is resolved against the
-    reference first.
+    reference first, after the channel permutation of a butterfly.
     """
     from commkit.backend import to_device
-    from commkit.recovery import resolve_phase_ambiguity
+    from commkit.recovery import resolve_channel_permutation, resolve_phase_ambiguity
 
     y = to_device(result.y_hat, "cpu")[..., skip:]
     ref = to_device(syms, "cpu")[..., skip : skip + y.shape[-1]]
     if blind:
+        if y.ndim == 2:
+            y = resolve_channel_permutation(y, ref)
         y = resolve_phase_ambiguity(y, ref, constellation=constellation)
-    ser = float((constellation.demap(y) != constellation.demap(ref)).mean())
+    # Symbol decisions, not bits (one wrong symbol is one error), and the
+    # worst channel, so one failed stream cannot hide behind a good one.
+    wrong = constellation._nearest(y.reshape(-1)) != constellation._nearest(
+        ref.reshape(-1)
+    )
+    per_channel = to_device(wrong, "cpu").reshape(y.shape).mean(axis=-1)
+    ser = float(per_channel.max())
     assert ser <= max_ser, f"benchmark workload did not converge: SER {ser:.3g}"

{commkit-3.2.0 → commkit-3.2.1}/benchmarks/conftest.py

@@ -56,6 +56,20 @@ def pytest_generate_tests(metafunc):
         metafunc.parametrize("backend_device", params, indirect=True)
 
 
+def pytest_collection_modifyitems(config, items):
+    """Deselect, not skip, the CPU items of ``gpu_only`` parameters."""
+    cpu_only_gpu = [
+        item
+        for item in items
+        if item.get_closest_marker("gpu_only")
+        and getattr(item, "callspec", None) is not None
+        and item.callspec.params.get("backend_device") == "cpu"
+    ]
+    if cpu_only_gpu:
+        items[:] = [item for item in items if item not in cpu_only_gpu]
+        config.hook.pytest_deselected(items=cpu_only_gpu)
+
+
 @numba.njit(cache=True, parallel=True)
 def _spin(x):
     total = 0.0

{commkit-3.2.0 → commkit-3.2.1}/commkit/__init__.py

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

{commkit-3.2.0 → commkit-3.2.1}/commkit/coding/linear.py

@@ -247,7 +247,9 @@ class Chase:
         code, ``Syndrome(max_weight=1)`` rejects test words with two errors.
     beta : float, optional
         Soft-output magnitude of bits without a competitor; ``None`` takes
-        the largest competitor magnitude of the same word.
+        the largest competitor magnitude of the same word, or, when no
+        candidate of the word differs from the decision anywhere, the
+        word's largest input ``|LLR|``.
     """
 
     test_positions: int = 4

{commkit-3.2.0 → commkit-3.2.1}/commkit/equalization/_block/_blind.py

@@ -74,7 +74,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 block_rde's default, ``min(1e-3, 0.5 / block_size)``.
+    is the default of both, ``min(1e-3, 0.5 / block_size)``.
     """
     use_pilots = pilot_ref is not None and pilot_mask is not None
     equalizer = f"block_{kind}"

{commkit-3.2.0 → commkit-3.2.1}/commkit/equalization/_block/_engine.py

@@ -198,7 +198,7 @@ def _prepare_block(
 
     samples, xp, _ = dispatch(samples)
     if xp is np:
-        logger.warning(
+        logger.info(
             "%s is running on CPU (NumPy). For CPU workloads %s is typically "
             "faster. Move samples to GPU (CuPy) to benefit from block-FFT "
             "acceleration.",

{commkit-3.2.0 → commkit-3.2.1}/commkit/equalization/_common.py

@@ -328,7 +328,7 @@ def _unpack_result_numpy(
 
     w_history = None
     if store_weights:
-        w_history = xp.asarray(w_hist)
+        w_history = xp.asarray(w_hist if n_sym is None else w_hist[:n_sym])
         if was_1d:
             w_history = w_history[:, 0, 0, :]
 
@@ -375,7 +375,7 @@ def _validate_sps(sps: Any, num_taps: int) -> None:
             "proportionally more taps.",
             sps,
         )
-    if num_taps < 2 * sps:
+    if sps > 1 and num_taps < 2 * sps:  # fractionally spaced only
         logger.warning(
             "num_taps=%s is small for sps=%s. Recommend num_taps >= %s "
             "for fractionally-spaced equalization.",

{commkit-3.2.0 → commkit-3.2.1}/commkit/equalization/_numba_loops.py

@@ -150,6 +150,10 @@ def _rls_update(W, P, x_bar, e, Px, xH_P, k_gain, lam_f64, leak_term, update):
     denom = lam_f64
     for jj in range(N):
         denom = denom + (np.conj(x_bar[jj]) * Px[jj]).real
+    # A positive-definite P gives denom >= λ; anything else means P has lost
+    # it, and rls() reports the divergence.
+    if not denom > 0.0:
+        raise FloatingPointError("RLS inverse correlation matrix lost definiteness")
     inv_denom = np.float64(1.0) / denom
     for ii in range(N):
         k_gain[ii] = Px[ii] * inv_denom

{commkit-3.2.0 → commkit-3.2.1}/commkit/equalization/blind.py

@@ -79,7 +79,7 @@ def block_cma(
     *,
     num_taps: int = 21,
     sps: int | None = None,
-    step_size: float = 2e-4,
+    step_size: float | None = None,
     block_size: int = 256,
     constellation: Any = None,
     initial_taps: ArrayType | None = None,
@@ -113,10 +113,12 @@ def block_cma(
     sps : int, optional
         Samples per symbol, an integer.  Taken from the Signal; required for
         array input.  A value that disagrees with the Signal raises.
-    step_size : float, default 2e-4
+    step_size : float, optional
         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
+        :func:`block_rde`.
     block_size : int, default 256
         Output symbols per weight update.
     constellation : Constellation, optional

{commkit-3.2.0 → commkit-3.2.1}/commkit/equalization/result.py

@@ -170,7 +170,9 @@ class EqualizerResult:
     error : ndarray
         Error signal, ``(N_sym,)`` or ``(C, N_sym)``.
     weights_history : ndarray or None
-        Tap weights over time, only with ``store_weights=True``.
+        Tap weights over time, only with ``store_weights=True``: one row per
+        symbol of ``y_hat`` (RLS's trimmed tail included), the taps that
+        produced it.
     num_train_symbols : int
         Training symbols consumed in the data-aided phase (LMS/RLS); skip
         them before steady-state metrics such as EVM, SNR and BER.

{commkit-3.2.0 → commkit-3.2.1}/commkit/equalization/sequential/_dd.py

@@ -367,13 +367,17 @@ def _check_rls_divergence(
     actionable error instead of returning garbage weights.
     """
     if not bool(xp.isfinite(weights).all()):
-        raise RuntimeError(
-            f"RLS equalizer diverged (forgetting_factor={forgetting_factor}, "
-            f"regularization={regularization}). RLS requires a positive-definite "
-            "correlation matrix. "
-            "Try increasing 'regularization', reducing 'forgetting_factor', "
-            "or adding 'leakage' (e.g. 1e-4) to stabilize fractionally-spaced inputs."
-        )
+        raise RuntimeError(_rls_divergence_message(forgetting_factor, regularization))
+
+
+def _rls_divergence_message(forgetting_factor: float, regularization: float) -> str:
+    return (
+        f"RLS equalizer diverged (forgetting_factor={forgetting_factor}, "
+        f"regularization={regularization}). RLS requires a positive-definite "
+        "correlation matrix. "
+        "Try increasing 'regularization', raising 'forgetting_factor' toward 1, "
+        "or adding 'leakage' (e.g. 1e-4) to stabilize fractionally-spaced inputs."
+    )
 
 
 def rls(
@@ -477,7 +481,8 @@ def rls(
     Returns
     -------
     EqualizerResult
-        The fields described for :func:`lms`.  ``y_hat`` lacks the last
+        The fields described for :func:`lms`.  ``y_hat``, ``error``,
+        ``weights_history`` and ``phase_trajectory`` lack the last
         ``num_taps // 2`` symbols (``tail_trim``), and ``signal`` carries the
         reference cut to match.
 
@@ -565,7 +570,7 @@ def rls(
     n_update_halt = max(0, run.n_sym - num_taps // 2)
     tail_trim = num_taps // 2
     if tail_trim > 0:
-        logger.warning(
+        logger.info(
             "RLS tail trim: last %s symbols removed from y_hat "
             "(zero-padding contamination zone). result.signal carries the "
             "trimmed reference; trim reference arrays to match: "
@@ -663,7 +668,12 @@ def rls(
 
     # W and P freeze at n_update_halt, so the state resumes there at the latest.
     resume = min(run.n_done, n_update_halt)
-    snap = _run_resumable(run, resume, segment, snapshot)
+    try:
+        snap = _run_resumable(run, resume, segment, snapshot)
+    except FloatingPointError as err:  # raised by the kernel when P is no longer PD
+        raise RuntimeError(
+            _rls_divergence_message(forgetting_factor, regularization)
+        ) from err
     result = _assemble_sequential(
         run,
         equalizer="rls",

{commkit-3.2.0 → commkit-3.2.1}/commkit/equalization/sequential/_setup.py

@@ -397,7 +397,9 @@ def _inline_cpr(cpr: Any, constellation: Any, function_name: str) -> _InlineCpr
         joint=bool(cpr.joint_channels),
         symmetry=symmetry,
         cycle_slip=cycle_slip is not None,
-        history=slip._history_values(1),  # per-symbol phase
+        history=slip._history_values(  # per-symbol phase
+            1, cpr._slip_history if isinstance(cpr, PLL) else None
+        ),
         threshold=float(slip.threshold),
     )
 

{commkit-3.2.0 → commkit-3.2.1}/commkit/filtering/linear.py

@@ -387,8 +387,8 @@ def ols_fir_filter(
         is at least ``L`` samples long.
     causal : bool, default False
         By default the output is aligned as :func:`fir_filter` aligns it
-        (SciPy's ``mode='same'``, centered on tap ``L // 2``):
-        ``y[n] = sum_k x[n + L//2 - k]·taps[k]``, which removes the group
+        (SciPy's ``mode='same'``, centered on tap ``(L - 1) // 2``):
+        ``y[n] = sum_k x[n + (L-1)//2 - k]·taps[k]``, which removes the group
         delay of a symmetric filter before symbol sampling.  With ``True``
         the output is the causal convolution ``y[n] = sum_k x[n-k]·taps[k]``
         (``numpy.convolve(x, taps, mode='full')[:N]``), for a raw causal
@@ -412,7 +412,7 @@ def ols_fir_filter(
     A symmetric guard of ``nfft // 4`` samples is discarded from each
     block edge, so ``nfft // 4 >= len(taps)`` must hold.
 
-    Without ``causal`` the input is padded at the end by ``L // 2`` zeros
+    Without ``causal`` the input is padded at the end by ``(L - 1) // 2`` zeros
     and as many leading output samples are dropped, which costs at most one
     extra block.
     """
@@ -425,7 +425,7 @@ def ols_fir_filter(
     out_dtype = x.dtype  # capture before any reshape
 
     L = len(taps)
-    half = L // 2
+    half = (L - 1) // 2  # SciPy's mode='same' centre, as fir_filter
 
     x, was_1d = as_2d(x, name="samples")
 
@@ -473,7 +473,9 @@ def fir_filter(samples: S, taps: ArrayType, *, periodic: bool = False) -> S:
     """Apply an FIR filter along the time (last) axis.
 
     FFT convolution, ``mode="same"``: the output is centered on tap
-    ``len(taps) // 2``, so a symmetric filter adds no delay.  With
+    ``(len(taps) - 1) // 2``, ``y[n] = sum_k x[n + (L-1)//2 - k]·taps[k]``,
+    so a symmetric filter of odd length adds no delay (one of even length,
+    whose centre falls between two taps, half a sample).  With
     ``periodic=True`` the convolution is circular; away from the record ends
     both give the same samples.
 

{commkit-3.2.0 → commkit-3.2.1}/commkit/frequency.py

@@ -476,9 +476,6 @@ def _mth_power(
     # In the samples' precision: complex128 changed no estimate by more than
     # 0.005 Hz (16-QAM, 2^16 symbols, 15 dB; the error itself is 726 Hz rms).
     x_m = x**M
-    # Non-constant-envelope symbols leave an amplitude residual at DC.
-    if constellation is not None and np.ptp(np.abs(constellation.points)) > 1e-9:
-        x_m = x_m - xp.mean(x_m, axis=-1, keepdims=True)
 
     X_m = _fft.fft(x_m, n=nfft, axis=-1)  # (R, nfft)
     freqs_np = np.fft.fftfreq(nfft, d=1.0 / fs)  # reported on the host
@@ -494,7 +491,6 @@ def _mth_power(
         freqs = xp.fft.fftfreq(nfft, d=1.0 / fs)
         mask = (freqs >= tone_lo) & (freqs <= tone_hi)
         mag = xp.where(mask[None, :], mag, xp.zeros_like(mag))
-    mag[:, 0] = 0.0  # Δf = 0 is degenerate; also any residual DC
 
     if shared_rows:
         k_peak = xp.broadcast_to(xp.argmax(xp.sum(mag, axis=0)), (R,))

{commkit-3.2.0 → commkit-3.2.1}/commkit/plotting/analysis.py

@@ -92,8 +92,8 @@ def plot_frequency_drift(
         axi.axhline(amp_ref, color="white", ls="--", label="±amplitude")
         axi.axhline(-amp_ref, color="white", ls="--")
 
-    _set_eng_formatter(axi, "x", "s")
-    _set_eng_formatter(axi, "y", "Hz")
+    _set_eng_formatter(axi, "x")
+    _set_eng_formatter(axi, "y")
     axi.set_xlabel("Time [s]")
     axi.set_ylabel(r"$\Delta f$ [Hz]")
     axi.set_title(title)
@@ -232,7 +232,7 @@ def plot_frequency_noise_psd(
     model = getattr(estimate, "S_f_model", None)
     if model is not None:
         m_c = _as_channels(model)
-        axi.loglog(fp, m_c[0, pos], color="#ef476f", lw=1.5, label="Fitted model")
+        axi.loglog(fp, m_c[0, pos], color="#ef476f", label="Fitted model")
 
     used_label = "Fit bins" if model is not None else "Plateau bins (median)"
     if used is not None:
@@ -246,7 +246,6 @@ def plot_frequency_noise_psd(
                 S_c[0, pos][sel],
                 ".",
                 color="#06d6a0",
-                ms=3.0,
                 ls="none",
                 label=used_label,
             )
@@ -282,7 +281,7 @@ def plot_frequency_noise_psd(
         for edge in (lo, float(band[1])):
             axi.axvline(edge, color="#06d6a0")
 
-    _set_eng_formatter(axi, "x", "Hz")
+    _set_eng_formatter(axi, "x")
     axi.set_xlabel("Frequency [Hz]")
     axi.set_ylabel("$S_f$ [Hz²/Hz]")
     axi.set_title(title)
@@ -338,7 +337,6 @@ def plot_allan_deviation(
             tau,
             adv[i],
             "o-",
-            ms=3,
             color=f"C{i}",
             label=f"Pol {i}" if C > 1 else r"$\sigma_y(\tau)$",
         )
@@ -356,8 +354,8 @@ def plot_allan_deviation(
                 label=r"$\tau^{-1/2}$ (white-FM)",
             )
 
-    _set_eng_formatter(axi, "x", "s")
-    _set_eng_formatter(axi, "y", "Hz")
+    _set_eng_formatter(axi, "x")
+    _set_eng_formatter(axi, "y")
     axi.set_xlabel(r"Averaging Time $\tau$ [s]")
     axi.set_ylabel(r"Allan Deviation $\sigma_y(\tau)$ [Hz]")
     axi.set_title(title)
@@ -414,7 +412,6 @@ def plot_increment_variance(
             lag,
             v[i],
             "o",
-            ms=4,
             color=f"C{i}",
             label=f"Measured pol {i}" if C > 1 else "Measured",
         )
@@ -437,7 +434,7 @@ def plot_increment_variance(
             label=r"Intercept (noise $2\sigma_\phi^2$)",
         )
 
-    _set_eng_formatter(axi, "x", "s")
+    _set_eng_formatter(axi, "x")
     axi.set_xlabel("Increment Lag [s]")
     axi.set_ylabel("Variance [rad²]")
     axi.set_title(title)
@@ -517,7 +514,7 @@ def plot_dsh_beat_psd(
             label=f"$W_{{-{level_db:g}\\,dB}}$",
         )
 
-    _set_eng_formatter(axi, "x", "Hz")
+    _set_eng_formatter(axi, "x")
     axi.set_xlabel(
         "Frequency Offset from Beat Peak [Hz]"
         if f_peak is not None

{commkit-3.2.0 → commkit-3.2.1}/commkit/plotting/coding.py

@@ -158,7 +158,7 @@ def plot_llr_distribution(
         with np.errstate(divide="ignore"):
             ratio = np.log(h0[j][keep] / h1[j][keep]) + np.log(n1[j] / n0[j])
         label = "measured" if m == 1 else f"bit {j}"
-        ax_cons.plot(centers[keep], ratio, "o-", markersize=3, label=label)
+        ax_cons.plot(centers[keep], ratio, "o-", label=label)
         if keep.any():
             span = [min(span[0], centers[keep][0]), max(span[1], centers[keep][-1])]
     if span[0] > span[1]:
@@ -257,7 +257,7 @@ def plot_parity_check(
         ax_h.spy(h, markersize=size, aspect="auto", rasterized=True)
     if punctured:
         ax_h.axvspan(n - punctured - 0.5, n - 0.5, color="gray", alpha=0.3)
-        ax_h.text(n - punctured, -0.5, "punctured", va="bottom", fontsize=9)
+        ax_h.text(n - punctured, -0.5, "punctured", va="bottom")
     ax_h.tick_params(labeltop=False, labelbottom=True)
     ax_h.grid(False)
     ax_h.set_xlabel("Variable node (column)")
@@ -342,7 +342,6 @@ def plot_exit_chart(
             chart.trajectory[:, 0],
             chart.trajectory[:, 1],
             color="white",
-            linewidth=0.8,
             alpha=0.8,
             label="trajectory",
         )
@@ -358,5 +357,5 @@ def plot_exit_chart(
         state = "open" if chart.converges else "closed"
         title = f"EXIT chart: tunnel {state}, {chart.iterations} iterations"
     axi.set_title(title)
-    axi.legend(loc="lower right", fontsize=8)
+    axi.legend(loc="lower right")
     return _finish((fig, axi), show)

{commkit-3.2.0 → commkit-3.2.1}/commkit/plotting/equalizer.py

@@ -130,7 +130,6 @@ def plot_equalizer_result(
                     tap_idx,
                     np.abs(weights[i, j]),
                     marker="o",
-                    markersize=3,
                     label=label,
                 )
         ax_taps.legend(ncol=2)
@@ -138,8 +137,7 @@ def plot_equalizer_result(
         # SISO: (num_taps,) - stem plot
         num_taps = weights.shape[0]
         tap_idx = np.arange(num_taps) - (num_taps // 2)
-        markerline, _, _ = ax_taps.stem(tap_idx, np.abs(weights))
-        markerline.set_markersize(4)
+        ax_taps.stem(tap_idx, np.abs(weights))
 
     ax_taps.set_xlabel("Tap Index")
     ax_taps.set_ylabel("|w|")
@@ -241,7 +239,7 @@ def plot_zf_equalizer_response(
             axi.plot(f_sorted, 20 * np.log10(np.abs(data) + 1e-12), color=col)
             prefix = f"{row_label} " if row_label else ""
             axi.set_title(f"{prefix}{lbl}")
-            _set_eng_formatter(axi, "x", "Hz")
+            _set_eng_formatter(axi, "x")
             axi.set_xlabel("Frequency [Hz]")
             axi.set_ylabel("Magnitude [dB]")
 

{commkit-3.2.0 → commkit-3.2.1}/commkit/plotting/eye.py

@@ -108,7 +108,7 @@ def _plot_eye_traces(
         segments = np.empty((traces.shape[0], trace_len, 2))
         segments[:, :, 0] = t
         segments[:, :, 1] = traces
-        line_kwargs: dict[str, Any] = {"alpha": 0.2, "linewidth": 1, "color": "C0"}
+        line_kwargs: dict[str, Any] = {"alpha": 0.2, "color": "C0"}
         line_kwargs.update(kwargs)
         ax.add_collection(LineCollection(list(segments), **line_kwargs))
         y_lo, y_hi = float(traces.min()), float(traces.max())