Auto-Load-off-Test

Repeatable measurement workflows. Inspectable results. No lab required to explore.

A Python/Tkinter workbench for sweep orchestration, gain/phase analysis, reference correction, and reproducible reports.

Demo · Engineering Evidence · Architecture · Reproduce · Case Study

Auto-Load-off-Test refactors a tightly coupled lab script into a testable desktop application. The design separates operator UI, use-case orchestration, sweep and signal-processing logic, persistence, and model-specific instrument side effects. This makes the core workflow reproducible without requiring access to a physical lab bench.

Validation boundary: automated tests and demonstration evidence are hardware-free. Production adapter paths are inspectable, but this repository does not claim current live AWG/oscilloscope, metrology, or production-safety validation.

Demo

Watch the operator console demo on YouTube

The published walkthrough shows an earlier real Tkinter console revision replaying a deterministic 72-point fixture, not a live acquisition. The local MP4 fallback is retained for offline viewing. Both keep No hardware - simulated fixture visible.

Current Desktop Workflow

The current branch adds ordinary Load Demo Fixture / Replay Fixture actions, stop-and-restart playback, explicit Apply / Reset Analysis, and a reproducible Export Report workflow. These run through the same controller used by the application, without capture-only plot animation. The local acceptance record separates verified behavior from unverified hardware and native file dialogs. macOS is the UI acceptance target for this iteration; Windows UI validation is outside this delivery scope, not implied by cross-platform tests or packaging checks.

Project At A Glance

Problem	Manual generator/oscilloscope sweeps are repetitive, stateful, and easy to misconfigure.
Workflow	Configure a sweep, acquire gain/phase, apply a reference, inspect progress and warnings, then export results.
Engineering approach	Layered presentation, application, domain, persistence, and instrument-adapter boundaries.
Stack	Python 3.10+, Tkinter/ttk, Matplotlib, NumPy, SciPy, PyVISA, PyInstaller.
Reproducible evidence	Deterministic fixture/reference data, fake instrument ports, strict IO contracts, cross-platform CI, and a packaged Windows smoke.
Current boundary	Software and no-hardware workflows are validated; connected instruments and electrical behavior are not.

Engineering Evidence

1. Isolated hardware side effects

Application services depend on explicit AWG/oscilloscope ports, not on vendor commands. A capability registry defines model constraints, while the adapter registry resolves production and fake paths. The original equips.py module remains isolated as a legacy compatibility layer instead of being broadly rewritten without a physical regression bench.

2. Strict measurement and calibration contracts

Boundary validation rejects missing fields, length mismatches, non-finite gain, and non-positive, duplicate, or unsorted frequencies. The deterministic end-to-end workflow test reconstructs corrected gain and phase from raw plus reference curves, compares expected values, exports MAT/CSV/TXT, reloads MAT/CSV, and verifies source metadata.

3. Reproducible analysis without a lab workstation

The offline analysis command accepts MAT/CSV files independently of the desktop and instrument adapters. It checks gain consistency, phase availability, reference coverage, and known prior correction; then stages input snapshots, data exports, a plot, an HTML report, and a hashed JSON manifest in a new directory. Integration tests cover numerical results, metadata roundtrips, failure cleanup, existing-output protection, and a real CLI subprocess that does not import Tkinter or PyVISA.

4. Operator state is part of the system design

The console distinguishes live, loaded, and fixture data sources and allows only one mutating operation at a time. Connection, file analysis, and export run outside the Tk event loop. A stopped or failed sweep retains valid points; cleanup completes before auto-save. File analysis uses immutable input snapshots, and failed exports roll back newly created files without overwriting existing results. Warnings remain in a bounded history and shutdown diagnostics persist locally. See the operator guide for the complete workflow.

5. Distribution is tested as a workflow

GitHub Actions runs the hardware-free suite on Linux, macOS, and Windows, checks the code with Ruff, and builds a Windows PyInstaller one-folder artifact. The bundled package smoke exercises fixture load, reference correction, export, and reload from the frozen executable and records live_hardware_used: false. This is packaging evidence, not a certified release or a live-VISA test.

Architecture

flowchart LR
  UI["Tkinter operator console"] --> APP["Application use cases"]
  DEMO["Deterministic fixtures and fakes"] --> APP
  APP --> DOMAIN["Sweep, DSP, calibration, validation"]
  APP --> PORTS["Instrument ports"]
  PORTS --> REGISTRY["Capability and adapter registries"]
  REGISTRY --> LEGACY["Legacy vendor compatibility layer"]
  APP --> STORE["Settings and measurement persistence"]
  STORE --> FILES["MAT / CSV / TXT / PNG"]

Loading

The dependency direction keeps the domain and most application behavior independent from Tkinter, PyVISA, and the legacy driver module. More detail is available in the architecture note and case study.

Validation Evidence

