Signal-processing correctness + AI-assisted link estimation + edge deployment evidence. A production-discipline reference for physical-layer AI: a classical QPSK baseband simulator with deterministic BER vs SNR sweeps, four scikit-learn estimators that learn link conditions from constellation statistics, an ONNX export path validated against a Jetson benchmark template, and end-to-end reproducibility from a fresh clone in under five minutes.

The deliverable is the engineering pattern, not a production receiver. Every BER number is regenerable from a deterministic seed; every ML metric is reported on a stratified holdout; the channel classifier's weak 0.472 accuracy is surfaced as a calibrated finding rather than hidden in a footnote.

▶ Open the live dashboard  ·  Tech brief  ·  Source code

AI-RAN and edge-AI wireless systems depend on a measurable physical layer. Most repos in this space either skip the signal-processing work (claim ML wins without showing the classical baseline) or skip the discipline (claim production-grade results from notebook-only experiments). Neither is a defensible engineering pattern.

This repo demonstrates the engineering pattern that makes physical-layer ML credible: classical baseline first (verified BER curves matching textbook predictions), ML estimators second (with honest holdout metrics and disclosed weaknesses), edge deployment path third (ONNX export + Jetson benchmark template, ready when hardware lands).

The discipline is the deliverable. The QPSK math is textbook, the dataset is synthetic, the Jetson latency row is honest <TO MEASURE> until hardware arrives. What's defensible end-to-end is the methodology, the reproducibility, and the calibration of confidence.

Full numbers and methodology in Measured Metrics below. Limitations and what production would require in Positioning.

Open the rendered dashboard here: reports/dashboard.html.

It summarizes:

• adaptive QAM BER across CP-OFDM QPSK / 16-QAM / 64-QAM / 256-QAM
• 3GPP TR 38.901 TDL-A/B/C BLER multipath stress behavior
• LS vs MMSE vs neural channel-estimation comparison
• ONNX FP32/INT8 deployment path and quantization trade-off
• weak channel classifier result disclosed instead of hidden
• Jetson AGX Thor benchmark template ready, with latency marked pending until measured

These are the concrete decisions that separate a clean physical-layer reference from a notebook with a model in it:

• CP-OFDM with adaptive QAM — not just QPSK. qpsk_link/ofdm.py implements a 64-subcarrier CP-OFDM modem with Gray-coded square QAM at M = 4 / 16 / 64 / 256. Constellations normalised to unit average symbol energy; Gray property verified by an explicit test that walks the I/Q grid and checks every neighbour pair has Hamming distance exactly 1. The resulting BER vs SNR curves match textbook 5G NR link-adaptation tables.
• 3GPP TR 38.901 TDL-A / TDL-B / TDL-C channels. qpsk_link/tdl_channel.py transcribes the literal NLOS tap profiles from TR 38.901 §7.7.2 Tables 7.7.2-1/2/3. Block fading per realisation, power normalised so E[Σ|h|²] = 1. Ensemble BLER curves committed to reports/bler_full_tdl_ofdm.csv. The honest finding (BLER ~10% even at 30 dB without coding) is the signal that motivates LDPC + HARQ — surfaced, not polished away.
• Pilot-based channel estimation with LS / MMSE / neural compared head-to-head. qpsk_link/channel_estimation.py runs all three on the same TDL-C realisations and reports both channel-MSE and resulting BLER. The PyTorch MLP is the DeepRx pattern in miniature; the calibrated finding is that neural wins at low SNR (denoising), MMSE wins at high SNR (correct prior + low noise = closed-form optimum). LS lags everywhere.
• PyTorch + INT8 ONNX deployment pipeline. train_snr_torch.py trains a small MLP, exports FP32 ONNX, dynamic-PTQ quantises to INT8 ONNX, and benchmarks holdout MAE + file size + CPU latency for all three forms. Measured: ~3.3× CPU latency reduction and ~2× smaller file with sub-0.01 dB accuracy drift — textbook PTQ payoff. INT8 ONNX lands directly on Jetson AGX Thor via edge/jetson_benchmark_template.py.
• No feature leakage for the link-condition estimators: fading_abs and fading_phase are saved in the dataset CSV as labels but excluded from FEATURE_COLUMNS in ai_link_estimation/features.py. They encode oracle channel knowledge and would trivially inflate any classifier built on them — AGENTS.md non-negotiable rule #1.
• Two-pass channel verification. A bug in earlier revisions had add_awgn referencing noise to received power instead of transmit power, making the Rayleigh penalty cancel out at the receiver. Caught by ensemble measurement, fixed (add_awgn gained an optional reference_power, apply_channel now passes pre-fading transmit power), and verified with a regression gate: reports/ber_smoke_awgn.csv must regenerate bit-identically.
• CI runs on Python 3.11 AND 3.12. Most portfolio repos pin one version; this one validates both, including the PyTorch + ONNX + INT8 quantisation pipeline.
• Deterministic everywhere it matters. np.random.default_rng(seed) is threaded through the BER sweep, dataset generation, model training, channel-estimator training, and ONNX export — every committed number is byte-reproducible from the committed seed.

