QECTOR Decoder Workbench

Professional Quantum Error Correction Analysis Suite
17 Decoders · 10 Code Families · 85-Tool MCP Server · GPU Acceleration

Website · Quick Start · Features · Downloads · CHANGELOG · License

📖 Overview

QECTOR Decoder Workbench is a production-grade desktop application for quantum error correction (QEC) research, evaluation, and documentation. Built on the high-performance qector-decoder-v3 Rust/PyO3 engine, it provides interactive decoding, batch simulation, hardware-accelerated compute, and a full local-only MCP server for LLM/AI agent integration.

Zero Install · Zero Config · Zero Dependencies Download. Double-click. Decode.

This repository is a release-only distribution mirror of the v1.0.2 Linux build. It contains no source files — only the release artifacts listed below. Binary packages are published on the Releases page.

🚀 Quick Start

Portable Binary (Recommended)

1.  Download  QectorWorkbench-Linux-v1.0.2.zip  from Releases
2.  Extract:  unzip QectorWorkbench-Linux-v1.0.2.zip
3.  Make executable:  chmod +x QectorWorkbench-Portable
4.  Launch:  ./QectorWorkbench-Portable  — no installation required
    # Debian alternative:  sudo dpkg -i qector-workbench_1.0.2_amd64.deb && qector-workbench
    The bundled decoder activates automatically on first run

CLI Mode

# Portable binary
./QectorWorkbench-Portable decode --family rotated_surface --distance 5 --decoder blossom
./QectorWorkbench-Portable benchmark --family toric --distance 7 --samples 10000
./QectorWorkbench-Portable diagnostics

# Debian package (after sudo dpkg -i qector-workbench_1.0.2_amd64.deb)
qector-workbench decode --family rotated_surface --distance 5 --decoder blossom
qector-workbench benchmark --family toric --distance 7 --samples 10000
qector-workbench diagnostics

MCP Server (AI/LLM Integration)

./QectorWorkbench-Portable --mcp
# or
qector-workbench --mcp

Launches a stdio JSON-RPC 2.0 MCP server with all 85 tools. The server is local-only and communicates through stdio; it does not open an external network connection. No window is required to run the headless MCP mode.

Note for Claude users: To seamlessly integrate these MCP tools directly into Claude Desktop or Claude Code, check out the official plugin at https://github.com/GuillaumeLessard/qector-claude-plugin — both the Windows and Linux releases of this workbench are fully compatible with it. See the Claude Plugin Compatibility section below.

📥 Downloads

v1.0.2 release assets (all available on the Releases page):

Artifact	Contents
`QectorWorkbench-Linux-v1.0.2.zip`	`QectorWorkbench-Portable` + `qector-workbench_1.0.2_amd64.deb` + `SBOM-linux.json` + `test_results_linux.txt` + `screenshots/` (10 tabs) + `EULA.txt` + `CHANGELOG.md` + `SECURITY.md`
`QectorWorkbench-Portable`	Standalone portable binary (PyInstaller, glibc >= 2.30, Python 3.12.3, ~112 MB) — no install, no root required
`qector-workbench_1.0.2_amd64.deb`	Debian package for Ubuntu 22.04+ / Debian 12+ (x86_64) — installs to `/opt/qector-workbench`, launcher `qector-workbench`

Checksums (v1.0.2):

File	SHA-256
`QectorWorkbench-Linux-v1.0.2.zip`	`0da9cdee7fb5b54bed81fd2ddbb8639e6642987b7ea0d1c00935db36e270a41e`
`QectorWorkbench-Portable`	`21484f5a81f54cacc35582d69c9325b8ab025ca7f9bc4b06bf9cfcab584f3403`

