Metadata-Version: 2.4
Name: serdes-optical-lab
Version: 0.2.0
Summary: Physics-backed virtual instrument bench for electrical and optical SerDes links
License-Expression: MIT
Project-URL: Homepage, https://github.com/andreagaucho88/Serdes_Simulator
Project-URL: Repository, https://github.com/andreagaucho88/Serdes_Simulator.git
Project-URL: Issues, https://github.com/andreagaucho88/Serdes_Simulator/issues
Project-URL: Changelog, https://github.com/andreagaucho88/Serdes_Simulator/blob/main/CHANGELOG.md
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: labpro/static/plotly.min.js.LICENSE.txt
License-File: labpro/static/fonts/OFL-IBM-Plex.txt
License-File: labpro/static/fonts/OFL-Space-Grotesk.txt
Requires-Dist: numpy==1.26.4
Requires-Dist: scipy==1.13.1
Requires-Dist: pandas==2.2.3
Requires-Dist: tornado==6.4.1
Requires-Dist: plotly==5.24.1
Requires-Dist: scikit-rf==2.1.0
Provides-Extra: dev
Requires-Dist: build==1.2.2.post1; extra == "dev"
Requires-Dist: pytest==8.3.5; extra == "dev"
Requires-Dist: ruff==0.6.9; extra == "dev"
Requires-Dist: setuptools>=77; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Provides-Extra: legacy
Requires-Dist: streamlit==1.45.0; extra == "legacy"
Provides-Extra: reference
Requires-Dist: serdespy==1.0; extra == "reference"
Dynamic: license-file

<div align="center">

<h1>SerDes Optical Lab PRO</h1>

<h3>From bits to eye diagrams, from channel loss to corrected codewords</h3>

<p><strong>A physics-backed virtual instrument bench for exploring complete
electrical and electro-optical SerDes links up to the 224G class.</strong></p>

<p>
  <img alt="Python 3.12" src="https://img.shields.io/badge/Python-3.12-3776AB?style=for-the-badge&logo=python&logoColor=white">
  <a href="https://github.com/andreagaucho88/Serdes_Simulator/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/andreagaucho88/Serdes_Simulator/actions/workflows/ci.yml/badge.svg?branch=main"></a>
  <a href="https://pypi.org/project/serdes-optical-lab/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/serdes-optical-lab?style=for-the-badge&color=2F7DBD"></a>
  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-F5C518?style=for-the-badge"></a>
  <img alt="32 instruments" src="https://img.shields.io/badge/instruments-32-00A6D6?style=for-the-badge">
  <img alt="136 physical controls" src="https://img.shields.io/badge/physical%20controls-136-7B61FF?style=for-the-badge">
  <img alt="502 tests" src="https://img.shields.io/badge/tests-502%20passing-2EA44F?style=for-the-badge">
</p>

<p>
  <a href="#quick-start">Quick start</a> ·
  <a href="#visual-tour">Visual tour</a> ·
  <a href="#32-instrument-panels">32-panel reference</a> ·
  <a href="#local-api">API</a> ·
  <a href="#verification-and-quality-gates">Verification</a> ·
  <a href="CHANGELOG.md">Changelog</a>
</p>

</div>

<p align="center">
  <img src="docs/media/00-instruments-hero.gif"
       alt="DCA eye diagram, live BER, and live FEC instrument tour"
       width="100%">
</p>

<p align="center">
  <em>Persistent DCA eye → synchronized waveform → accumulated BER → in-path
  KP4/KR4 FEC codeword analysis.</em>
</p>

---

## Why Lab PRO

Most link simulators stop at a waveform or a final BER number. Lab PRO keeps
the **whole evidence chain** visible. One versioned record travels from the
traffic source through TX, channel, optics, receiver, timing recovery, DSP,
decisions, and FEC. Every instrument observes a declared reference plane from
that same record.

