commkit 1.1.0__tar.gz → 2.1.0__tar.gz

commkit-2.1.0/.gitattributes

@@ -0,0 +1 @@
+*.ipynb filter=nbstripout diff=ipynb

{commkit-1.1.0 → commkit-2.1.0}/.github/workflows/ci.yml

@@ -38,6 +38,22 @@ jobs:
       - name: Type check
         run: uv run mypy commkit/
 
+  notebooks:
+    name: Notebooks carry no outputs
+    # Outputs (plots are base64 PNGs) would bloat the repository. The
+    # nbstripout git filter strips them on commit once a clone runs
+    # 'uv run nbstripout --install'; this required check catches a clone
+    # without it before anything reaches main.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Every committed notebook is stripped
+        run: uvx nbstripout@0.9.1 --verify $(git ls-files '*.ipynb')
+
   test:
     name: Test (Python ${{ matrix.python-version }} | ${{ matrix.resolution }})
     runs-on: ubuntu-latest
@@ -68,7 +84,38 @@ jobs:
         run: uv sync --python ${{ matrix.python-version }} --resolution lowest-direct
         
       - name: Run tests (CPU) with coverage
-        run: uv run pytest --device=cpu --cov=commkit --cov-report=term-missing
+        # Floor = total at the start of the 2.0 work; raise it, never lower it.
+        run: uv run pytest --device=cpu --cov=commkit --cov-report=term-missing --cov-fail-under=78
+
+  kernel-coverage:
+    name: Numba kernel coverage (JIT disabled)
+    # Compiled Numba code is invisible to coverage, so the main job reports the
+    # kernels as almost untested. Here the same tests run the kernels as plain
+    # Python, measuring their real line coverage.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Sync environment
+        run: uv sync
+
+      - name: Run kernel tests with JIT disabled
+        env:
+          NUMBA_DISABLE_JIT: "1"
+        run: uv run pytest tests/equalization tests/recovery tests/test_frequency.py --device=cpu --cov=commkit --cov-report=
+
+      - name: Kernel coverage report
+        run: >-
+          uv run coverage report --show-missing --fail-under=85
+          --include="commkit/equalization/_kernels_numba.py,commkit/equalization/sequential/*,commkit/frequency.py,commkit/recovery/*"
 
 # 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-2.1.0/AGENTS.md