Fully local, no network required. The portable binary embeds the decoder wheel and provisions it into a per-user managed site (~/.local/share/QectorWorkbench/decoder_site/<abi_tag>) on first launch, so a lab machine with no internet access runs the complete workbench — including the MCP server. The .deb ships the same manylinux wheel under /opt/qector-workbench/offline_wheel/ and provision is identical. The same wheel can be installed manually via pip install offline_wheel/*.whl for custom Python environments.

Runtime data (logs, exported documents, managed decoder site) is written to ~/.local/share/QectorWorkbench (or $XDG_DATA_HOME/QectorWorkbench if set). Override the location entirely with the QECTOR_DATA_DIR environment variable.

Windows and Linux artifacts are built from the same air-gapped source policy and include SHA-256 manifests. macOS requires a build on Apple hardware and is not included until that build is produced and signed.

Verified v1.0.2 Build Facts

Item	Value
Workbench app	`1.0.2`
Decoder backend	`qector-decoder-v3 1.0.0` bundled wheel
MCP server	`85` tools over stdio JSON-RPC 2.0
MCP protocol	`2024-11-05`
Decoders	`17`
Code families	`10`
Bundled Python runtime	Python `3.12.3`

Repository Files

File	Purpose
`README.md`	This document
`CHANGELOG.md`	Release history
`EULA.txt`	End User License Agreement
`SECURITY.md`	Security policy
`CODE_OF_CONDUCT.md`	Code of conduct
`CONTRIBUTING.md`	Contribution guidelines
`assets/logo_banner.png`	Project banner

✨ Features

🖥️ Nine Interactive Tabs + Live Console

🔬 Code Explorer

Build and inspect 10 code families with configurable parameters. View qubit/check counts, distance, code rate, and interactive Tanner graph visualizations.

🧪 Decoder Lab

Interactive single-syndrome decoding with 17 decoder algorithms. Tunable BP-OSD parameters, resilient fallback mode, clear cache controls, and detailed correction analysis.

📊 Benchmark Suite

Configurable decode benchmarks with throughput, latency (mean / p50 / p99 / min / max), and multi-panel Matplotlib charts. Export results to JSON.

⚡ Batch & Streaming

Batch decoding with explicit CPU / CUDA / OpenCL routing. Streaming decode with sliding-window commit semantics and live logical error rate tracking.

🕘 History

Persistent decode-session history with re-inspection of past syndromes, corrections, and exported artifacts.

🖧 Hardware & System

Auto-detect CUDA, OpenCL, and CPU backends. Hardware-aware decoder recommendations via hardware_routing.recommend().

🩺 Diagnostics & Auto-Debug

Full environment/decoder/hardware self-diagnostics and qd.doctor health checks. Automatic multi-decoder fallback with complete attempt trace analysis.

📄 Documentation Studio

Deposit-ready export in 8 formats: Markdown, JSON, HTML, LaTeX, PDF, SVG, plus .zenodo.json and CITATION.cff. Reports carry a five-figure publication suite (Tanner graph, parity sparsity, decoder latency, logical failure fraction, speed/accuracy Pareto front), a Methods section, a Data Availability statement and a formatted citation.

🏷️ Lab Info & Microsoft Entra ID

Deposit metadata for generated reports: lead author, ORCID, institution, DOI, funding and keywords. It also exposes a fail-closed Microsoft Entra ID posture for lab evaluation; live identity sign-in is disabled in the air-gapped build.

🧬 Supported Code Families (10)

Family	Type	Description
`repetition`	Graphlike	1D repetition code
`ring`	Graphlike	Ring topology
`rotated_surface`	Graphlike	Rotated planar surface code
`unrotated_surface`	Graphlike	Standard planar surface code
`toric`	Graphlike	Periodic toric code
`heavy_hex`	Graphlike	IBM heavy-hexagon lattice
`hypergraph_product`	Graphlike	CSS code from repetition-code seed
`bicycle`	qLDPC	Quantum LDPC bicycle code
`bivariate_bicycle`	qLDPC	IBM bivariate bicycle (BB) code family
`color_code`	Color	Triangular & 2D color codes

⚙️ Decoder Algorithms (17)

Decoder	Strategy	Notes
`union_find`	Approximate	Fast cluster-growth matching
`fast_union_find`	Approximate	Optimized UF variant
`blossom`	Exact MWPM	Weight-optimal, matches PyMatching LER
`sparse_blossom`	Near-optimal	Sparse graph MWPM approximation
`bp_osd`	Iterative	Belief propagation + OSD for qLDPC codes
`auto`	Auto-select	Self-selects best backend
`hybrid`	Combined	Multi-strategy hybrid decoder
`lookup_table`	Exact	Table-based for small codes (≤ 20 checks)
`predecoded`	Staged	Pre-decoded syndrome correction
`auto_router`	Policy	Dispatches best decoder per code topology
`hybrid_cascade`	Staged	UF pre-filter → Blossom/BP-OSD escalation
`gnn_belief_matching`	Neural	GNN-weighted belief matching
`belief_matching`	Hybrid	BP posteriors reweight exact Blossom MWPM
`two_stage`	Decoupled	Independent X/Z sector decoders for CSS/color codes
`ambiguity_cluster`	Cluster	Partition ambiguous checks into local clusters
`colour_code`	DEM-native	BP-OSD hypergraph decoder for 3-body color codes
`space_time`	Multi-round	Space-time decoder for phenomenological & circuit-level decoding

Resilient mode: When enabled, the workbench automatically falls back through compatible decoders if the selected one cannot handle the current code family — and reports exactly what happened.

🤖 85-Tool MCP Server

Full Model Context Protocol integration for headless AI/LLM workflows:

Transport: stdio JSON-RPC 2.0 (protocol version 2024-11-05)
No HTTP bridge, no port binding — pure stdin/stdout newline-delimited JSON-RPC
All 85 tools wired to the live backend API
Per-tool 60-second timeouts, busy guards, and 10 MB frame limits protect long-running agents

Tool Categories

Category	Tools
Decoding	`decode_syndrome`, `decode_single`, `decode_with_options`, `decode_syndrome_blossom`, `decode_syndrome_cascade`, `diagnostic_decode`, `resilient_decode`, `probe_decoders`, `sparse_blossom_radix_neighbors`, `gnn_belief_match_decode`, `belief_match_decode`, `two_stage_decode`, `ambiguity_cluster_decode`, `colour_code_decode`, `decode_hyperedge`, `decode_mmap`, `decode_dem`, `compare_all_decoders`
Batch & Streaming	`batch_decode`, `batch_decode_gpu`, `parallel_batch_decode`, `native_streaming`, `stream_decode`
Benchmarking	`benchmark_decoder`, `run_benchmark`, `run_ler_benchmark`, `hybrid_cascade_stats`, `compare_benchmarks`, `decoder_benchmark_suite`, `estimate_threshold`, `finite_size_scaling`, `get_statistics`
Code Management	`list_code_families`, `list_codes`, `build_code_from_matrix`, `get_code_properties`, `analyze_code_family`, `analyze_error_patterns`, `analyze_logicals`, `generate_parity_check`, `compatible_decoders`, `compat_report`, `compatibility_matrix`, `get_decoder_info`, `list_decoders`
DEM & Stim	`build_dem`, `import_stim`
Hardware & System	`get_hardware_info`, `get_system_info`, `get_backend_health`, `native_recommend`, `recommend_decoder`
Diagnostics & Compliance	`self_diagnostics`, `doctor_diagnostics`, `version_info`, `check_updates`, `compliance_attestation`, `get_entra_posture`, `get_identity_info`, `mcp_health`, `mcp_status`, `get_server_env`
Documentation & Export	`generate_documentation`, `export_benchmark`, `export_figure`, `export_session`, `generate_reproducibility_package`
Resources & Config	`get_resources`, `get_resource`, `get_results`, `clear_results`, `delete_resource`, `register_client`, `list_clients`, `get_config`, `set_config`, `reset_config`, `clear_decoder_cache`
Licensing	`get_license_info`, `verify_license_token`, `set_license_key_file`, `flush_usage`
Research	`neural_predecoder_train`, `import_syndrome`
Meta	`list_tools`

📈 Local Benchmarking

Benchmark output is intentionally not stored or shipped because throughput and latency depend on the user's hardware, drivers, seed, and workload. Run the Benchmark tab or CLI locally when measurements are required.

🔧 CLI Reference

./QectorWorkbench-Portable <command> [options]
# or: qector-workbench <command> [options]

Global Flags

These flags are available on all commands:

Flag	Description
`--json`	Output raw results in JSON format
`--no-color`	Disable ANSI colors
`--no-banner`	Suppress ASCII header banner
`--output, -o`	Redirect output to a file (sanitized)
`--verbose, -v`	Enable verbose logging / details
`--quiet, -q`	Suppress banners and warning prints
`--config, -c`	Path to JSON config file to load parameters
`--version, -V`	Show version information and exit

Subcommands (22)

Command	Description
`decode`	Decode a single syndrome (supports `--dry-run`)
`benchmark`	Run decoder benchmarks (supports `--dry-run`)
`probe`	Probe compatible decoders for a code
`diagnostics`	Full environment & decoder diagnostics
`hardware`	Detect and report hardware backends
`list-codes`	List all available code families
`list-decoders`	List all decoder algorithms
`docgen`	Generate documentation in multiple formats
`version`	Show version information
`compare`	Compare multiple decoders on the same code
`batch`	Batch decode multiple syndromes
`stream`	Streaming decode workflow (supports `--dry-run`)
`train`	Train neural predecoder
`export`	Export a complete decode session
`import`	Import external syndrome data (CSV, JSON, .npy)
`matrix`	Return the full decoder/code compatibility matrix
`serve`	Launch local REST API service
`doctor`	Run 15-check environment diagnostic
`compliance`	Run zero-egress / offline compliance attestation
`entra`	Optional Microsoft Entra ID SSO readiness (off by default)
`decode_mmap`	Out-of-core memmap decoding of large syndromes
`completions`	Generate shell completions for bash/zsh/PowerShell

Examples

# Decode with exact Blossom MWPM on a rotated surface code
./QectorWorkbench-Portable decode \
    --family rotated_surface --distance 5 \
    --decoder blossom --error-rate 0.05

# Compare multiple decoders on a rotated surface code
./QectorWorkbench-Portable compare \
    --family rotated_surface --distance 5 \
    --decoders blossom,bp_osd,union_find

# Batch decode 1000 samples on CPU
./QectorWorkbench-Portable batch \
    --family rotated_surface --distance 5 \
    --backend cpu --samples 1000

# Run a sliding window streaming decode session
./QectorWorkbench-Portable stream \
    --family rotated_surface --distance 5 \
    --window 5 --n-rounds 100

# Train neural predecoder for a repetition code
./QectorWorkbench-Portable train \
    --family repetition --distance 3 \
    --samples 200 --epochs 5

# Export a complete session to a zip file
./QectorWorkbench-Portable export \
    --family rotated_surface --decoder blossom --output session.zip

# Import external syndrome and decode it
./QectorWorkbench-Portable import \
    --file syndrome.csv --decoder blossom --family rotated_surface --distance 5

# Display compatibility matrix as an ASCII table
./QectorWorkbench-Portable matrix --format table

# Run 15-check environment diagnostic
./QectorWorkbench-Portable doctor

# Verify the air-gapped / zero-egress compliance posture
./QectorWorkbench-Portable compliance

# Debian package equivalents (after install):
# qector-workbench decode --family rotated_surface --distance 5 --decoder blossom

📋 System Requirements

Component	Requirement
OS	Ubuntu 22.04+ / Debian 12+ (x86_64, glibc ≥ 2.30), Fedora 37+, or any glibc 2.30+ distribution
Runtime	None — portable binary bundles everything (Python 3.12.3); `.deb` uses system Python 3.10–3.12
RAM	4 GB minimum, 8 GB recommended
GPU	Optional — CUDA for GPU-accelerated batch decode
Disk	~112 MB (portable binary), ~130 MB installed via `.deb`
Display	Not required for CLI / MCP headless modes

🔬 Decoder Runtime Provisioning

The workbench uses a zero-config runtime provisioner for the qector-decoder-v3 backend:

Bundled wheel — The portable binary (QectorWorkbench-Portable) ships with an embedded, ABI-matched manylinux wheel
Managed site — Falls back to a per-user, ABI-partitioned managed site (decoder_site/<abi_tag>)
PyPI fallback — If neither is available, downloads the correct wheel from PyPI
Self-heal — On corruption, extracts the bundled wheel and rebuilds the managed site
Version purge — Outdated managed decoders from older releases are removed automatically

No internet connection is required for normal operation with the portable build.

🛡️ Air-Gapped Hardening Status

The v1.0.2 public package is designed for offline lab use after download and extraction. Implemented in this release:

Bundled decoder wheel activation works without internet access
MCP transport is stdio only; the packaged MCP mode does not bind an HTTP port
Version checks resolve against the bundled local baseline, not a network update service
Runtime data can be redirected with QECTOR_DATA_DIR
License keys are encrypted at rest with machine-derived Fernet keys; export path traversal is sanitized
All documentation exports and deposit sidecars carry SHA-256 sidecar manifests

Status tracking ships in the release package as AIR_GAPPED_HARDENING_STATUS.md.

🤖 Claude Plugin Compatibility

Both the Windows and Linux v1.0.2 releases of QECTOR Decoder Workbench are fully compatible with the official QECTOR Claude Plugin (qector-claude-plugin) for Claude Code and Claude Desktop:

The plugin's bundled qector-library (8 stable tools) and qector-bench (29 research tools) MCP servers run against the same qector-decoder-v3 1.0.0 backend that the workbench provisions — versions match exactly (qector-decoder-v3==1.0.0).
Use the workbench's --mcp server, the plugin's two stdio MCP servers, or both at once — all are local-only with zero network egress.
Claude Desktop extension: run scripts\install_windows_connector.cmd from the plugin repository to register QECTOR as a first-class Extension inside Claude Desktop Settings → Connectors (manifest_version: 0.3).

Claude Code marketplace:

claude plugin marketplace add GuillaumeLessard/qector-claude-plugin
claude plugin install qector@qector-tools

The plugin ships 13 slash commands (/qec-decode, /qec-threshold-sweep, /qec-benchmark, /qec-dem, …), 5 specialized agents (researcher, developer, validator, sysadmin, hardware engineer), 28 domain skills, and enforces the same H·c ≡ s mod 2 fail-closed verification used by the workbench.

Plugin requirements: Python 3.10+, qector-decoder-v3==1.0.0, mcp==1.2.0, NumPy.

⚠️ Honest Performance Posture

Following the upstream QECTOR Decoder v3 documentation:

All logical-error-rate, throughput, and latency figures are hardware-, driver-, seed-, and workload-dependent simulation results — regenerate them on your own target hardware before quoting.

PyMatching remains the speed leader on standard surface-code MWPM
QECTOR's exact blossom decoder matches PyMatching's logical error rate but is not faster
Key strengths: batch throughput via approximate Union-Find, qLDPC coverage via BP-OSD, and GF(2) syndrome correctness (H·c ≡ s mod 2)
This is a research and evaluation platform, not a real-time fault-tolerant hardware decoding stack

📚 Documentation

Document	Where
Quick Start Guide	In the release `.zip` (`manuals/`)
Linux User Manual	In the release `.zip` (`manuals/`)
API Reference	In the release `.zip` (`manuals/`)
API Reference PDF	In the release `.zip` (`manuals/`)
MCP Integration Guide	In the release `.zip` (`manuals/`)
LLM Reference Manual	In the release `.zip` (`manuals/`)
Air-Gapped Hardening Status	In the release `.zip`
CHANGELOG	This repository
EULA	This repository
SECURITY	This repository

Full documentation is included inside the manuals/ directory of the release package. This repository is release-only and does not host the docs folder.

📄 License

Workbench (this application)

Source-available under EULA.txt. Grants a royalty-free, worldwide license to use, execute, copy, and distribute the software for any purpose — including commercial, academic, and personal use — provided embedded "QECTOR" notices and watermarks are retained (EULA §2).

Backend (`qector-decoder-v3`)

Separately licensed, source-available Rust/Python platform by the same author:

✅ Free for personal, academic, educational, and non-commercial research
💼 Commercial use (company R&D, SaaS, hosted API, OEM, redistribution) requires a paid license
🔄 60-day commercial evaluation available, creditable against a license

The workbench depends on qector-decoder-v3 at runtime. Honor the backend's license terms for any commercial deployment.

🤝 Support & Contact


Website	www.qector.store
Commercial Licensing	admin@qector.store
Support	admin@qector.store
Pricing	qector.store/pricing

QECTOR Decoder Workbench v1.0.2
Built on qector-decoder-v3 v1.0.0 (Rust/PyO3 core)

© 2026 Guillaume Lessard / iD01t Productions
ORCID 0009-0000-3465-3753

Powered by QECTOR

Name		Name	Last commit message	Last commit date
assets		assets
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
EULA.txt		EULA.txt
README.md		README.md
SECURITY.md		SECURITY.md

Latest commit

History

Folders and files

Repository files navigation