| | Product capability | What it gives you |
| --- | --- | --- |
| 🔭 | **Instrument-style analysis** | Coherent DCA, BERT, TIE, spectrum, BER, FEC, traffic, sweep, and JTOL views |
| ⚡ | **Live acquisition** | Fresh noise per record, accumulating counters, confidence intervals, and explicit lock state |
| 🧩 | **One complete datapath** | Electrical, optical, timing, DSP, and coding effects propagate end to end |
| 🧪 | **Measured-channel support** | Touchstone 1.x/2.x S2P and mixed-mode S4P can replace the analytical channel |
| 🎓 | **Explainable controls** | 136 bilingual controls document physics, observables, experiments, and model boundaries |
| ✅ | **Auditable behavior** | 32 panels, signal ledger, checkpoints, paired invariants, and 502 automated tests |

### What is new in 0.2.0

| Instrument capability | Evidence now available |
| --- | --- |
| **Golden correlation** | Six measured IEEE P802.3bs SMF waveforms, software pattern lock, provenance, reference bandwidth, and per-capture TDECQ deltas |
| **Traffic qualification** | PHY/L1/L2 accounting, RFC 2544, ITU-T Y.1564, MP1900A-style PAM4 error analysis, and exportable reports |
| **Optical stress** | DR4 eight-case stress space, reflection/MPI, source RIN, SECQ calibration, and stressed-receiver BER |
| **Automation** | PyVISA-compatible SCPI, atomic JSON sessions, explicit readiness health, and the same experiment lock/cancel contract as the web bench |

### What you can investigate

- Trace a signal from PRBS or Ethernet frames to pre/post-FEC error counters.
- Compare up to four coherent DCA reference planes on the same acquisition.
- Inject RJ, PJ, DCD, BUJ, SSC, differential noise, and targeted bit errors.
- Move between copper and MZM, EML, DML, or VCSEL optical architectures.
- Separate sensitivity, overload, bandwidth, timing, equalization, and FEC
  limitations instead of reducing them to one score.
- Run parameter sweeps, JTOL-lite, link training, AN/LT, traffic procedures,
  DR4 analysis, and physics invariants from one workspace.

### Choose your path