If you are evaluating physical-layer ML engineering: these are the signals that distinguish a reference repo from a tutorial.

Implemented: Python · NumPy · SciPy · scikit-learn · matplotlib · ONNX export · BER analysis · permutation-aware feature design

Optional extension: Jetson ONNX Runtime latency benchmarking (template ready, hardware not yet measured)

Source: reports/link_estimation_metrics.json (mirror at models/metrics.json). Dataset: synthetic link-condition CSV with 500 samples, 125-sample stratified holdout, 12 constellation-statistic features.

The channel classifier scoring 0.472 on a two-class problem is a useful negative result, not noise to hide: the current 12-feature set supports SNR/BER estimation much better than channel-type recognition. See reports/link_estimation_report.md for the full interpretation.

The Rayleigh smoke row is a single-realization result: channel.rayleigh_fading draws one complex-Gaussian h per simulation call, and the demodulator receives that h as perfect channel-state information. With seed=7 the single draw produces a deep enough fade at 0 dB to push BER to 4.8 %, while higher-SNR draws happen to land at favourable |h|² and clear below the 2000-bit resolution floor.

The ensemble-averaged Rayleigh row (N=200 × 10 000 bits per SNR point) is the right curve to compare against AWGN. It uses the transmit-power-SNR convention: channel.add_awgn references noise variance to the pre-fading transmit signal power (via an explicit reference_power passed from apply_channel), so the |h|² factor does not cancel out and the fade penalty propagates to the receiver.

Earlier revisions used a per-realization-SNR convention (noise referenced to received power), under which the Rayleigh curve tracked AWGN at the same SNR. That earlier behaviour was confirmed by ensemble measurement and then fixed: channel.add_awgn gained an optional reference_power parameter, and apply_channel now passes the pre-fading transmit power on both AWGN and Rayleigh paths. The verification gate (AWGN BER on reports/ber_smoke_awgn.csv and reports/ber_full_awgn.csv must regenerate bit-identically) is satisfied — the AWGN path is mathematically unchanged because the input signal to add_awgn already equals the transmit signal there.

Reproduce locally:

make install-dev
make generate-evidence
make train-evidence
cat reports/link_estimation_metrics.json

flowchart LR
    A["Random bits"] --> B["QPSK mapper<br/>(Gray coding)"]
    B --> C["Pulse shaping<br/>(root-raised cosine)"]
    C --> D["Wireless channel<br/>AWGN / Rayleigh"]
    D --> E["Matched filter<br/>symbol timing recovery"]
    E --> F["QPSK demapper<br/>(hard decision)"]
    F --> G["BER + constellation statistics"]
    G --> H["Classical BER vs SNR curve<br/>textbook verification"]
    G --> I["ML link estimators<br/>SNR / BER / channel / quality"]
    I --> J["ONNX export"]
    J --> K["Jetson benchmark template<br/>latency p50 / p95 / p99"]
    G --> L["Static dashboard<br/>operator engineering readout"]

