LinkScope couples a behavioral photonic circuit model to a communications link simulator to study calibration, drift, and equalization.
| Surface | Status | Evidence |
|---|---|---|
| Core link simulator | Working local NumPy scaffold for PAM2/PAM4 symbols, ring/MZI modulation, detector/TIA noise, FFE equalization, link budget, and process variation | python3 -m pytest -q |
| Corrected BER accounting | Gray-coded PAM bit errors, separate SER/BER bounds, historical ber_proxy separated from FEC comparisons |
tests/unit/test_metrics.py, tests/unit/test_symbols.py |
| E001 smoke | Local smoke passed: 512 symbols, BER 0.122070, SER 0.244141, worst smoke drift BER 0.151367 |
results/e001/summary.json |
| Canonical E001 | Not run | experiments/e001/configs/canonical.json is intentionally disabled |
Does joint ring-bias calibration and digital FFE adaptation maintain lower BER after thermal drift than optical recalibration alone or FFE adaptation alone under a matched training and measurement budget?
The retained implementation is intentionally small:
- Behavioral ring and MZI transmitter models.
- Photodiode/TIA, detector noise, quantization, and jitter-like impairment.
- Feed-forward equalizer fitting and hard PAM decisions.
- Gray-coded PAM bit mapping for actual BER counts.
- Ring calibration fitting against a synthetic calibration fixture.
- TX power, thermal drift, and process-variation sweeps.
SAX and OptiCommPy are the intended upstream substrates for the canonical experiment. They are pinned in UPSTREAM.md but not yet wired into the smoke run.
Smoke artifact:
scripts/reproduce_e001.sh experiments/e001/configs/smoke.jsonCanonical E001:
scripts/reproduce_e001.sh experiments/e001/configs/canonical.jsonThe canonical command stops while disabled. Enable it only after the SAX-to-OptiCommPy bridge, matched budget policy, and canonical run budget are implemented.
Local verification:
python3 -m pytest -q
python3 -m compileall -q src tests
uv run --with ruff ruff check .| Path | Why inspect it |
|---|---|
UPSTREAM.md |
SAX and OptiCommPy pins and integration boundary |
src/photon_link_lab/metrics.py |
Corrected BER/SER accounting and confidence bounds |
src/photon_link_lab/symbols.py |
PAM levels and Gray-coded bit mapping |
src/photon_link_lab/link.py |
End-to-end retained link simulation |
src/photon_link_lab/calibration.py |
Ring calibration fit |
src/photon_link_lab/sweeps.py |
TX power, drift, and variation sweeps |
experiments/e001/experiment.md |
Hypothesis, baselines, controls, metrics, and promotion rule |
experiments/e001/configs/ |
Smoke and disabled canonical configs |
results/e001/ |
Generated local smoke manifest, summary, CSV, and figure |
docs/units-and-conventions.md |
Symbol mapping, units, and confidence-bound conventions |
docs/limitations.md |
Evidence boundaries and unsupported claims |
- Measured by tests: symbol mapping, BER/SER accounting, calibration recovery on synthetic data, retained CLI paths, link simulation behavior, and units helpers.
- Generated by command: E001 local smoke summary and figure.
- Inferred: the retained simulator is suitable as a small local scaffold for a future SAX/OptiCommPy bridge.
- Not tested: joint adaptation, substrate-backed waveform/DSP metrics, measured device calibration, or real hardware behavior.
The current ring and receiver models are behavioral approximations. The calibration fixture is synthetic and generated from the same model family that is fitted. The E001 smoke result is not a communication-system result; it only proves the retained artifact chain and corrected bit counting.
More detail is in docs/limitations.md and docs/units-and-conventions.md.
License: MIT.
SAX and OptiCommPy upstream pins are recorded in UPSTREAM.md. The package import path remains photon_link_lab for compatibility; LinkScope is the public research surface for this refocus.