| If you are a… | Start here | First outcome |
| --- | --- | --- |
| **SerDes designer** | [3-minute FEC demo](docs/QUICK_DEMO.md) | Separate channel, timing, DSP, and coding margin |
| **Optical engineer** | [Channel and optics panels](docs/PANELS.md#channel-and-optics) | Compare MZM/EML/DML/VCSEL and fiber penalties |
| **Student or interviewer** | Academy view, then [panel reference](docs/PANELS.md) | Connect each block, formula, waveform, and metric |
| **Contributor** | [Contribution guide](CONTRIBUTING.md) | Reproduce the baseline and submit a safe change |

### One bench, one datapath

~~~text
PRBS / SSPRQ / Ethernet
          │
          ▼
FEC TX → NRZ/PAM4 → TX FIR → DAC → P/N driver → S-parameter channel
                                                       │
                      ┌────────────────────────────────┘
                      ▼
              modulator → fiber → PD → TIA/AFE → AGC → CTLE → ADC
                                                                  │
                      ┌───────────────────────────────────────────┘
                      ▼
              CDR → FSE → DFE → slicer → FEC RX
                      │                    │
                      └──── eye / TIE ─────┴── BER / GMI / L2 / FEC
~~~

The maintained application lives in <code>labpro/</code> and uses a custom
Tornado/WebSocket frontend. The numerical engine in
<code>serdes_sim/</code> is GUI-independent. The former Streamlit interface
in <code>app/</code> is preserved as a frozen reference.

> **Honest scope.** Lab PRO is a system-level educational framework for
> learning, debugging, and sensitivity analysis. IEEE/OIF procedures and
> profiles identify assumptions and unsupported portions explicitly.
> <code>MODEL PASS/FAIL</code> is never presented as certified compliance.

## Visual tour

Every GIF and screenshot below comes from the real application. Each tab
change requests bench data; none of the screens use mocked plots.

### 1. Workspace, signal chain, Academy, and standards

![Workspace, signal chain, and guides tour](docs/media/01-workspace-overview.gif)

The signal chain is navigable: clicking a block opens its instrument panel.
Failed checkpoints highlight the responsible block, while amber triangles
show the reference planes currently acquired by DCA scopes.

### 2. Source, BERT, and transmitter

![BERT, generator, and transmitter tour](docs/media/02-source-and-tx.gif)

The BERT combines four views: PPG source, TX stress, error checker, and RX
procedures. Its state is shared with the FIR, DAC, P/N driver, TX PLL, and
error-insertion path.

### 3. Channel, COM, and optics

![Channel, COM, and optics tour](docs/media/03-channel-and-optics.gif)

The channel can be analytical or imported from a Touchstone file. COM,
modulator, fiber, and CMIS-lite expose their own physical planes,
measurements, and declared limitations.

### 4. Receiver and DSP

![Receiver, ADC, CDR, and equalization tour](docs/media/04-rx-and-dsp.gif)

PD, TIA, AGC, CTLE, interleaved ADC, CDR, FSE/DFE, and slicer operate on the
same end-to-end record. They are not disconnected demonstrations.

### 5. Live instruments

![DCA, jitter, spectrum, BER, and FEC tour](docs/media/05-live-instruments.gif)

DCA EYE/WAVE, TIE, spectrum, BER, and FEC update while acquisition is
running. Counters grow record by record and reset whenever the underlying
physics changes.

### 6. Procedures, training, and audit

![L2, JTOL, AN/LT, training, and audit tour](docs/media/06-procedures-and-audit.gif)

Sweep, JTOL-lite, link training, AN/LT, DR4, instrument alignment, the signal
ledger, and the physics audit make both the result and the path that produced
it inspectable.

### 7. Latest developments: traffic PHY · L1 · L2, DR4 stress space, stressed RX, compliance

The screenshots below are captured from the running application after the
instrument-fidelity iteration (traffic layers, golden correlation, stressed
receiver, DCA fixture de-embedding, J2/J9).

![Ethernet traffic panel with PHY, L1 PCS and L2 MAC cards](docs/media/07-traffic-phy-l1-l2.jpg)

**Traffic on three layers of the same record.** L2 generates real MAC frames
from up to four streams with a round-robin, weighted round-robin or IMIX
scheduler and workload profiles (AI training all-reduce bursts, LLM inference
token streams, storage, web, video) with burst-completion KPIs; the impairment
emulator drops, duplicates, misorders and corrupts a declared share of frames.
L1 is a Clause 49 64b/66b PCS with block lock, sync-header monitor and 66/64
overhead. The audit rows close accounting identities across the layers on
every record (frame conservation, detected = OK + bad FCS, emulated losses ⊆
losses, FCS catches every emulated corruption, WRR share ≈ weights, block
lock, overhead).

![DR4 procedure with golden correlation and eight-case stress space](docs/media/08-dr4-stress-golden.jpg)

**DR4 v1.2 stress space and golden correlation.** Eight cases on the full
SSPRQ period: two dispersion extremes × three polarization splits, a
multipath-reflection pair at the TX return-loss tolerance and a stress-RIN
case at the optical source. A `labpro-golden/1` dataset exported from a real
DCA closes the correlation step; the synthetic example only exercises the
pipeline and stays PROXY.

![Stressed receiver calibration on SECQ with RX BER verdict](docs/media/09-stressed-rx-secq.jpg)

**Stressed receiver (SECQ).** Sinusoidal jitter plus RIN at the source are
bisected until the SECQ at the reference receiver reaches the registry target
(or a declared one); the RX BER is then measured on a long record with a
Clopper-Pearson verdict against the PMD pre-FEC limit.

![Compliance panel with registry limits, margins and separate model/compliance chips](docs/media/10-compliance.jpg)

**Compliance panel.** One row per measurement contract of the active profile,
registry limit with clause/table, margin bar with uncertainty, a model verdict
and a separate compliance chip that stays NOT ASSESSED; JSON/Markdown report
export from the same record.

![Scope with declared fixture and regularized de-embedding](docs/media/11-scope-fixture-deembed.jpg)

**DCA fixture and de-embedding.** The scope declares a √f fixture between DUT
and DCA and removes it with a regularized inverse filter on the same record,
for both EYE and WAVE; the jitter panel adds the DCA jitter-mode pair J2/J9
(measured and dual-Dirac extrapolated).

![Jitter panel with J2/J9 readout](docs/media/12-jitter-j2-j9.jpg)

### 8. Golden correlation with real instrument data, instrument-style reports, SCPI

![Golden library correlation table in the DR4 panel](docs/media/13-golden-library.jpg)

**Correlation with measured waveforms.** The package ships the six 53.125 GBd
PAM4 optical waveforms contributed to the IEEE P802.3bs SMF ad hoc (Cisco
transmitter, Tektronix DSA8300 + 80C10, exported through Keysight FlexDCA)
as a decimated library with provenance and SHA-256 of the originals. LabPro
locks to the generator pattern in software (PRBS11 on the MSB and a delayed,
inverted copy on the LSB) and measures TDECQ with the reference equalizer
optimized for minimum TDECQ. At the instrument's receiver bandwidth the
LabPro values fall inside, or within 0.2 dB of, the FlexDCA 5-tap range on
all six captures:

| Capture | Equivalent BW | FlexDCA 5T (main tap 2/3/4) | LabPro @ instrument BW | LabPro @ clause 0.5·Bd |
| --- | --- | --- | --- | --- |
| 70G | 52.50 GHz | 2.06 – 2.82 dB | 3.02 dB (+0.20) | 4.23 dB |
| 55G | 41.25 GHz | 2.39 – 3.17 dB | 3.25 dB (+0.08) | 4.54 dB |
| 43G | 32.26 GHz | 2.82 – 3.70 dB | 3.54 dB (in range) | 4.93 dB |
| 39G | 29.86 GHz | 3.12 – 3.85 dB | 3.88 dB (+0.03) | 5.58 dB |
| 32G | 24.00 GHz | 3.69 – 4.57 dB | 4.40 dB (in range) | 6.32 dB |
| 28G | 20.97 GHz | 4.48 – 5.81 dB | 4.95 dB (in range) | 7.27 dB |

The references date from March 2017 (802.3bs Draft 2.2 preset, receiver at
0.728·baud), so this is a model correlation with a declared tolerance of
0.5 dB, not a compliance claim; the clause-bandwidth column is what the
published standard asks for. A FlexDCA CSV export of your own transmitter
can be loaded the same way.

![RFC 2544 report in the Xena2544 structure inside the traffic panel](docs/media/14-rfc2544-report.jpg)

**Reports shaped like the instruments' own.** The traffic panel runs RFC 2544
(throughput binary search, latency/jitter, frame loss, back-to-back) and
ITU-T Y.1564 (service configuration and performance tests with the MEF KPIs
IR, FTD, FDV, FLR, availability) and exports them with the sections and
column names of the Valkyrie2544 and SAMComplete reports (Markdown, XML,
CSV). The BERT checker shows the MP1900A "Result PAM4" box: MSB/LSB error
ratio and count split into insertions and omissions, plus the 12-case PAM4
symbol-error matrix. Every report states its declared boundary: one serial
lane, no packet DUT, losses from the PHY bit errors.

**Remote control.** The bench answers SCPI over TCP like a real instrument:
`*IDN?`, `MEASure:EYE:TDEQ?`, `CALCulate:DATA:EALarm? "CURRent:ER:TOTal"`,
`SOURce:JITTer:SJ:AMPLitude`, `TRAFfic:RFC2544:RUN`, and a generic
`CONFigure:PARameter` for every field. See [docs/SCPI.md](docs/SCPI.md).

## Quick start

Install the published package in an isolated application environment:

~~~bash
pipx install serdes-optical-lab      # or: pip install serdes-optical-lab
serdes-lab                           # opens the bench on http://localhost:8640
~~~

The same command starts the SCPI server on `127.0.0.1:5025` for
PyVISA scripts (see [SCPI remote control](docs/SCPI.md)).

### Requirements

- Python 3.12;
- NumPy, SciPy, pandas, Tornado, Plotly, and scikit-rf are installed with the package;
- a modern web browser;
- optional development tools: pytest, Ruff, Playwright, and ImageMagick.

Clone, create an isolated environment, and install the Lab PRO package:

~~~bash
git clone https://github.com/andreagaucho88/Serdes_Simulator.git
cd Serdes_Simulator
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
serdes-lab --port 8640
~~~

Then open [http://localhost:8640](http://localhost:8640). On macOS you can
also double-click <code>avvia_labpro.command</code>.

For development, the legacy UI, and optional references:

~~~bash
python -m pip install -e ".[dev,legacy,reference]"
python -m pytest -m "not slow" -q
~~~

The server binds to localhost. Stop it with <code>Ctrl+C</code>; shutdown
stops the LiveBench cleanly without leaving a traceback.

Lab PRO persists the active configuration and chamber settings in a private
per-user state file, not inside the installed Python package. The default is
<code>~/Library/Application Support/SerDes Optical Lab PRO/session.json</code>
on macOS, <code>$XDG_STATE_HOME/serdes-optical-lab/session.json</code> (or
<code>~/.local/state/...</code>) on Linux, and the local application-data
directory on Windows. Writes are atomic and the file is created with user-only
permissions where the platform supports them.

Use an ephemeral session or choose an explicit location when needed:

~~~bash
serdes-lab --no-persist
serdes-lab --state-file ./private-session.json
SERDES_LAB_STATE_FILE=./private-session.json serdes-lab
~~~

The read-only [health endpoint](http://localhost:8640/api/health) reports the
service/package version, API version, acquisition state, active experiment,
persistence health, and actual SCPI readiness without disclosing the local
state-file path. The macOS launcher waits for this endpoint instead of relying
on a fixed delay.

## Using the workbench

### Top bar

- **Preset** loads one of seven educational scenarios or one of 17 IEEE/OIF
  contexts.
- **RUN / STOP** starts or pauses server-side acquisition.
- **Record** shows the number of accumulated acquisitions.
- **Seed** makes noise, pattern generation, and stress reproducible.
- **IT / EN** switches panels, tooltips, Academy content, and messages.
- **Views** loads a themed workspace: Full bench, Essential, Source and TX,
  Channel and optics, RX and DSP, Live analysis, BERT and traffic, P/N scope,
  or Academy.
- **Reset** restores the selected preset and invalidates dependent
  accumulations.

### Grouped tab workspace

The left palette follows signal flow. Clicking an entry opens it as a tab. A
singleton panel that is already open is activated instead of duplicated.
Scope is intentionally multi-instance so that up to four coherent reference
planes can be compared.

- Drag a tab to reorder it or move it to another group.
- Drag a group to change the section order.
- Use the card buttons to open Academy help, reset local state, or close it.
- Use the left and right arrow keys to move through the active tab group.
- Workspace order, collapsed groups, active tab, language, and plot camera
  survive reloads.
- Hidden panels are lazy: only the active instrument polls and renders.

### Shared control contract

Every slider or selector updates the shared <code>LinkConfig</code>. The
server increments the configuration version, cancels any obsolete worker,
clears counters that can no longer be compared, and broadcasts the new state
over WebSocket. The small hash in the status bar verifies that two panels are
observing the same configuration.

The **?** button next to a control explains:

1. the affected physical plane;
2. the expected effect;
3. the readout to observe;
4. a suggested paired experiment;
5. activation conditions;
6. the model boundary;
7. the API field actually changed.

The **?** button in a card title opens the corresponding Academy page.

## 32 instrument panels

The public workbench contains 32 panels organized by signal flow:

| Domain | Panels |
| --- | --- |
| Overview | Signal chain, Academy |
| Source and TX | BERT, TX FIR/DAC/driver |
| Channel and optics | Electrical channel, COM, modulator/fiber |
| Receiver and DSP | RX front end, PD, TIA, AGC, CTLE, ADC, CDR, FSE/DFE, decisions |
| Live instruments | DCA (fixture/de-embed), jitter/TIE (J2/J9), spectrum, BER, FEC, traffic PHY · L1 · L2, CMIS-lite |
| Procedures | Sweep, JTOL, training, AN/LT, Compliance, DR4 (stress space + golden library), alignment, ledger, physics audit |

Each entry documents purpose, controls, readouts, a suggested experiment, and
the boundary between implemented physics and educational approximation.

**[Open the complete 32-panel reference →](docs/PANELS.md)**

## Educational presets

| Preset | Recommended use |
| --- | --- |
| 112G educational, 2 km at 1550 nm | Course baseline: 56 GBd PAM4 in C-band |
| Back-to-back | Reference without fiber penalty |
| 10 km stress: CD fading | IM/DD notch and equalization limit |
| 100GBASE-LR1 context | O-band, 53.125 GBd, 10 km |
| Severe electrical channel | CTLE/FSE/DFE against 20 dB at Nyquist |
| Noisy receiver | TIA sensitivity and noise budget |
| Link with margin: FEC at work | Observe corrected KP4 codewords |

The 17 standard profiles add 10G, 25G, 50G, 100G, 400G, and 800G Ethernet;
CEI-56G/112G/224G; and P802.3dj contexts. They are not certification presets.

## Persistence and coherence

- <code>LinkConfig</code> is an immutable dataclass with 136 serializable
  fields.
- The server atomically saves configuration, the active standards profile,
  and chamber settings in the laboratory session file. Acquisition always
  follows the explicit startup flag instead of silently resuming RUN.
- The browser saves layout, language, active tab, and plot camera locally.
- Every response carries configuration version/hash and record identity.
- Long-running workers are tied to the version that started them.
- WebSocket disconnects and rapid reloads are consumed without orphaned
  asynchronous futures.
- Config import/export uses a versioned JSON contract.

Use Reset in the UI for a clean session. Before manually removing a session
file, stop the server and keep a copy if its configuration matters.

## Local API

The UI uses the same API that is available for local inspection and
automation:

| Endpoint | Method | Purpose |
| --- | --- | --- |
| <code>/api/health</code> | GET | Package/API version, persistence, acquisition, experiment, and SCPI readiness |
| <code>/api/state</code> | GET | Configuration, presets, language metadata, RUN state |
| <code>/api/config</code> | POST | Atomic patch of LinkConfig fields |
| <code>/api/config/export</code> | GET | Versioned configuration export |
| <code>/api/config/import</code> | POST | Versioned configuration restore |
| <code>/api/preset</code> | POST | Load an educational or standard profile |
| <code>/api/run</code> | POST | Start or stop acquisition |
| <code>/api/reset</code> | POST | Reset bench state |
| <code>/api/chamber</code> | POST | Validated climate-chamber cycle, ramp, or soak settings |
| <code>/api/s2p</code> | POST | Validate and apply Touchstone text |
| <code>/api/panel/&lt;name&gt;</code> | GET | Build a panel payload |
| <code>/api/experiment/&lt;name&gt;</code> | POST | Sweep, training, JTOL, traffic, ONT, stressed-eye and procedures |
| <code>/api/experiment/stressed-rx</code> | POST | Stressed receiver: SJ + RIN bisection to the SECQ target, RX BER verdict |
| <code>/api/golden</code> | GET / POST | Golden-instrument dataset (<code>labpro-golden/1</code>) and its correlation |
| <code>/api/scope?fix=&lt;dB&gt;&amp;deembed=1</code> | GET | EYE/WAVE with a declared fixture and regularized de-embedding |
| <code>/api/report/standards?format=json|md</code> | GET | Traceable compliance report from the same record |
| <code>/api/golden/library</code> | GET | Bundled golden libraries (IEEE 802.3bs SMF ad hoc waveforms) |
| <code>/api/experiment/golden-library</code> | POST | Systematic LabPro-vs-instrument correlation over a library |
| <code>/api/experiment/rfc2544</code>, <code>/api/experiment/y1564</code> | POST | Instrument-style procedures on the current bench |
| <code>/api/report/rfc2544</code>, <code>/api/report/y1564</code>, <code>/api/report/bert</code> | GET | Xena2544 / SAMComplete / MP1900A-style exports (json, md, xml, csv) |
| <code>/api/scope/fixture</code> | GET / POST | Measured S-parameter fixture for scope de-embedding |
| TCP <code>127.0.0.1:5025</code> | SCPI | PyVISA-compatible remote control (`docs/SCPI.md`) |
| <code>/ws</code> | WebSocket | State, invalidation, record, and progress updates |

Example:

~~~bash
curl -s http://localhost:8640/api/state
curl -s -X POST http://localhost:8640/api/config \
  -H 'Content-Type: application/json' \
  -d '{"channel_il_nyquist_db": 16.0, "fec_mode": "kp4"}'
~~~

The API is local, unauthenticated, single-user, and does not promise the
stability of a public product API.

## Using the Python engine directly

~~~python
from dataclasses import replace

from serdes_sim import LinkConfig, simulate, sweep

cfg = replace(
    LinkConfig(),
    link_medium="copper",
    channel_il_nyquist_db=16.0,
    fec_mode="kp4",
)

result = simulate(cfg, seed=7, depth="full")
print(result.metrics)
print(result.checkpoints)

curve = sweep(
    cfg,
    field="channel_il_nyquist_db",
    values=[8.0, 12.0, 16.0, 20.0],
    seed=7,
)
~~~

The result contains physical-plane records, metrics, metadata, the signal
ledger, and checkpoints. Source types and repository tests define the exact
contract.

## Repository layout

~~~text
simulatore/
├── labpro/                  Tornado server and Lab PRO frontend
│   ├── server.py
│   └── static/              HTML, CSS, JavaScript, local Plotly bundle
├── serdes_sim/              GUI-independent physical engine
│   ├── blocks/              TX, channel, optics, RX, ADC, DSP, FEC, metrics
│   ├── engine.py            simulate() and sweep()
│   ├── procedures.py        DR4 and versioned procedures
│   ├── config.py            LinkConfig, presets, standard profiles
│   ├── ami.py               IBIS-AMI loader and demo model
│   └── selftest.py          end-to-end smoke test
├── tests/                   numerical, API, UI-contract regression suite
├── tools/
│   └── capture_readme_gifs.py
├── docs/
│   ├── PANELS.md            complete 32-instrument reference
│   ├── QUICK_DEMO.md        guided three-minute product tour
│   ├── VALIDATION.md        verified claims and test evidence
│   └── media/               seven real-UI GIFs and eight feature screenshots
├── app/                     frozen legacy Streamlit interface
├── CONTRIBUTING.md          development and pull-request workflow
├── ROADMAP.md               planned product evolution
└── LICENSE                  MIT license
~~~

## Verification and quality gates

Run from the <code>simulatore</code> directory:

~~~bash
python -m pytest tests -q
python -m serdes_sim.selftest
node --check labpro/static/app.js
python -m compileall -q serdes_sim labpro
git diff --check
~~~

The <code>dev</code> extra installs the declared setuptools backend and wheel.
This also makes <code>python -m build --no-isolation</code> valid after the
development install; without that extra, prefer the isolated command shown
above so the build frontend can provision <code>setuptools&gt;=77</code>.

Current validated state: **502/502 tests pass**, physical self-test
**13/13**, JavaScript syntax, Python compilation, and whitespace checks clean.

The additional browser audit traverses all 32 panels in both IT and EN,
verifies singleton and active-tab behavior, all four BERT views, DCA EYE/WAVE,
control propagation, a real Touchstone 2.x upload, and rapid reloads. Numerical
tests also preserve the frozen notebook-v7 baseline.

For the exact evidence and claim boundaries, see the
[validation report](docs/VALIDATION.md).

## Regenerating the GIFs

With the server listening on port 8640:

~~~bash
python tools/capture_readme_gifs.py --base http://127.0.0.1:8640
~~~

The script:

1. launches Playwright using an available Chromium browser;
2. saves the current configuration and RUN state in an isolated browser
   profile;
3. switches the UI to English;
4. visits real tabs and captures 1440 by 900 frames;
5. builds seven optimized 1000 by 625 GIFs with ImageMagick;
6. restores the initial bench state even if capture fails.

Options:

~~~bash
python tools/capture_readme_gifs.py --help
~~~

Do not edit generated GIFs without updating the script. The tour must remain
reproducible and faithful to the current interface.

## Troubleshooting

### The page does not open

Check that the process is running and the port is available:

~~~bash
curl -s http://localhost:8640/api/state
~~~

If port 8640 is occupied, start the server on another port and use the
matching browser URL.

### A panel shows stale data

Check the configuration version/hash in the status bar, allow the current
record to complete, and reload. A parameter change intentionally invalidates
accumulation. If needed, use STOP, Reset, then RUN.

### The link is DOWN

Open Signal chain, Checkpoints and signal ledger, Timing/CDR, and Decisions in
that order. Verify TX output, ADC range utilization, clipping, pattern lock,
and CDR lock.

Missing BER, GMI, or post-FEC metrics while the link is down are correct
behavior.

### A Touchstone file is rejected

Check the extension and port count, strictly increasing frequencies, RI/MA/DB
format, uniform reference impedance, and S4P port-pair mapping. Touchstone 2.x
uses scikit-rf, which must be installed in the same interpreter as the
server.

### GIF regeneration fails

Install Playwright and ImageMagick, and make a Playwright Chromium browser
available in its standard cache. The script emits an explicit error if
<code>magick</code> is unavailable.

### A vendor AMI model does not appear in the legacy workbench

For safety, the Streamlit reference UI discovers executable AMI libraries
only in <code>~/.serdes_sim_ami_models</code>. Copy the trusted `.so`, `.dylib`,
or `.dll` there, or set <code>SERDES_AMI_MODEL_DIR</code> before starting the
process. Symlinks that resolve outside that directory are ignored.

## Known limitations

- This is not a compliance instrument and does not replace a golden
  instrument.
- The model is system-level rather than transistor- or layout-level.
- COM and JTOL are educational proxies with declared boundaries.
- CMIS and traffic tests are functional subsets.
- DR4 covers dispersion × polarization, a reflection pair and stress RIN,
  but traceable instrument uncertainty is still missing and the stress RIN
  value is declared (clause RIN_21.4OMA to verify).
- The golden correlation uses 2017 draft-era FlexDCA references at the
  instrument's receiver bandwidth; it is a model correlation with a
  declared tolerance, not a certification, and it covers TDECQ only.
- RFC 2544 and Y.1564 reports keep the instruments' structure but run on
  one serial lane without a packet DUT: no queues, no policer, latency from
  a block budget plus the measured analog delay.
- The SCPI server mirrors instrument mnemonics without their full grammars
  and is unauthenticated on the loopback interface.
- Traffic is one serial lane without a switch, queues or congestion; there
  are no header modifiers or payload-timestamp latency measurements.
- RIN at the source and the receiver noise-current model are alternatives
  selected by a declared flag; the frozen baseline keeps the receiver model.
- IBIS-AMI behavior depends on each vendor library and contract.
- The Streamlit UI is legacy and receives security maintenance but no new
  features.

Use [GitHub Issues](https://github.com/andreagaucho88/Serdes_Simulator/issues)
for public bug reports, feature requests, and roadmap discussions.

## License and intended use

Original SerDes Optical Lab PRO code is released under the
[MIT License](LICENSE). Plotly.js, the bundled fonts, and IEEE reference data
retain their respective rights and licenses; see
[Third-party notices](THIRD_PARTY_NOTICES.md).

For design, procurement, or compliance decisions, always correlate the model
with the applicable specification, component data, and traceable
measurements.
