commkit 3.2.0__tar.gz → 3.3.0__tar.gz

{commkit-3.2.0 → commkit-3.3.0}/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.3.0}/CHANGELOG.md

@@ -4,6 +4,51 @@ Notable changes to CommKit, newest first. Performance figures are from the refer
 
 ## [Unreleased]
 
+## [3.3.0] - 2026-11-03
+
+Numerical filter responses and plots built for comparisons. `filter_response`, `impulse_response` and `step_response` evaluate any FIR, SOS or `(b, a)` filter on its device; the multi-panel diagnostics draw one selected panel, and every plot can overlay several results on one axis. The example notebooks explain what each result shows.
+
+### Changes that may need code updates
+
+- `plot_filter_response` raises `ValueError` when `ax` holds other than four axes for the dashboard (or one for a selected `quantity=`), as the other multi-panel plots do; it used to log a warning and open a new figure. Pass the right number of axes, or none.
+
+### Added
+
+- `filter_response` (returning a `FilterResponse` of frequencies, complex response and group delay), `impulse_response` and `step_response` compute the responses of FIR taps, second-order sections or a `(b, a)` pair on the coefficients' device. The group delay of SOS filters is summed section by section, so high orders keep their accuracy; real IIR time responses run through `iir_filter`, in double-precision state whatever the coefficients' precision.
+- Multi-panel diagnostics (`plot_filter_response`, `plot_equalizer_result`, `plot_zf_equalizer_response`, `plot_llr_distribution`, `plot_parity_check`, `plot_timing_correlation`, `plot_mm_autocorrelation`, `plot_frequency_offset_blockwise_result`, `plot_pilot_phase_estimate`, `plot_pilot_tone_phase_estimate`, `plot_pilot_tones_phase_estimate`) take `quantity=` to draw one panel on one axis.
+- Comparisons on one axis: the single-panel plots and a selected `quantity=` take `label=`, `xlim=`, `ylim=` and `legend=` (`True` shows, `False` hides, `None` keeps the plot's default), and the plots with fits, guides or markers take `annotations=False` to draw only the measured curves of an overlay. `plot_eye_diagram(quantity="i" | "q")` draws one component; `plot_carrier_phase_characterization` accepts existing axes.
+- The example notebooks explain what each receiver result shows, their subplot grids scale the theme's figure size, and notebooks 13 and 16 overlay filter, smoothing, shaping and equalizer comparisons on one axis.
+
+### Development
+
+- The transfer audit documents the Tikhonov smoother's host round trip, which it flagged as undocumented.
+- `bench_filter_response` times responses on the DFT grid and on an arbitrary grid at 31, 257 and 4097 taps.
+
+## [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
 
 EXIT analysis and coding diagnostics. EXIT charts for any soft-in soft-out component, measured through the existing decoders or the demapper, or in closed form for LDPC codes with their threshold; plots of LLR distributions, parity-check matrices and EXIT charts; and INFO logging in the modules where it was missing. Nothing changes for existing code.
@@ -318,7 +363,9 @@ 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.3.0...HEAD
+[3.3.0]: https://github.com/lokgar/commkit/compare/v3.2.1...v3.3.0
+[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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: commkit
-Version: 3.2.0
+Version: 3.3.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
@@ -49,7 +49,7 @@ CommKit covers the receiver chain of coherent and IM/DD links (waveform generati
 
 ## The model
 
-Data is a NumPy or CuPy array, or a `Signal` that wraps the samples together with what is known about them. Algorithms are plain functions that take the data and return a new `Signal` or array, or a typed result such as `EqualizerResult` or an `*Estimate`. Plotting functions draw those results; they never compute them.
+Data is a NumPy or CuPy array, or a `Signal` that wraps the samples together with what is known about them. Algorithms are plain functions that take the data and return a new `Signal` or array, or a typed result such as `EqualizerResult` or an `*Estimate`. Plotting functions draw those results or call the public compute functions needed to produce them.
 
 - **Things that describe** a modulation, a pulse or a sub-algorithm are small frozen objects written in the call: `lms(rx, cpr=BPS(test_phases=64))`. The same object works standalone: `correct_carrier_phase(y, BPS())`.
 - **A `Signal` carries facts and ground truth.** Facts are `sampling_rate`, `symbol_rate`, `center_frequency` and `domain`; the carrier of an optical Signal gives its `center_wavelength_nm`, which dispersion, fiber propagation and OSNR noise read. The description is `constellation` and `pulse`. The ground truth is `reference`: the transmitted symbols, the bits on the air and the source bits before coding or distribution matching (the same array when there is neither). Functions take facts from the Signal and raise on a conflicting argument. Choices such as the decision constellation default to the Signal's and can be overridden.
@@ -87,6 +87,32 @@ res2 = ck.equalization.lms(rx, num_taps=21, step_size=1e-3, cpr=cpr, state=res.s
 
 Without CuPy, pass `device="cpu"` (the default): the same code runs on the CPU.
 
+## Comparing filter responses
+
+Calculate a response on the coefficients' device, or overlay selected panels
+of several filters:
+
+```python
+short = ck.filtering.fir_taps(sampling_rate=1e6, num_taps=21, cutoff=100e3)
+long = ck.filtering.fir_taps(sampling_rate=1e6, num_taps=101, cutoff=100e3)
+response = ck.filtering.filter_response(long, sampling_rate=1e6)
+print(response.frequencies, response.response, response.group_delay)
+
+ck.plotting.apply_default_theme()
+_, ax = ck.plotting.plot_filter_response(
+    short, sampling_rate=1e6, quantity="magnitude", label="21 taps"
+)
+ck.plotting.plot_filter_response(
+    long, sampling_rate=1e6, quantity="magnitude", ax=ax,
+    label="101 taps", legend=True, show=True,
+)
+```
+
+See notebook 03 for filter and smoothing comparisons. The multi-panel
+equalizer, timing, recovery and coding diagnostics take `quantity=` in the
+same way: draw a second result on the returned axis with its own `label=`,
+and `annotations=False` to leave out repeated fits and guides.
+
 ## CPU and GPU
 
 CommKit never picks a device for you: data stays where you put it, and each function runs on the device of its input. A few habits get the speed out of a GPU:
@@ -116,7 +142,7 @@ CommKit never picks a device for you: data stays where you put it, and each func
 | --- | --- |
 | [`commkit.core`](https://github.com/lokgar/commkit/tree/main/commkit/core) | `Signal`, `Reference`, `generate` (uniform, shaped through a distribution matcher, or coded with `code=`), `SingleCarrierFrame` and `Preamble` (pilots, guard intervals, MIMO channels), `extract_payload`. |
 | [`commkit.mapping`](https://github.com/lokgar/commkit/tree/main/commkit/mapping) | `Constellation` (QAM, PSK, PAM, arbitrary points; Gray labels; probabilistic shaping with `.shaped()`), bit mapping, hard demapping, max-log and exact LLRs. |
-| [`commkit.filtering`](https://github.com/lokgar/commkit/tree/main/commkit/filtering) | Pulses (`RRC`, `RC`, `Gaussian`, `Rect`, `SmoothRect`), FIR and IIR design (Butterworth, Chebyshev I/II, elliptic, Bessel), `fir_filter`, `iir_filter`, `matched_filter`, overlap-save, chromatic-dispersion compensation and digital backpropagation (`correct_fiber_propagation`). |
+| [`commkit.filtering`](https://github.com/lokgar/commkit/tree/main/commkit/filtering) | Pulses (`RRC`, `RC`, `Gaussian`, `Rect`, `SmoothRect`), FIR and IIR design (Butterworth, Chebyshev I/II, elliptic, Bessel), numerical filter responses, `fir_filter`, `iir_filter`, `matched_filter`, overlap-save, chromatic-dispersion compensation and digital backpropagation (`correct_fiber_propagation`). |
 | [`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-3.2.0 → commkit-3.3.0}/README.md

@@ -13,7 +13,7 @@ CommKit covers the receiver chain of coherent and IM/DD links (waveform generati
 
 ## The model
 
-Data is a NumPy or CuPy array, or a `Signal` that wraps the samples together with what is known about them. Algorithms are plain functions that take the data and return a new `Signal` or array, or a typed result such as `EqualizerResult` or an `*Estimate`. Plotting functions draw those results; they never compute them.
+Data is a NumPy or CuPy array, or a `Signal` that wraps the samples together with what is known about them. Algorithms are plain functions that take the data and return a new `Signal` or array, or a typed result such as `EqualizerResult` or an `*Estimate`. Plotting functions draw those results or call the public compute functions needed to produce them.
 
 - **Things that describe** a modulation, a pulse or a sub-algorithm are small frozen objects written in the call: `lms(rx, cpr=BPS(test_phases=64))`. The same object works standalone: `correct_carrier_phase(y, BPS())`.
 - **A `Signal` carries facts and ground truth.** Facts are `sampling_rate`, `symbol_rate`, `center_frequency` and `domain`; the carrier of an optical Signal gives its `center_wavelength_nm`, which dispersion, fiber propagation and OSNR noise read. The description is `constellation` and `pulse`. The ground truth is `reference`: the transmitted symbols, the bits on the air and the source bits before coding or distribution matching (the same array when there is neither). Functions take facts from the Signal and raise on a conflicting argument. Choices such as the decision constellation default to the Signal's and can be overridden.
@@ -51,6 +51,32 @@ res2 = ck.equalization.lms(rx, num_taps=21, step_size=1e-3, cpr=cpr, state=res.s
 
 Without CuPy, pass `device="cpu"` (the default): the same code runs on the CPU.
 
+## Comparing filter responses
+
+Calculate a response on the coefficients' device, or overlay selected panels
+of several filters:
+
+```python
+short = ck.filtering.fir_taps(sampling_rate=1e6, num_taps=21, cutoff=100e3)
+long = ck.filtering.fir_taps(sampling_rate=1e6, num_taps=101, cutoff=100e3)
+response = ck.filtering.filter_response(long, sampling_rate=1e6)
+print(response.frequencies, response.response, response.group_delay)
+
+ck.plotting.apply_default_theme()
+_, ax = ck.plotting.plot_filter_response(
+    short, sampling_rate=1e6, quantity="magnitude", label="21 taps"
+)
+ck.plotting.plot_filter_response(
+    long, sampling_rate=1e6, quantity="magnitude", ax=ax,
+    label="101 taps", legend=True, show=True,
+)
+```
+
+See notebook 03 for filter and smoothing comparisons. The multi-panel
+equalizer, timing, recovery and coding diagnostics take `quantity=` in the
+same way: draw a second result on the returned axis with its own `label=`,
+and `annotations=False` to leave out repeated fits and guides.
+
 ## CPU and GPU
 
 CommKit never picks a device for you: data stays where you put it, and each function runs on the device of its input. A few habits get the speed out of a GPU:
@@ -80,7 +106,7 @@ CommKit never picks a device for you: data stays where you put it, and each func
 | --- | --- |
 | [`commkit.core`](https://github.com/lokgar/commkit/tree/main/commkit/core) | `Signal`, `Reference`, `generate` (uniform, shaped through a distribution matcher, or coded with `code=`), `SingleCarrierFrame` and `Preamble` (pilots, guard intervals, MIMO channels), `extract_payload`. |
 | [`commkit.mapping`](https://github.com/lokgar/commkit/tree/main/commkit/mapping) | `Constellation` (QAM, PSK, PAM, arbitrary points; Gray labels; probabilistic shaping with `.shaped()`), bit mapping, hard demapping, max-log and exact LLRs. |
-| [`commkit.filtering`](https://github.com/lokgar/commkit/tree/main/commkit/filtering) | Pulses (`RRC`, `RC`, `Gaussian`, `Rect`, `SmoothRect`), FIR and IIR design (Butterworth, Chebyshev I/II, elliptic, Bessel), `fir_filter`, `iir_filter`, `matched_filter`, overlap-save, chromatic-dispersion compensation and digital backpropagation (`correct_fiber_propagation`). |
+| [`commkit.filtering`](https://github.com/lokgar/commkit/tree/main/commkit/filtering) | Pulses (`RRC`, `RC`, `Gaussian`, `Rect`, `SmoothRect`), FIR and IIR design (Butterworth, Chebyshev I/II, elliptic, Bessel), numerical filter responses, `fir_filter`, `iir_filter`, `matched_filter`, overlap-save, chromatic-dispersion compensation and digital backpropagation (`correct_fiber_propagation`). |
 | [`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-3.2.0 → commkit-3.3.0}/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.3.0}/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.3.0}/benchmarks/bench_filters.py

@@ -4,12 +4,15 @@
 (1% of the sampling rate, poles near z = 1) on dual-channel complex64; on the
 GPU it times the double-precision ``cupyx.scipy.signal`` path.
 ``bench_moving_average_valid`` smooths a two-channel float32 phase record.
+``bench_filter_response`` evaluates the response and group delay of
+low-pass FIRs on the default 4096-point grid (FFTs) and on an arbitrary
+grid of as many points (Horner evaluation).
 """
 
 import pytest
 from workloads import FS, bps_workload, phase_workload
 
-from commkit.filtering import butterworth_sos, iir_filter
+from commkit.filtering import butterworth_sos, filter_response, fir_taps, iir_filter
 from commkit.smoothing import moving_average
 
 ROUNDS = dict(rounds=3, warmup_rounds=1, iterations=1)
@@ -39,3 +42,18 @@ def bench_moving_average_valid(benchmark, backend_device, xp, sync, window):
         return out
 
     benchmark.pedantic(run, **ROUNDS)
+
+
+@pytest.mark.parametrize("grid", ["dft", "custom"])
+@pytest.mark.parametrize("num_taps", [31, 257, 4097])
+def bench_filter_response(benchmark, backend_device, xp, sync, num_taps, grid):
+    taps = fir_taps(sampling_rate=FS, num_taps=num_taps, cutoff=0.1 * FS)
+    taps = xp.asarray(taps, dtype=xp.float32)
+    frequencies = xp.linspace(-0.5, 0.5, 4096) if grid == "custom" else None
+
+    def run():
+        result = filter_response(taps, nfft=4096, frequencies=frequencies)
+        sync()
+        return result
+
+    benchmark.pedantic(run, **ROUNDS)

{commkit-3.2.0 → commkit-3.3.0}/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.3.0}/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.3.0}/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.3.0"
 
 from .backend import PrecisionWarning
 from .core import (

{commkit-3.2.0 → commkit-3.3.0}/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.3.0}/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.3.0}/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.3.0}/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.3.0}/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.3.0}/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.3.0}/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.3.0}/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.3.0}/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.3.0}/commkit/filtering/__init__.py

@@ -6,6 +6,9 @@
 - Design: :func:`fir_taps` (window method) and the IIR designs in
   second-order sections, :func:`butterworth_sos`, :func:`chebyshev1_sos`,
   :func:`chebyshev2_sos`, :func:`elliptic_sos` and :func:`bessel_sos`.
+- Responses: :func:`filter_response` (a :class:`FilterResponse`),
+  :func:`impulse_response` and :func:`step_response`, computed on the
+  coefficients' device.
 - Application: :func:`fir_filter` (FFT convolution, optionally circular),
   :func:`ols_fir_filter` (overlap-save, for long filters), :func:`iir_filter`
   and :func:`matched_filter`.
@@ -40,8 +43,10 @@ from .pulses import (
     Rect,
     SmoothRect,
 )
+from .response import FilterResponse, filter_response, impulse_response, step_response
 
 __all__ = [
+    "FilterResponse",
     "Gaussian",
     "Pulse",
     "RC",
@@ -55,9 +60,12 @@ __all__ = [
     "correct_chromatic_dispersion",
     "correct_fiber_propagation",
     "elliptic_sos",
+    "filter_response",
     "fir_filter",
     "fir_taps",
     "iir_filter",
+    "impulse_response",
     "matched_filter",
     "ols_fir_filter",
+    "step_response",
 ]