CommKit

Digital-communications research kit for Python, on CPU and GPU.

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

plain arrays (NumPy / CuPy)          value objects (frozen, written inline)
        \                            Constellation, RRC / RC / Gaussian / Rect,
         \                           BPS / PLL / CycleSlip, MthPower, ...
          v                                   |
       Signal  = samples + facts + description + reference
          |
          v
   functions: generate, apply_*, estimate_*, correct_*, resolve_*, ...
          |                 \
          v                  v
   Signal or array      typed results (EqualizerResult, *Estimate, ...)
                             |
                             v
                   plotting (draws results, never computes them)

• Algorithms are plain functions. Data is a Signal or an array.
• 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").
• There is no pipeline object, receiver class or configuration file: the orchestration stays in your script.

Quickstart

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

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+.

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, use uv pip install in place of pip install. Extras combine, e.g. commkit[gpu,notebook].

Examples

Jupyter notebooks in examples/ (install the notebook extra and run jupyter lab examples):

• qam_receiver_quickstart - the quickstart above, cell by cell, with the constellation, spectrum and equalizer plots;
• carrier_phase_analysis - drift, linewidth and Allan deviation of a recovered carrier phase;
• laser_linewidth_dsh and laser_linewidth_homodyne_iq
  • 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

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.

License

MIT.