@@ -0,0 +1,264 @@
+# AGENTS.md
+
+Guide for anyone, human or coding agent, changing the **CommKit** repository.
+
+The rules below describe the code as it is. New code follows them; a change that breaks one changes this file in the same commit.
+
+---
+
+## 1. What CommKit is
+
+A Python library for digital-communications research: simulation, receiver DSP, metrics, plotting and experimental captures, on NumPy (CPU) and CuPy (GPU) data. It is **not differentiable**. A separate JAX library, *commax*, will hold the blocks that must sit inside a gradient. commax depends on commkit, never the reverse, and takes its conventions (`Constellation`, bit labels, pulse taps, frame layouts) from commkit.
+
+Users are researchers and engineers. Design for them:
+
+- **Algorithms are plain functions.** Data is a `Signal` or an array. Things that *describe* a modulation, a pulse or an embedded sub-algorithm are small frozen value objects written inline in the call:
+
+  ```python
+  res = lms(rx, num_taps=21, step_size=1e-3, cpr=BPS(test_phases=64))
+  ```
+
+- **Everything is expressed in Python.** No configuration files, registries, global switches or multi-step setup.
+- **We deliberately do not build** pipeline or receiver objects, DSP methods on `Signal`, string shorthands for constellations, or public "config objects per algorithm".
+
+---
+
+## 2. Commands
+
+Always use `uv`. Python 3.12+.
+
+```bash
+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 tests/equalization/ -k lms # subset
+uv run pytest --cov=commkit              # coverage
+NUMBA_DISABLE_JIT=1 uv run pytest tests/equalization tests/recovery \
+    tests/test_frequency.py --device=cpu --cov=commkit   # real kernel coverage
+```
+
+**Commit gate.** CI fails on any of these, so run all of them before every commit, with `ruff format` last:
+
+```bash
+uv run ruff check . --fix
+uv run mypy commkit/
+uv run pytest
+uv run ruff format .
+```
+
+**Benchmarks** are explicit-only; `uv run pytest` never collects them. A commit that changes a public signature also smoke-runs them once, without timing, so their call sites cannot rot unnoticed:
+
+```bash
+uv run pytest benchmarks/ --benchmark-disable --device=all
+```
+
+Timed runs:
+
+```bash
+uv run pytest benchmarks/bench_bps.py --benchmark-only --device=all
+uv run pytest benchmarks/ --benchmark-only --device=all \
+    --benchmark-compare=0003 --benchmark-storage=file://benchmarks/baselines
+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.
+2. `uv run bump-my-version bump {patch|minor|major}`. This commits the new version and tags it `vX.Y.Z`.
+3. `git push origin main --tags`.
+4. Publish a GitHub Release for the tag (`gh release create vX.Y.Z --generate-notes`). Publishing the release runs `.github/workflows/publish.yml`, which builds and uploads to PyPI through Trusted Publishing; pushing a tag alone publishes nothing.
+
+---
+
+## 3. Architecture
+
+Dependencies point downward only:
+
+| Layer | Modules | May import |
+| --- | --- | --- |
+| Infrastructure | `backend`, `logger`, `_cuda` | NumPy, CuPy |
+| Array and math helpers | `_array` (shape and validation), `math` (power, normalization, dB, linear trend) | infrastructure |
+| Value objects | `mapping.Constellation`, pulse classes, `recovery` CPR configs | layers above |
+| Core | `core` (`Signal`, frames, generation), `io` | layers above |
+| DSP | `mapping`, `filtering`, `multirate`, `spectral`, `smoothing`, `impairments`, `timing`, `frequency`, `recovery`, `equalization`, `metrics`, `analysis` | layers above, and lower DSP modules |
+| Presentation | `plotting` | everything; **nothing imports plotting** |
+
+- **Responsibilities:**
+  - `filtering` holds signal-chain filters with a real frequency response.
+  - `smoothing` holds display and estimation smoothers only.
+  - `analysis` holds laser and phase characterization.
+  - `metrics` is the reporting layer.
+- **Splitting modules:** promote a flat module to a package only when it exceeds about 1000 lines *and* has two or more separable concerns. The package `__init__` re-exports the public names. Never create a `utils/` package or one-function files.
+- **Placeholder modules are kept on purpose.** `commkit.coding` and `commkit.impairments.channel.nonlinear` are reminders of planned work. Never delete them or treat them as dead code. They are excluded from coverage and from the contract registry, and the README labels them "planned, not implemented".
+
+---
+
+## 4. API rules
+
+### Signal
+
+- `Signal` holds: samples (NumPy or CuPy, `(N,)` or `(C, N)`, time on the last axis), the **facts** `sampling_rate`, `symbol_rate` and `center_frequency`, the **description** `constellation` and `pulse`, and the ground truth `reference` (transmitted symbols and bits) plus the `frame` layout.
+- It never holds pipeline results.
+- 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. Arrays are shared, not copied; use `clone()` for an independent copy.
+- **Alignment invariant:** reference symbol *k* corresponds to symbol period *k* of the samples. Any function that drops or shifts symbol periods slices the reference to match. Metrics raise on mismatch; they never guess.
+
+### Function signatures
+
+- `f(data, other_data, *, params)`: everything after the data arguments is keyword-only. A function without data arguments may keep its single primary parameter positional (`barker_sequence(13)`, `gray_code(5)`); with several parameters, all are keyword-only (`rrc_taps(sps=2, rolloff=0.1, span=10)`). The data-argument count is recorded per function in the contract registry.
+- **Signal awareness.** A function whose main argument is waveform data (or a field a Signal really carries) accepts an array or a Signal. It unwraps once with `adapt_signal()` (in `core/_signal_adapter.py`), works on arrays, and returns through `wrap_samples()`. Never re-enter the public function recursively.
+  - Functions on *derived* quantities (phase trajectories, correlations, taps, PSD bins, results) and synthesis primitives stay array-only.
+- **Metadata rule: facts versus choices.**
+  - Facts (`sampling_rate`, `symbol_rate`, and so `sps`) come from the Signal. A conflicting argument raises `ValueError`; an equal one is fine.
+  - Choices (decision `constellation`, `noise_var`, `pulse`) default to the Signal's value, and an explicit argument wins.
+  - A missing fact for array input raises. Neither case warns.
+- Integer-SPS algorithms validate with `require_integer_sps()` before any cast. Never truncate 1.5 SPS to 1.
+- **Value objects are frozen dataclasses** with read-only NumPy arrays:
+  - `Constellation`: `.qam(M)`, `.psk(M)`, `.pam(M, unipolar=)`, or arbitrary `points`; `.shaped(nu=|entropy=)` keeps unit power. Functions accept the object only, never strings.
+  - Pulses: `RRC`, `RC`, `Gaussian`, `Rect`, `SmoothRect`. A raw taps array is accepted wherever a pulse is.
+  - Algorithm objects, one per estimation method (`BPS`, `PLL`, `ViterbiViterbi`, `MthPower`, `CycleSlip`, ...). The same object is used standalone (`correct_carrier_phase(y, BPS())`) and nested (`lms(..., cpr=BPS())`). It lives next to its kernel and validates its parameters on construction. Class names are unique across the package.
+  - Equalizer continuation uses `state=result.state`.
+- **Randomness:** `rng: int | np.random.Generator | None` (SciPy SPEC 7).
+  - What is transmitted (bits, symbols, pilots): draw on the host with the Generator, then transfer. A seed gives the same payload on CPU and GPU.
+  - What the channel adds (AWGN, phase noise): draw on the data's device through `_random.standard_normal`. Realizations differ between devices; statistics agree, and tests assert statistics.
+  - Never use a global RNG.
+- **Types:** a transform is written `def f(samples: S, ...) -> S` with the TypeVar `S` from `core/_signal_adapter.py` (bound to `np.ndarray | Signal`), so a Signal gives a Signal and an array an array. Do not reassign the `samples` parameter; name the unwrapped array `x`.
+- **Device follows the data.** There are no `backend=` arguments and no global switches. Unsupported array types (JAX, PyTorch) raise `TypeError`.
+  - Only factories with no input data to follow (`generate`, `generate_phase_noise`, `Preamble`/`SingleCarrierFrame.to_signal`, `load_npz`) take `device: str = "cpu"`, validated with `require_device()`. They draw randomness as the rule above says and do the vectorized work (mapping, shaping) on `device`. The default is never "GPU if available".
+- **No `debug_plot`.** Numerical code never imports plotting. Plot functions consume results or recompute through public compute functions.
+- **Design and apply are separate functions**, for example `rrc_taps` and `fir_filter`, or `butterworth_sos` and `iir_filter`.
+
+### Returns
+
+- **Transforms:** array in gives array out on the same device; Signal in gives a new Signal out (update `sampling_rate` when the rate changes).
+- **Estimators** reduce over the time axis by input rank: `(N,)` gives 0-d and `(C, N)` gives `(C,)`. Results stay on the input device.
+- **Analysis summaries** (`estimate_linewidth`, `allan_deviation`, the `frequency_drift` statistics) are reporting-layer fits on plot-sized reductions. Like the metrics, they return host floats or `(C,)` arrays. Sample-rate outputs (trajectories, PSDs, `dsh_phase`) stay on the input device.
+- **Metrics** (`evm`, `snr`, `ber`, `ser`, `gmi`, `mi`) return host values: a `float` for 1-D input and `np.ndarray (C,)` for 2-D input. They **raise** on empty selections; they never return `None` or `0.0` for "nothing measured". Metrics never silently align, rotate or permute against the reference.
+- **More than one value** is returned as a frozen dataclass with named fields. No dicts, and no tuples longer than two.
+- **Equalizers** return `EqualizerResult`. `y_hat` is always an array, `signal` holds the 1-SPS Signal for Signal input, `state` is the continuation state, and diagnostics are returned as data.
+
+### Naming
+
+| Prefix | Meaning |
+| --- | --- |
+| `apply_*` | add an impairment or apply a model |
+| `estimate_<quantity>(x, method)` | measure, never change the data; returns a frozen `<Quantity>Estimate` (value plus diagnostics) |
+| `correct_<quantity>(x, how)` | remove the impairment; returns only the corrected data. `how` is an estimate or an algorithm object (which estimates first) |
+| `resolve_*` | pick among discrete candidates (π/2 rotation, channel permutation); nothing else |
+| `generate` | synthesis from parameters, takes `rng` |
+| `plot_*` | every public plotting function (only `apply_default_theme` is exempt) |
+
+- The algorithm is chosen by an object, never by the function name or a string: `estimate_carrier_phase(y, BPS())`, not `recover_carrier_phase_bps(y)`. The verb function dispatches on the object's type through a private table in its module. There is no `recover_*` or `compensate_*`.
+- Computations use plain nouns (`allan_deviation`).
+- **Glossary**, one name each:
+  - `num_taps`, `step_size`, `sps`, `constellation`, `pulse`, `rng`, `num_symbols`, `num_channels`, `sampling_rate`, `symbol_rate`.
+  - Units are in the docstring. Use `_db` and `_hz` suffixes where the unit is ambiguous.
+
+### Errors and logging
+
+- Wrong input raises, with a message naming the argument.
+- `logger` is for diagnostics only. Per-channel logging that needs a device-to-host transfer is wrapped in `if logger.isEnabledFor(logging.INFO):`.
+- The library never configures handlers, Matplotlib or warning filters at import time.
+
+---
+
+## 5. Numerics
+
+- **Storage dtypes:** `complex64` for IQ samples and `float32` for real signals.
+- **Accumulation precision:**
+  - LMS/CMA/RDE: inputs and weights are `complex64`, but dot products and gradient updates in the hot loop are accumulated in `complex128`.
+  - RLS keeps `P`, the gain `k` and the regressor buffers in `complex128` throughout. Single precision loses the Hermitian positive-definite property and the filter diverges.
+  - Carrier phase: promote angles to `float64` before `xp.unwrap()`, because float32 rounding causes spurious quadrant slips. Tikhonov/Kalman block transitions also run in `float64`.
+- **Normalization invariant:** at `sps` samples per symbol, `E[|x|²] = 1/sps`; at symbol rate, `E[|x|²] = 1`. Any rate-changing block applies the exact gain correction.
+- **Shapes:** SISO is `(N,)` and MIMO is `(C, N)`. Use `as_2d`, `restore_1d`, `broadcast_channels` and `require_channels`; never hand-roll the promote/squeeze idiom.
+- **Reproducibility:** a seed is reproducible within a library version only. Tests and baselines assert statistics, never exact noise realizations.
+
+---
+
+## 6. Performance
+
+| Algorithm structure | Implementation | Device |
+| --- | --- | --- |
+| Vectorized: filters, resampling, spectra, impairments, metrics, LLR, frequency-domain equalizers | NumPy/CuPy via `x, xp, sp = dispatch(samples)` | follows the input |
+| Sequential recursions: LMS/RLS/CMA/RDE, PLL, Tikhonov, cycle slips | Numba `@njit(cache=True, fastmath=True, nogil=True)` | CPU; GPU input does one round trip to the host and back |
+| Hot spots limited by intermediates, launches or round trips | CUDA C++ via CuPy `RawModule` (`commkit/_cuda`) | GPU |
+
+**Host-sync hygiene:**
+
+- Never extract scalars from a possibly-GPU array inside a loop (`float(x[c])`, `.item()`). Compute the vector on the device, transfer it once with `to_device(v, "cpu")`, then loop on the host.
+- Prefer on-device gathers (`xp.take_along_axis`).
+- Chunk `(N, M)` intermediates over N with an on-device accumulator.
+- Reduce on the device before transferring, including for plotting.
+- Pass whole records to compiled code. There are no Python loops over symbols or small blocks, except inside a CUDA graph.
+
+**Kernel policy:**
+
+- A `.cu` kernel needs a benchmark showing that CuPy is limited by intermediates, launch count or round trips.
+- It optimizes a CPU reference (Numba or NumPy) and is tested against it with `--device=all`.
+- Wrappers check dtype, contiguity, shape and size before launch.
+- `float32` with explicit literals.
+- `--use_fast_math` only per kernel (through `options`), after an accuracy check; the compiler default does not pass it.
+- Short elementwise chains use `ElementwiseKernel` or `cupy.fuse`.
+- Sequential recursions over a whole record are never ported to the GPU; one record has no parallel work per step. A short per-block scan may be, as one launch, when it replaces a host round trip per block (`cs_block`, `bps_anchor`); keep its parallel part parallel (float64 is 1/64 of float32 throughput on consumer GPUs).
+
+---
+
+## 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(...)`.
+- **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.
+- **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.
+- **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.
+- **Coverage** must not drop below the CI floor. Numba kernel coverage is measured by a separate `NUMBA_DISABLE_JIT=1` job.
+
+---
+
+## 8. Benchmarks
+
+`benchmarks/` tracks the GPU-relevant hot paths. Baselines are committed under `benchmarks/baselines/`. The current reference is `0003` (`v2_0`) on the reference machine: RTX 4070 Ti, Ryzen 7 7800X3D, WSL2; `0002` (`pre_v2`) is the 1.x state. `0002` ran the CPR equalizer and Viterbi-Viterbi benchmarks on workloads that did not converge, so compare those only from `0003` on.
+
+- **Workloads must converge.** A workload the algorithm cannot handle times a failure mode (slip storms, divergence), not the operating point. Every equalizer benchmark asserts its symbol error rate with `benchutils.assert_converged`.
+- **Baselines** are recorded with `benchmarks/record_baseline.py`: each file in its own process, best of three passes. In one full-suite process, small GPU benchmarks after the large equalizer workloads ran 2-12x slower than alone, so never record a baseline from a single `pytest benchmarks/` run.
+
+- **IDs** are `[cpu]` or `[gpu]`, meaning the input device.
+- **Timing:**
+  - Timed bodies end with the `sync` fixture; otherwise GPU timings measure launches, not execution.
+  - Each benchmark has one warmup round, so compilation and pool growth are excluded.
+- **Workloads** come from `benchmarks/workloads.py` with fixed seeds; never generate data inline.
+- **Tools:** `benchmarks/benchutils.py` provides `CudaEventTimer` and `nvtx_range` for `nsys` profiling.
+- **Logging** is set to WARNING in `benchmarks/conftest.py`.
+- **Trust deltas, not single runs.** A ±20-40% swing has been seen under load. Re-run a suspected regression in isolation, or do a controlled A/B with at least 7 repetitions, alternating old and new per repetition and comparing the paired ratios. When even unchanged benchmarks move, time the changed part itself with `CudaEventTimer` and quote it against the step it sits in.
+- A commit touching a hot path quotes its delta against `0003`. Tolerance is 5% on CPU and 10% on GPU.
+
+---
+
+## 9. Roadmap and open items
+
+What is not done yet, in suggested order. Unlike the sections above, this is a to-do list, not a description of the code: remove an item in the commit that resolves it, and add one when a known gap is left open.
+
+### Planned modules
+
+1. **Nonlinear fiber channel** (`impairments.channel.nonlinear`, a placeholder). Split-step Fourier propagation of the Kerr effect together with chromatic dispersion, then digital backpropagation as its compensation counterpart in `filtering`. Comes first because it builds on what exists: the dispersion operator (`_dispersion`), overlap-save and FFT-heavy GPU code. It completes the coherent optical link model.
+2. **Channel coding** (`coding`, a placeholder package). Start with one soft decoder (LDPC) that consumes `compute_llr` output (positive LLR = bit 0) and reports post-FEC BER next to `gmi`, then add encoders. The package stays out of `commkit/__init__.py` until a real encode/decode entry point exists. Decoders are iterative message passing over many codewords: batch codewords on the GPU from the start.
+
+### Usability gaps
+
+- **`block_lms` default `step_size`** (2e-4) converges too slowly under strong polarization mixing (30 degrees needs about 3e-3 at `block_size=256`), and the stable step falls as `block_size` grows (5e-4 at 2048). Consider a default that scales with `block_size`, or at least a clearer warning when the error does not drop.
+- **RDE from a cold start** on 16-QAM settles at a few percent SER at large block sizes. CMA pre-convergence works today in two calls (`initial_taps=` or `state=` from a `cma`/`block_cma` result); a worked example in the docs or notebooks would make it discoverable.
+
+### Performance
+
+- **Exact LLRs on the CPU**: 256-QAM takes about 330 ms per 2^18 symbols (max-log about 18 ms), dominated by one `exp` per point and bit.
+- **Block equalizers at small `block_size` on the GPU**: a fixed cost per block; at 256 the GPU only ties the CPU without carrier recovery.
+- **`cs_block` on phases with frequent slip decisions**: one speculation pass per changed decision (about 1 pass per block on a realistic link, more on pathological input). Outside a CUDA graph the Python wrapper (validation, scratch allocation) costs about 18 us per launch.
+
+### Known limitations
+
+- The DSH-input warning of `estimate_linewidth` misses a drift-removed phase residual when `f_shift` is unknown: a real-valued record is valid input for both kinds of method, so the type alone cannot tell them apart.
+- Blind carrier recovery on 8-PSK near ±π/8 can lock to the wrong rotation. Inherent to blind recovery; training symbols or `resolve_phase_ambiguity` resolve it.