Surface	Current evidence	What it does not prove
Sweep, DSP, calibration, and IO	Automated tests using pure logic, temporary files, deterministic arrays, and fake ports.	Instrument timing, acquisition fidelity, or calibration uncertainty.
Operator workflow	Actual Tkinter window capture from 0/72 through 72/72 with source, correction, progress, and export receipts.	A live sweep or connected-instrument workflow.
Resource discovery and adapter selection	Mock scanners, identity probes, capability preflight, and registry/factory tests.	Real VISA enumeration, *IDN? behavior, or firmware compatibility.
Windows packaging	CI-built one-folder executable plus frozen fixture/export/reload smoke.	Driver installation, code signing, every Windows theme, or live VISA access.
Stop and output-off flow	Fake-port tests for cancellation, cleanup attempts, timeouts, and warning events.	Electrical shutdown latency or fail-safe behavior on hardware.
Live bench and metrology	No current public validation record.	Any claim of live-instrument, metrology-grade, or production-certified operation.

The detailed validation matrix maps each claim to inspectable evidence and lists wording that is not supported by the repository.

Reproduce

Analyze measurement files without hardware

python -m pip install -e .
auto-load-off-test analyze demo_data/hyperframe_simulated_fixture.mat --output __data__/analysis-demo

Open __data__/analysis-demo/report.html to inspect the data, plot, processing notes, and input hashes. The command runs without Tkinter or instrument connections and produces MAT/CSV/TXT, PNG, HTML, and a JSON manifest. Optional reference correction has explicit coverage and phase checks. See the offline analysis guide for raw-fixture reconstruction, input formats, reproducibility assumptions, and error behavior.

Install and launch

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
python src/main.py

On Windows, activate the environment with .venv\Scripts\activate before installing. The installed console entry point is also available as auto-load-off-test.

To inspect the workflow without instruments, select Load Demo Fixture, then Replay Fixture. Stop partway or choose 1x / 2x / 4x playback. In Analysis, choose raw + complex to reconstruct the fixture using its bundled reference, then Apply Analysis. Reset Analysis restores the original file snapshot. Export Report saves the displayed result and its reproducibility record to a new directory. The no-hardware label remains explicit.

Run the hardware-free checks

PYTHONPATH=src python -m unittest discover -s tests
python -m ruff check src/app tests scripts

The automated suite covers sweep generation, DSP, capability validation, adapter/discovery fakes, strict measurement/reference schemas, deterministic correction and export round trips, UI receipt state, task-runner cleanup, and the package smoke.

Instrument Paths

UI-visible capability profiles and legacy-compatible adapter paths currently exist for:

Role	Registered models
AWG	DSG4102, DSG836
Oscilloscope	MDO34, MDO3024, DHO1202, DHO1204

These names describe registered software paths, not a current live-hardware compatibility certificate. Model limits, termination, coupling, transport, and validation status are defined in the capability registry. Test-only mock models are hidden from the UI.

Data And Runtime Paths

Save Data writes the displayed numeric result as MAT/CSV/TXT. Export Report adds a PNG, HTML report, input snapshots, and a SHA-256 manifest. Neither action silently replaces existing output. Imported/fixture data is not exported with unrelated instrument settings from the setup form.

Settings, automatic saves, and rotating diagnostic logs live under a stable per-user application-data root:

OS	Root
macOS	~/Library/Application Support/Auto-Load-off-Test
Windows	%APPDATA%/Auto-Load-off-Test
Linux	$XDG_DATA_HOME/Auto-Load-off-Test or ~/.local/share/Auto-Load-off-Test

__config__/settings.json
__data__/measurement/
__data__/logs/sweep-events.jsonl

AUTO_LOAD_OFF_TEST_ROOT overrides this root. Existing cwd-based settings are not silently migrated. Bundled demo resources resolve independently, including after a wheel install. See the packaging guide for Windows prerequisites and the no-hardware smoke checklist.

Technical Documentation

Topic	Document
Design decisions and tradeoffs	Case Study
Layer boundaries and dependencies	Architecture
Evidence levels and unsupported claims	Validation Matrix
Setup, replay, run, correction, and export	Operator Guide
Stop behavior and operator responsibilities	Safety Notes
Adding adapters, persistence, or UI behavior	Extending The Application
Windows one-folder build and prerequisites	Packaging
Deterministic fixture design and provenance	Demo Fixture / Demo Data

Scope And Safety

This is a local engineering tool, not a certified production test platform. Before any live run, an operator must confirm the physical instrument model and address, probe attenuation, voltage and frequency limits, termination, coupling, trigger behavior, and device-under-test constraints.

Current evidence demonstrates software architecture, deterministic data handling, operator-state design, and hardware-free distribution testing. Live VISA discovery, model/firmware compatibility, electrical output-off latency, measurement uncertainty, calibration traceability, and safe DUT operation require a documented physical bench matrix and remain intentionally unclaimed. See docs/safety.md for the full boundary.