Metadata-Version: 2.4
Name: pyberlab
Version: 0.1.0
Summary: Reproducible BER simulation for digital modulation over AWGN and Rayleigh channels
Author: Siwei Chen
License-Expression: MIT
Project-URL: Homepage, https://github.com/If-smile/A-reproducible-Python-laboratory-for-digital-modulation-BER-experiments
Project-URL: Documentation, https://github.com/If-smile/A-reproducible-Python-laboratory-for-digital-modulation-BER-experiments/tree/main/docs
Project-URL: Repository, https://github.com/If-smile/A-reproducible-Python-laboratory-for-digital-modulation-BER-experiments.git
Project-URL: Issues, https://github.com/If-smile/A-reproducible-Python-laboratory-for-digital-modulation-BER-experiments/issues
Project-URL: Changelog, https://github.com/If-smile/A-reproducible-Python-laboratory-for-digital-modulation-BER-experiments/blob/main/CHANGELOG.md
Keywords: bit-error-rate,communications,digital-modulation,monte-carlo-simulation,signal-processing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.7
Provides-Extra: test
Requires-Dist: pytest>=7.4; extra == "test"
Requires-Dist: pytest-cov>=4.1; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff==0.15.22; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.2; extra == "docs"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: docutils<0.22,>=0.21.2; extra == "release"
Requires-Dist: packaging<26,>=24; extra == "release"
Requires-Dist: twine>=5.1; extra == "release"
Dynamic: license-file

# pyberlab — Physical-Layer BER Simulation

`pyberlab` is a Python library for simulating bit-error-rate (BER)
performance of digital modulation schemes over common wireless channel models.
It is intended for reproducible communication-systems experiments without a
MATLAB dependency.

## Features

- Modulation: BPSK, QPSK, Gray-coded 8-PSK, 16-QAM, and 64-QAM
- Channels: AWGN and independent Rayleigh flat fading with perfect coherent
  equalisation
- Theory baselines: exact hard-decision BER for the supported AWGN schemes;
  Rayleigh BER for every implemented modulation
- Reproducible Monte-Carlo experiments through `numpy.random.Generator` seeds
- Adaptive sample counts based on the theoretical BER, with a configurable cap
- CSV export and publication-ready semilog BER plots
- Parameter validation that prevents truncated bit streams and invalid SNRs

## Installation

```bash
pip install -e .
```

For development tools and tests:

```bash
pip install -e ".[dev]"
```

Python 3.9+ is required.

## Documentation

The API reference is generated from the source docstrings with Sphinx. Build it
locally with:

```bash
pip install -e ".[docs]"
python -m sphinx -W --keep-going -b html docs docs/_build/html
```

Open `docs/_build/html/index.html` after the build completes. The documentation
sources start at [`docs/index.rst`](docs/index.rst), and CI treats every Sphinx
warning as a build failure.

## Release validation

Build and validate the wheel and source distribution without uploading them:

```bash
pip install -e ".[release]"
python -m build
python -m twine check --strict dist/*
python scripts/check_distribution.py dist
```

The GitHub Actions `Distribution` job also installs the wheel in a clean virtual
environment and runs modulation and BER smoke tests. See the complete
[release validation guide](docs/releasing.rst).

The Trusted Publishing workflow is defined in `.github/workflows/release.yml`:
after the corresponding GitHub environments and index publishers are configured,
manual runs from `main` publish to TestPyPI, while publishing a version-matched
GitHub Release is the only route to production PyPI. Neither route stores a
long-lived API token in the repository.

## Quick start

```python
import numpy as np

from pyberlab.channel import awgn, rayleigh
from pyberlab.modulation import BPSK, PSK8, QAM64
from pyberlab.plot import plot_ber
from pyberlab.simulation import run_simulation

EbN0_dB = np.arange(0, 13)

bpsk_awgn = run_simulation(BPSK(), awgn, EbN0_dB, seed=42)
bpsk_rayleigh = run_simulation(BPSK(), rayleigh, EbN0_dB, seed=42)
qam64_awgn = run_simulation(QAM64(), awgn, EbN0_dB, seed=42)
psk8_rayleigh = run_simulation(PSK8(), rayleigh, EbN0_dB, seed=42)

plot_ber(
    [bpsk_awgn, bpsk_rayleigh, qam64_awgn, psk8_rayleigh],
    ["BPSK AWGN", "BPSK Rayleigh", "64-QAM AWGN", "8-PSK Rayleigh"],
    title="BER comparison",
    save_path="outputs/ber_comparison.png",
)
```

Each result dictionary contains `EbN0_dB`, simulated and theoretical BER,
the number of simulated bits, and error counts. Pass `csv_path` to
`run_simulation` to persist the result table.

## Examples

- [`examples/bpsk_awgn.ipynb`](examples/bpsk_awgn.ipynb) presents a complete,
  reproducible BPSK/AWGN experiment with constellation, statistics, CSV export,
  and BER plotting.
- [`examples/qpsk_awgn.ipynb`](examples/qpsk_awgn.ipynb) demonstrates the
  Gray-coded QPSK constellation, independent I/Q decisions, and its theoretical
  BER equivalence with BPSK.
- [`examples/rayleigh_comparison.ipynb`](examples/rayleigh_comparison.ipynb)
  compares every implemented modulation over AWGN and coherent Rayleigh fading,
  including target-BER fading penalties and per-experiment CSV exports.
- [`examples/modulation_comparison.ipynb`](examples/modulation_comparison.ipynb)
  compares all supported constellations and their AWGN BER performance, including
  the Eb/N0 required to reach a target BER and the penalty relative to BPSK.

## Theory model

For BPSK and QPSK, the AWGN and coherent-Rayleigh formulas are closed form.
For Gray-coded 8-PSK, the exact AWGN baseline integrates the receiver's angular
decision regions, and its Rayleigh baseline averages over instantaneous SNR.
For Gray-coded 16-QAM and 64-QAM, the AWGN baseline exactly enumerates the
hard-decision PAM regions and Gray-label Hamming distances. Their Rayleigh
baseline numerically averages that exact conditional BER over the exponential
instantaneous-SNR distribution.

The formulas therefore match the package's hard-decision receiver model at low
SNR as well as high SNR. They are not the common high-SNR QAM approximations.

## Project layout

```
pyberlab/
├── modulation/       # Modulator ABC, BPSK, QPSK, 8-PSK, 16-QAM, 64-QAM
├── channel/          # AWGN and coherent Rayleigh flat fading
├── simulation/       # Runner, BER metrics, CSV output
├── theory/           # Analytical and numerical BER baselines
└── plot/             # BER curve generation
examples/             # Executable notebooks and standalone prototypes
docs/                 # Sphinx guides and generated API reference sources
scripts/              # Distribution validation and installed-wheel smoke tests
tests/                # Unit and end-to-end tests
```

## Status and roadmap

The initial library, simulation framework, example notebooks, and API
documentation are complete. Version `0.1.0` is being prepared as the first
public release; the remaining release step is PyPI publishing. See
[CHANGELOG.md](CHANGELOG.md), the
[`v0.1.0` release notes](docs/releases/0.1.0.rst), and [TODO.md](TODO.md).

## License

MIT