{commkit-1.1.0 → commkit-2.1.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 lokgar
+Copyright (c) 2026 Denis Fatkhiev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

commkit-2.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.5
+Name: commkit
+Version: 2.1.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
+Project-URL: Issues, https://github.com/lokgar/commkit/issues
+Author: Denis Fatkhiev
+License: MIT
+License-File: LICENSE
+Keywords: CuPy,DSP,GPU,coherent optics,digital communications,equalization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: matplotlib>=3.11
+Requires-Dist: numba>=0.65
+Requires-Dist: numpy>=2.4
+Requires-Dist: scipy>=1.17
+Provides-Extra: full
+Requires-Dist: cupy-cuda13x[ctk]>=14.1; extra == 'full'
+Requires-Dist: jupyter>=1.1.1; extra == 'full'
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda13x[ctk]>=14.1; extra == 'gpu'
+Provides-Extra: notebook
+Requires-Dist: jupyter>=1.1.1; extra == 'notebook'
+Description-Content-Type: text/markdown
+
+# CommKit
+
+**Digital-communications research kit for Python, on CPU and GPU.**
+
+![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
+![Backends](https://img.shields.io/badge/backend-NumPy%20%7C%20CuPy-orange)
+![License](https://img.shields.io/badge/license-MIT-green)
+![CUDA](https://img.shields.io/badge/CUDA-13.x-76B900?logo=nvidia)
+
+CommKit covers the receiver chain of coherent and IM/DD links (waveform generation, channel impairments, synchronization, carrier recovery, adaptive equalization, metrics, laser characterization and plotting) on NumPy or CuPy arrays. Computation runs on the device the data lives on.
+
+---
+
+## 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.
+
+- **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` and `center_frequency`. The description is `constellation` and `pulse`. The ground truth is `reference` (transmitted symbols and bits). 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.
+- **Results with several values are frozen dataclasses** with named fields. Metrics return host floats: one per channel for `(C, N)` input.
+- **The device follows the data.** Processing functions have no `backend=` or `device=` argument. Only factories, which have no input data to follow, take `device=`: `generate(..., device="gpu")`. Move existing data with `sig.to("gpu")`.
+- **Plots draw results.** `plot_*` functions take a Signal, an array or a result object; numerical code never imports plotting.
+- There is no pipeline object, receiver class or configuration file: the orchestration stays in your script.
+
+## Quickstart
+
+```python
+import commkit as ck
+from commkit import RRC, Constellation
+from commkit.recovery import BPS, CycleSlip
+
+tx = ck.generate(Constellation.qam(16), num_symbols=2**16, symbol_rate=32e9,
+                 sps=2, pulse=RRC(rolloff=0.1), rng=1, device="gpu")
+rx = ck.impairments.apply_phase_noise(tx, linewidth=100e3, rng=2)
+rx = ck.impairments.apply_awgn(rx, esn0_db=18, rng=3)   # on the GPU, like tx
+rx = ck.filtering.matched_filter(rx)                     # pulse from rx
+
+cpr = BPS(test_phases=64, cycle_slip=CycleSlip(history=100))
+res = ck.equalization.lms(
+    rx, num_taps=21, step_size=1e-3,
+    training_symbols=rx.reference.symbols[..., :2000], cpr=cpr,
+)
+y = res.signal                    # 1-SPS Signal, reference aligned
+print(f"EVM {ck.metrics.evm(y, num_skip_symbols=2000):.1f} %, "
+      f"BER {ck.metrics.ber(y, num_skip_symbols=2000):.1e}")
+# EVM 12.8 %, BER 2.5e-04
+
+# The next record continues from the converged taps and CPR state.
+res2 = ck.equalization.lms(rx, num_taps=21, step_size=1e-3, cpr=cpr, state=res.state)
+```
+
+Without CuPy, pass `device="cpu"` (the default): the same code runs on the CPU.
+
+## 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:
+
+- **Put data on the GPU once, at the source.** Build it there with `generate(..., device="gpu")`, `frame.to_signal(..., device="gpu")` or `load_npz(path, device="gpu")`; move a capture with `sig.to("gpu")`. Do not move data back and forth between stages. Building on the GPU is faster than `generate(...).to("gpu")`: about 26 ms instead of 370 ms for 4M symbols, because mapping and pulse shaping run there.
+- **You do not need to move results back.** Metrics (`evm`, `ber`, ...) and analysis summaries return host floats, and plots reduce on the device and transfer only what they draw.
+- **Know what runs where.**
+
+  | Work | GPU input |
+  | --- | --- |
+  | Generation, filters, resampling, spectra, impairments, BPS, LLRs, metrics, analysis | runs on the GPU |
+  | Frequency-domain equalizers `block_lms`, `block_cma`, `block_rde` | runs on the GPU (CUDA graphs) |
+  | Sequential equalizers `lms`, `rls`, `cma`, `rde`; `PLL`, `Tikhonov`, cycle-slip correction | runs on the CPU (Numba): one copy to the host and back, no speedup |
+
+  A sample-by-sample recursion has no parallel work per step. For long records on the GPU, prefer the block equalizers with `block_size=1024` or more. Each block costs a fixed overhead: at 256 the GPU only ties the CPU without carrier recovery, at 2048 it is 6-9x faster. A larger block also lowers the stable `step_size`.
+- **Short records do not pay off.** Launch overhead dominates below roughly 10⁴-10⁵ samples, where the CPU is as fast.
+- **Batch channels and records.** Pass `(C, N)` arrays rather than looping over channels in Python: one call does the work of C.
+- **Keep scalars on the device inside loops.** `float(x)`, `x.item()` and `if x > 0:` on a CuPy array wait for the GPU and copy. Collect values in an array and transfer once.
+- **The first call compiles.** Numba and CUDA kernels compile on first use and are cached on disk. Warm up once before timing anything.
+- **Seeds and devices.** The same `rng` gives the same bits and symbols on both devices. Channel noise (AWGN, phase noise) is drawn on the device, so its realization differs between CPU and GPU while its statistics match. For the exact same phase-noise trajectory on both, draw it on the CPU with `generate_phase_noise(...)` and move it.
+
+---
+
+## Modules
+
+| Module | Contents |
+| --- | --- |
+| [`commkit.core`](https://github.com/lokgar/commkit/tree/main/commkit/core) | `Signal`, `Reference`, `generate`, `SingleCarrierFrame` and `Preamble` (pilots, guard intervals, MIMO streams), `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/blob/main/commkit/filtering.py) | 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. |
+| [`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, phase noise, IQ imbalance (with Löwdin and Gram-Schmidt correction), chromatic dispersion, PMD and polarization mixing. Nonlinear channel models: **planned, not implemented**. |
+| [`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.frequency`](https://github.com/lokgar/commkit/blob/main/commkit/frequency.py) | `estimate_frequency_offset` / `correct_frequency_offset` with `MthPower`, `MengaliMorelli`, `PilotSymbols` and `BiasTone`; 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`, `DataAided`, `PilotAided`, `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`, polarization-tone demultiplexing. |
+| [`commkit.metrics`](https://github.com/lokgar/commkit/blob/main/commkit/metrics.py) | `evm`, `snr`, `ber`, `ser`, `gmi`, `mi`, including shaped constellations; host values per channel. |
+| [`commkit.analysis`](https://github.com/lokgar/commkit/tree/main/commkit/analysis) | Laser and carrier-phase characterization: `estimate_linewidth` (increment slope, β-separation, delayed self-heterodyne FM-PSD / increment / Lorentzian), FM-noise PSDs, drift separation, Allan deviation. |
+| [`commkit.math`](https://github.com/lokgar/commkit/blob/main/commkit/math.py) | `rms`, `normalize`, dB conversions. |
+| [`commkit.smoothing`](https://github.com/lokgar/commkit/blob/main/commkit/smoothing.py) | Display and estimation smoothers (moving average, Savitzky-Golay, 2-D density). Signal-chain filters are in `filtering`. |
+| [`commkit.io`](https://github.com/lokgar/commkit/blob/main/commkit/io.py) | `save_npz` / `load_npz` for Signals. |
+| [`commkit.plotting`](https://github.com/lokgar/commkit/tree/main/commkit/plotting) | Constellations, eye diagrams, spectra, filter responses, equalizer convergence, and synchronization and laser diagnostics that draw the estimates. Imported on first use. |
+| [`commkit.coding`](https://github.com/lokgar/commkit/tree/main/commkit/coding) | Channel coding and FEC: **planned, not implemented**. |
+
+Importing `commkit` has no side effects: it configures no logging, Matplotlib or warning filters, and does not touch the GPU.
+
+---
+
+## Installation
+
+**Requires Python 3.12+.**
+
+```bash
+pip install commkit                 # CPU
+pip install "commkit[gpu]"          # CuPy with the CUDA 13 toolkit libraries
+pip install "commkit[notebook]"     # to run the example notebooks
+pip install "commkit[full]"         # everything
+```
+
+With [`uv`](https://github.com/astral-sh/uv), use `uv pip install` in place of `pip install`. Extras combine, e.g. `commkit[gpu,notebook]`.
+
+> [!NOTE]
+> **WSL2 and CUDA.** With NVIDIA drivers and CUDA installed on Windows, there is no need to install CUDA inside WSL2. To let the Python CUDA packages find the bundled NVIDIA libraries, add to `~/.bashrc`:
+>
+> ```bash
+> export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(echo $HOME/commkit/.venv/lib/python3.*/site-packages/nvidia/cu13/lib)
+> ```
+>
+> *(This assumes the repository is cloned to `$HOME/commkit`; adjust the path otherwise.)*
+
+## Examples
+
+Jupyter notebooks in [`examples/`](https://github.com/lokgar/commkit/tree/main/examples) (install the `notebook` extra and run `jupyter lab examples`):
+
+- [`qam_receiver_quickstart`](https://github.com/lokgar/commkit/blob/main/examples/qam_receiver_quickstart.ipynb) - the quickstart above, cell by cell, with the constellation, spectrum and equalizer plots;
+- [`carrier_phase_analysis`](https://github.com/lokgar/commkit/blob/main/examples/carrier_phase_analysis.ipynb) - drift, linewidth and Allan deviation of a recovered carrier phase;
+- [`laser_linewidth_dsh`](https://github.com/lokgar/commkit/blob/main/examples/laser_linewidth_dsh.ipynb) and [`laser_linewidth_homodyne_iq`](https://github.com/lokgar/commkit/blob/main/examples/laser_linewidth_homodyne_iq.ipynb)
+  - laser linewidth from delayed self-heterodyne and homodyne IQ captures;
+- `measurement_laser_linewidth_*` - lean templates for real captures.
+
+The notebooks are committed without outputs and run in CI.
+
+## Development
+
+```bash
+git clone https://github.com/lokgar/commkit.git
+cd commkit
+uv sync --all-extras
+uv run nbstripout --install      # once per clone: notebooks are committed without outputs
+
+uv run pytest                    # CPU and GPU tests
+uv run pytest --device=cpu       # what CI runs
+uv run ruff check . && uv run mypy commkit/
+```
+
+Contributor and coding-agent guidance (architecture, API rules, numerics, performance and test conventions) is in [AGENTS.md](https://github.com/lokgar/commkit/blob/main/AGENTS.md).
+
+## License
+
+[MIT](https://github.com/lokgar/commkit/blob/main/LICENSE)