ruQu: Quantum Execution Intelligence Engine

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

Platform Overview

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:

What Makes It Different

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.

The Five Layers

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

Module Reference

Layer 0: Core Engine (13 modules)

The foundation: circuit construction, state evolution, and backend dispatch.

Layer 1: Scientific Instrument (9 modules)

Everything needed to run quantum circuits as rigorous science.

Layer 2: SOTA Differentiation (3 modules)

Where ruQu separates from every other framework.

Layer 3: QEC Control Plane (2 modules)

Real-time quantum error correction infrastructure.

Layer 4: Theoretical Foundations (2 modules)

Provable complexity results and formal analysis.

Layer 5: Proof Suite (1 module)

Quantitative evidence that the architecture delivers measurable advantages.

Totals

Coherence Gating

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

Why Coherence Gating Matters

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.

Validated Results

Performance

Try It in 5 Minutes

Option 1: Add to Your Project

cargo add ruqu --features structural

use 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(())
}

Option 2: Run the Interactive Demo

git clone https://github.com/ruvnet/ruvector
cd ruvector
cargo run -p ruqu --bin ruqu_demo --release -- --distance 5 --rounds 1000 --error-rate 0.01

Option 3: Use the Quantum Execution Engine (ruqu-core)

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

Ecosystem

Tutorials

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"),
    }
}

Syndrome Data -> [Structural] -> [Shift] -> [Evidence] -> Decision
                    |              |             |
               Min-cut OK?    Distribution    E-value
                               stable?       accumulated?

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]);
    }
}

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 */ }
        }
    }
}

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

Architecture

System Diagram

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

256-Tile Fabric (Coherence Gating)

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

Security

Application Domains

Limitations

Roadmap

References

Academic

• 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

Project

• ADR-QE-001: Quantum Engine Core Architecture
• ADR-QE-015: Execution Engine Module Map

License

MIT OR Apache-2.0

ruQu -- Quantum execution intelligence in pure Rust.

ruv.io • RuVector • Issues

_{Built by ruv.io}