Metadata-Version: 2.4
Name: commpy
Version: 1.0.0
Summary: Python Library for Communication Engineering.
Author-email: Marvin Elling <mane.der@web.de>
License: Apache 2.0
Project-URL: Homepage, https://github.com/MarvinElling/CommPy
Project-URL: Iussues, https://github.com/MarvinElling/CommPy/issues
Keywords: Communication,Information,Information Theory,Signal Processing,Engineering,AI,Machine Learning,Shannon,Entropy
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: scipy
Provides-Extra: fast
Requires-Dist: numba; extra == "fast"
Provides-Extra: dev
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: yapf; extra == "dev"
Dynamic: license-file

# CommPy

**CommPy** is a general-purpose Python library for communications engineering (Nachrichtentechnik): channel coding, digital modulation, OFDM, information theory, and queuing theory, built on NumPy/SciPy with an optional Numba-accelerated fast path.

## Overview

CommPy covers the classic communications-engineering stack, end to end:

- **Channel coding (FEC)**: CRC (8/16/32), Hamming, generic cyclic codes, BCH, Reed-Solomon (error + erasure decoding), convolutional codes with hard/soft-decision Viterbi decoding, block and convolutional interleaving.
- **Digital modulation**: a generic, Gray-coded M-PSK/M-QAM/M-PAM engine with soft-decision (LLR) demodulation, plus the original per-scheme classes (OOK, BPSK, ASK-2/4, QPSK, 8-PSK) kept for backward compatibility.
- **Physical layer**: raised-cosine/root-raised-cosine pulse shaping, ZF/MMSE linear equalization, symbol-timing and carrier-frequency/-phase synchronization (Gardner TED, M-th-power CFO estimation, a Costas loop).
- **OFDM**: modulator/demodulator with configurable active subcarriers and cyclic prefix, PAPR/PAPR-CCDF analysis.
- **Channel models**: BSC, BEC, AWGN, Rayleigh/Rician fading, Z-channel, Gilbert-Elliott bursty channel, uniform quantization.
- **Information theory**: Shannon/binary entropy, mutual information, channel capacity (closed-form BSC/AWGN and Blahut-Arimoto for general DMCs), Huffman and arithmetic source coding, binary rate-distortion.
- **Queuing theory**: M/M/1, M/M/1/K, M/M/c closed-form performance models.
- **Finite-field arithmetic**: prime fields GF(p) and binary extension fields GF(2^m), the algebraic foundation for BCH/Reed-Solomon.
- **Waveform synthesis**: pulse-shaped, optionally up-converted IQ waveforms with eye-diagram/spectrum plotting.

## Features

- **Modular by design** — each topic (coding, modulation, OFDM, info theory, queuing) is an independent subpackage; shared abstractions (`Modulator`, `FiniteField`) mean adding a new scheme reuses existing, tested machinery instead of duplicating it.
- **Resource-efficient** — vectorized NumPy throughout; SciPy where it's a genuine win (FFT for OFDM, `solve_toeplitz` for MMSE equalization); the one inherently sequential hot loop (Viterbi decoding) gets optional Numba JIT acceleration via `pip install commpy[fast]`, with a correctness-preserving pure-Python fallback when it's not installed.
- **Rigorously tested** — 300+ tests, including exhaustive brute-force cross-validation for algebraic decoders (BCH, Reed-Solomon) and Viterbi against maximum-likelihood search, and statistical BER-vs-SNR checks against theoretical curves.
- **Fully typed** — complete type hints throughout, checked with `mypy --strict`.

## Installation

```bash
pip install commpy
```

With optional JIT acceleration for Viterbi decoding:

```bash
pip install commpy[fast]
```

Or install from source:

```bash
git clone <repository-url>
cd CommPy
pip install -e ".[dev]"
```

## Quick Start

### Channel coding: Reed-Solomon

```python
from commpy import ReedSolomonCode
import numpy as np

code = ReedSolomonCode(m=8, k=223)  # RS(255, 223), the classic CCSDS code
message = np.arange(223) % code.field.order
codeword = code.encode(message)

corrupted = codeword.copy()
corrupted[[10, 50, 100]] ^= 1  # 3 symbol errors, well within t=16
decoded, _, n_errors = code.decode(corrupted)
assert np.array_equal(decoded, message)
```

