Persistent DCA eye → synchronized waveform → accumulated BER → in-path KP4/KR4 FEC codeword analysis.

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.

What is new in 0.2.0

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

One bench, one datapath

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 labpro/ and uses a custom Tornado/WebSocket frontend. The numerical engine in serdes_sim/ is GUI-independent. The former Streamlit interface in app/ 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. MODEL PASS/FAIL 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

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

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

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

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 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

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).

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 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 (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. 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.

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).

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

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:

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.

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.

Quick start

Install the published package in an isolated application environment:

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).

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:

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. On macOS you can also double-click avvia_labpro.command.

For development, the legacy UI, and optional references:

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

The server binds to localhost. Stop it with Ctrl+C; 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 /Library/Application Support/SerDes Optical Lab PRO/session.json on macOS, $XDG_STATE_HOME/serdes-optical-lab/session.json (or /.local/state/...) 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:

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 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 LinkConfig. 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:

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

Open the complete 32-panel reference →

Educational presets

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

• LinkConfig 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:

Example:

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

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

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 simulatore directory:

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

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.

Regenerating the GIFs

With the server listening on port 8640:

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:

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:

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 magick 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 ~/.serdes_sim_ami_models. Copy the trusted .so, .dylib, or .dll there, or set SERDES_AMI_MODEL_DIR 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 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. Plotly.js, the bundled fonts, and IEEE reference data retain their respective rights and licenses; see Third-party notices.

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