comnum

Link-level simulation of digital communication systems, wireless and optical, in Rust with Python bindings: the blocks of a link, a parallel Monte Carlo runner whose results do not depend on the thread count, and campaigns written as files and checked against the literature.

• Lightweight: one run-time dependency in Python (numpy), 9 direct crates in Rust and no C, C++ or Fortran library to build; 27 MB installed with its dependencies (the benchmark's environment: komm 22 MB, OptiCommPy 321 MB, Sionna 1004 MB).
• Fast: compiled Rust, Monte Carlo runs on every core; on one CPU thread, the links of the benchmark take 2.1 to 33 times as long with komm, 2.3 to 4.7 times as long with OptiCommPy and 1.1 to 7.4 times as long with Sionna as with comnum.
• Safe: unsafe code forbidden in every crate, invalid inputs are errors (one error type), results independent of the thread count; 717 unit tests, 187 validation tests, 272 Python tests.
• Validated: compared with 130 papers, standards and reference tools (82 fully reproduced, 44 partly), 100 inconsistencies found in them; 93 validation cards rerun a comparison without the paper.

The numbers are recomputed by tools/highlights.py from the recorded benchmark and the validation files; the details are on the page Why comnum.

Install

pip install comnum            # Python 3.11 or later; wheels for Linux, macOS and Windows
pip install "comnum[plot]"    # with matplotlib, for the plots
cargo add comnum              # the Rust library (Rust 1.85 or later)
cargo install comnum-spec     # the `comnum` command, which runs campaigns written as YAML files

The Python package needs NumPy only. From a clone, maturin develop --release builds it (getting started).

Three examples

A coded link, on every core

The bit and block error rates of an LDPC code with 16-QAM over AWGN, run by the parallel runner until 100 block errors are counted at each $E_b/N_0$, with their confidence intervals, against the uncoded closed form and the BICM limit of the code rate:

import comnum
res = comnum.run_spec("specs/bicm_ldpc.yaml")           # the link, the grid and the stopping rule
res.plot("ebn0_db", "coded_ber", theory=lambda x: comnum.theory_ber(16, x, "qam"))

The same campaign from the command line, comnum run specs/bicm_ldpc.yaml, or in Rust on the same runner (comnum::sim, the example ber_awgn). The specification is a YAML file: the link as a list of blocks, the grid, the metrics and the stopping rule.

link:
  - {type: fec_encode, code: &code {type: ldpc, n: 1024, k: 512, seed: 1}, blocks: 8, interleave: true}
  - {type: map, constellation: 16-QAM}
  - {type: awgn_ebn0, ebn0_db: $ebn0_db}
  - demap
  - {type: fec_decode, code: *code, interleave: true}
metrics: {report: [ber, coded_ber, bler]}
stop: {min_errors: {bler: 100}, min_trials: 8, max_trials: 400}

An optical link

16-QAM at 32 GBd over 10 × 80 km of standard fibre with EDFAs, propagated by the split-step Fourier method, then received with dispersion compensation or digital back-propagation (specs/ssfm_dbp.yaml; the Rust example ssfm_dbp writes the same link by hand):

res = comnum.run_spec("specs/ssfm_dbp.yaml")
res.plot("power_dbm", "snr_db", by="receiver")

A measured signal

A capture of a software radio goes through the same blocks as a simulation. Here one second of an LTE carrier recorded by a HackRF One (band 28, 15.36 MS/s) is brought to baseband, searched for a cell, and the master information block of every frame is decoded:

x, fs, meta = comnum.read_sigmf("capture", channel=0)
y = comnum.select_channel(x, fs, 770.5e6 - 775e6, 1.92e6, 0.6e6)   # the six central resource blocks
cell = comnum.lte_cell_search(y, max_cfo_hz=25e3)[0]
frames = comnum.lte_decode_mib(y, cell)                             # {"sfn", "ports", "n_rb", ...} per frame

The receiver finds the cell identity, the frequency offset of the receiver (−13.06 kHz, the oscillator of the HackRF 17 ppm off) and decodes the MIB of 100 frames of 100, whose frame numbers follow one another. The Rust example lte_mib does the same from a SigMF file; the FM stereo multiplex and its RDS are received the same way (fm_stereo_decode, rds_receive).

What it covers

Every block is placed in one of fourteen crates, in five layers whose dependencies point downward only, re-exported by the facade comnum and bound to Python by name (comnum::channel::awgn, comnum.awgn); the layout and the rules are in docs/ARCHITECTURE.md.

The declarative blocks are listed by comnum blocks with their parameters; a project can add its own without comnum depending on it (ADR 0006).

Validated, not only tested

Every block enters the library with the reference it is checked against: a closed form, a table of a standard reproduced verbatim, a published figure (cited with its authors, venue, year and figure number), or the recorded output of a reference implementation (OptiCommPy, GNPy, AFF3CT, Sionna, py3gpp) used as a test oracle. The comparisons are written as data, the validation cards, and rerun without the paper; the inconsistencies found in the documents themselves are recorded with them (docs/LITERATURE.md). The strongest evidence of every module: A, an external reference; B, a closed form only; C, self-consistency only (docs/MATURITY.md gives the tests behind every grade and the regimes not covered).

Summary: 71 modules: 66 at A, 3 at B, 2 at C.

Foundations

Coding and shaping

Waveforms

MIMO

Wireless channels

Optical

Hardware impairments

Receiver DSP

Metrics and analysis

Systems and standards

Simulation and specifications

Positioning

comnum aims to be a reference link-level simulator: fast, reproducible bit for bit (seeded streams independent of the thread count), and validated block by block. It complements the existing tools rather than replacing them: Sionna targets differentiable, GPU-accelerated end-to-end learning; the MATLAB toolboxes and AFF3CT cover wider or more specialised ground; GNU Radio streams in real time. comnum offers one documented chain from the waveform to the metrics, wireless and optical, whose results trace to a closed form, a standard or a published curve (comparisons, benchmarks).

In scope: the physical layer of a point-to-point link, simulated sample by sample. Out of scope, because other tools do it well: system and network level, training neural receivers (comnum evaluates trained blocks at scale, from their parameters), real-time and hardware targets, graphical tools, and models without a reference.

The blocks follow the layout, names and conventions of OptiCommPy; the algorithms are written from their publications. OptiCommPy (GPL-3.0) is a test oracle only, never imported: the tests read its recorded outputs.

Stability

Version 0.2.0 is the first public release. From it on, the crates follow semantic versioning with one version for all, the Python API changes only with a migration note in the changelog, CI checks every pull request with cargo-semver-checks, and the schema of the specifications is versioned. Until then the API moves freely, without deprecated aliases.

How this library was written

comnum is developed with an AI coding assistant, and says so plainly: Claude (Anthropic), through Claude Code, wrote most of the code, tests and documentation, under the direction of the author, who decided the scope and the architecture, the models, the references each block is checked against and the tolerances, and reviewed every change. Correctness rests on the evidence above, not on who wrote a line; the rules apply to every contribution, human or generated (docs/ARCHITECTURE.md, CLAUDE.md).

Documentation

• The Python package: tutorials, the user guide, a gallery of classical results and of reproduced figures of the literature, the API reference.
• The Rust crates: https://docs.rs/comnum; the runnable examples in examples/; the specifications in specs/.
• Contributing: CONTRIBUTING.md (how a block is validated, the test suites, good first contributions). A disagreement with a reference is a bug: please report it.

Licence

MIT or Apache-2.0, at your option (LICENSE-MIT, LICENSE-APACHE). The data of third parties shipped in the crates and the status of the recorded oracle fixtures are listed in THIRD_PARTY.md. To cite comnum, use CITATION.cff.