### Digital modulation with soft-decision demodulation

```python
from commpy import MQAMModulator, Channels
import numpy as np

mod = MQAMModulator(16)  # 16-QAM, Gray-coded, unit average energy
bits = np.random.randint(0, 2, mod.bits_per_symbol * 1000)
symbols = mod.modulate(bits)

received = Channels.awgn(symbols, snr_db=15)
llrs = mod.soft_demodulate(received, noise_var=1.0)  # feed straight into a Viterbi decoder
hard_bits = mod.demodulate(received)
```

### Convolutional coding + Viterbi decoding

```python
from commpy import Trellis, ConvolutionalEncoder, viterbi_decode
import numpy as np

trellis = Trellis(constraint_length=7, generators=(0o171, 0o133))  # the classic Voyager code
encoder = ConvolutionalEncoder(trellis)

message = np.random.randint(0, 2, 100)
codeword, _ = encoder.encode(message, terminate=True)
decoded = viterbi_decode(trellis, codeword, mode='hard', terminated=True)
assert np.array_equal(decoded, message)
```

### OFDM

```python
from commpy import OFDMModulator, OFDMDemodulator, MQAMModulator, papr_db
import numpy as np

mod, demod = OFDMModulator(n_fft=64, cp_len=16), OFDMDemodulator(n_fft=64, cp_len=16)
qam = MQAMModulator(4)

bits = np.random.randint(0, 2, 64 * qam.bits_per_symbol * 10)
symbols = qam.modulate(bits)
tx = mod.modulate(symbols)
print(f"PAPR: {papr_db(tx[:64]):.1f} dB")

rx_symbols = demod.demodulate(tx)
assert np.allclose(rx_symbols, symbols)
```

### Information theory

```python
from commpy import channel_capacity_awgn, huffman_codes, huffman_encode

capacity = channel_capacity_awgn(snr_linear=10)  # bits/channel use

codes = huffman_codes({'a': 0.5, 'b': 0.25, 'c': 0.25})
encoded = huffman_encode(['a', 'a', 'b', 'c'], codes)
```

More end-to-end examples, including a full transmit chain composing several of these pieces, live in [`examples/`](examples/).

## Module Structure

```
commpy/
├── _channelCoding/
│   ├── block/            # CRC, Hamming, cyclic, BCH, Reed-Solomon
│   ├── convolutional/    # Trellis, encoder, Viterbi (hard/soft)
│   └── interleaving/     # Block and convolutional interleavers
├── _channels/            # Channel impairment models (BSC, BEC, AWGN, fading, ...)
├── _fields/               # GF(p) and GF(2^m) arithmetic, polynomials
├── _informationTheory/   # Entropy, capacity, source coding, rate-distortion
├── _modulation/          # Generic M-PSK/M-QAM/M-PAM engine, legacy classes,
│                          # pulse shaping, equalization, synchronization
├── _networking/          # M/M/1-family queuing models
├── _ofdm/                 # OFDM modulator/demodulator, PAPR analysis
├── _utils/                # Math helpers, optional-Numba shim
├── _waves/                # IQ waveform synthesis and plotting
└── __init__.py            # Public API (flat re-export; everything else is private)
```

Only names exported from `commpy/__init__.py` are public API; submodules (anything starting with `_`) may be reorganized without notice.

## Documentation

- [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) — tutorials, one per major feature area.
- [`docs/API.md`](docs/API.md) — full API reference.
- [`docs/USER_GUIDE.md`](docs/USER_GUIDE.md) — theory background and best practices.
- [`docs/QUICK_REFERENCE.md`](docs/QUICK_REFERENCE.md) — cheat sheet.
- [`docs/FAQ.md`](docs/FAQ.md), [`docs/CHANGELOG.md`](docs/CHANGELOG.md).
- [`examples/`](examples/) — runnable scripts, one per major feature plus a full-chain capstone.

## Requirements

- Python ≥ 3.10
- NumPy, SciPy, Matplotlib
- Optional: Numba (`pip install commpy[fast]`), for JIT-accelerated Viterbi decoding

## License

Licensed under the Apache License 2.0. See [LICENSE](LICENSE) file for details.

## Author

Marvin Elling

## Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests. See [CONTRIBUTING.md](CONTRIBUTING.md).