.
├── run_sim.py                            # BER sweep CLI (--fading, --num-bits, --snr-min/max/step)
├── run_sim_ensemble.py                   # Ensemble Rayleigh BER sweep (--n-realizations)
├── qpsk_modem.py                         # QPSK mapper, RRC filter, matched filter, demap
├── channel.py                            # AWGN + flat Rayleigh fading (transmit-power-SNR)
├── plots.py                              # BER curves, constellation plots
├── generate_dataset.py                   # Synthetic link-condition CSV CLI
├── train_link_models.py                  # Train SNR/BER/channel/quality estimators
├── export_onnx.py                        # Export trained estimators to ONNX
│
├── ai_link_estimation/                   # ML link-estimation package
│   ├── dataset.py                        # simulate_link_sample, generate_dataset, schema
│   ├── features.py                       # FEATURE_COLUMNS, constellation_statistics
│   ├── models.py                         # train_models, write_comparison_report
│   └── onnx_export.py                    # ONNX conversion via skl2onnx
│
├── edge/
│   └── jetson_benchmark_template.py      # ONNX Runtime latency benchmark
│
├── tests/
│   ├── test_modem.py                     # DSP unit tests
│   └── test_features.py                  # Feature extraction + link-quality score tests
│
├── reports/                              # Committed proof artifacts (regenerable via make verify)
│   ├── ber_smoke_awgn.{csv,svg}          # 2k-bit AWGN smoke curve
│   ├── ber_full_awgn.{csv,svg}           # 1M-bit AWGN full sweep
│   ├── ber_smoke_rayleigh.{csv,svg}      # Single-realization Rayleigh smoke (disclosed caveat)
│   ├── ber_full_rayleigh.{csv,svg}       # Ensemble-averaged Rayleigh (N=200 × 10k bits)
│   ├── link_estimation_metrics.json      # ML estimator holdout metrics
│   ├── link_estimation_report.md         # Plain-text comparison report
│   ├── edge_inference_plan.md            # ONNX / TensorRT path notes
│   └── dashboard.html                    # Executive HTML dashboard (regenerated)
│
└── notebooks/legacy/                     # Original exploration notebooks (provenance only)

Primary target: Linux / macOS / Windows. Core simulator runs on standard CPU Python. Jetson usage is the optional ONNX Runtime benchmark path after models are exported.

git clone https://github.com/obiedeh/wireless-link-intelligence-system.git
cd wireless-link-intelligence-system
python -m venv .venv
source .venv/bin/activate          # PowerShell: .\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python run_sim.py

Full verification (Linux / macOS):

make install-dev
make verify

make verify runs ruff lint → 15 pytest tests → BER smoke sweep → synthetic dataset generation → model training → artifact existence check.

make verify
python build_dashboard.py

Then open the rendered dashboard:

• Live dashboard
• Local artifact

For a fast CLI-only path, run:

python run_sim.py
python generate_dataset.py --samples 500 --num-bits 4000
python train_link_models.py

Generate synthetic link-condition data:

python generate_dataset.py --samples 500 --num-bits 4000

This creates data/link_conditions.csv with: SNR, measured BER from the classical baseline, channel type, fading magnitude and phase, and 12 constellation statistics (power, I/Q moments, EVM, phase spread, radius spread, quadrant balance).

Train the estimators and produce the comparison report:

python train_link_models.py

Training artifacts:

CI validates this path with a smaller deterministic dataset so the repository proves tests, simulation, dataset generation, training, and evidence artifact creation on Ubuntu (Python 3.11 + 3.12).

This is an edge benchmark path, not a TensorRT-validated production deployment claim. Use it to generate measurable latency evidence on Jetson hardware.

Export trained models to ONNX:

python -m pip install ".[edge]"
python export_onnx.py

Benchmark on Jetson (or any host with onnxruntime):

python edge/jetson_benchmark_template.py --model models/onnx/snr_estimator.onnx --runs 1000

See reports/edge_inference_plan.md for TensorRT-ready notes. The current ONNX path is a practical edge inference bridge for the tabular estimators. For TensorRT acceleration, the tree-based estimators would need to be distilled into a small neural network and validated for parity across Python, ONNX Runtime, and TensorRT — a known scope expansion, intentionally deferred until Jetson hardware lands.

For the reviewer-facing checklist see PORTFOLIO_DELIVERABLES.md. For the executive one-pager see TECH_BRIEF.md.

This repository is a production-discipline reference for physical-layer AI engineering. It is not:

• a full AI-RAN base station
• a scheduler
• a standards-compliant modem
• a production telecom receiver

What it is: a measurable QPSK simulation testbed with verified BER curves, an ML link-estimation layer with honest holdout evaluation, and an ONNX export path validated end-to-end on commodity hardware (Jetson latency <TO MEASURE> until the device lands).

The methodology — classical baseline first, ML second, edge path third, honest weak results surfaced — applies beyond QPSK to any physical-layer AI work.

MIT License.