ruQu: Classical Nervous System for Quantum Machines

---

Integrity First. Then Intelligence.

ruQu is a classical nervous system for quantum machines, and it unlocks a new class of AI-infused quantum computing systems that were not viable before.

Most attempts to combine AI and quantum treat AI as a tuner or optimizer. Adjust parameters. Improve decoders. Push performance. That assumes the quantum system is always safe to act on. In reality, quantum hardware is fragile, and blind optimization often accelerates failure.

ruQu changes that relationship.

By measuring structural integrity in real time using boundary-to-boundary min-cut, ruQu gives AI a sense of when the quantum system is healthy and when it is approaching breakage. That turns AI from an aggressive optimizer into a careful operator. It learns not just what to do, but when doing anything is a mistake.

This enables a new class of systems where AI and quantum computing co-evolve safely. The AI learns noise patterns, drift, and mitigation strategies—but only applies them when integrity permits. Stable regions run fast. Fragile regions slow down or isolate. Learning pauses instead of corrupting state. The system behaves less like a brittle experiment and more like a living machine with reflexes.

Security Implications

ruQu enables adaptive micro-segmentation at the quantum control layer. Instead of treating the system as one trusted surface, it continuously partitions execution into healthy and degraded regions:

• Risk is isolated in real time — suspicious correlations are quarantined before they spread
• Control authority narrows automatically as integrity weakens
• Security shifts from reactive incident response to proactive integrity management

Application Impact

Healthcare: Enables personalized quantum-assisted diagnostics. Instead of running short, generic simulations, systems can run longer, patient-specific models of protein folding, drug interactions, or genomic pathways without constant resets. Customized treatment planning where each patient's biology drives the computation—not the limitations of the hardware.

Finance: Enables continuous risk modeling and stress testing that adapts in real time. Portfolio simulations run longer and more safely, isolating instability instead of aborting entire analyses—critical for regulated environments that require auditability and reproducibility.

AI-infused quantum computing stops being fragile and opaque. It becomes segmented, self-protecting, and operationally defensible.

---

What is ruQu?

ruQu (pronounced "roo-cue") is a Rust library that lets quantum computers know when it's safe to act.

The Problem

Quantum computers make errors constantly. Error correction codes (like surface codes) can fix these errors, but:

1. Some error patterns are dangerous — correlated errors that span the whole chip can cause logical failures
2. Decoders are blind to structure — they correct errors without knowing if the underlying graph is healthy
3. Crashes are expensive — a logical failure means starting over completely

The Solution

ruQu monitors the structure of error patterns using graph min-cut analysis:

Syndrome Stream → [Min-Cut Analysis] → PERMIT / DEFER / DENY
                        ↓
                  "Is the error pattern
                   structurally safe?"

• PERMIT: Errors are scattered, safe to continue
• DEFER: Uncertainty, proceed with caution
• DENY: Correlated errors detected, quarantine this region

Real-World Analogy

Your Body	ruQu for Quantum
Nerves detect damage before you consciously notice	ruQu detects correlated errors before logical failures
Reflexes pull your hand away from heat automatically	ruQu quarantines fragile regions before they corrupt data
You can still walk even with a sprained ankle	Quantum computer keeps running even with damaged qubits

Why This Matters

Without ruQu: Quantum computer runs until logical failure → full reset → lose all progress.

With ruQu: Quantum computer detects trouble early → isolates problem region → healthy parts keep running.

Think of it like a car dashboard:

• Speedometer: How much computational load can I safely handle?
• Engine temperature: Which qubit regions are showing stress?
• Check engine light: Early warning before logical failure
• Limp mode: Reduced capacity is better than complete failure

---

Created by ruv.io — Building the future of quantum computing infrastructure

Part of the RuVector quantum computing toolkit

---

Try It in 5 Minutes

Get a latency histogram and risk signal immediately:

# Clone and build
git clone https://github.com/ruvnet/ruvector
cd ruvector

# Run the demo with live metrics
cargo run -p ruqu --bin ruqu_demo --release -- --distance 5 --rounds 1000 --error-rate 0.01

# Output: Latency histogram, throughput, decision breakdown

╔═══════════════════════════════════════════════════════════════════╗
║                    ruQu Demo - Proof Artifact                     ║
╠═══════════════════════════════════════════════════════════════════╣
║ Code Distance: d=5  | Error Rate: 0.0100  | Rounds:   1000      ║
╚═══════════════════════════════════════════════════════════════════╝

Round │ Cut   │ Risk  │ Decision │ Regions │ Latency
──────┼───────┼───────┼──────────┼─────────┼─────────
    0 │ 13.83 │  0.00 │ PERMIT   │ 0000001 │  4521ns

Latency: P50=3.9μs  P99=26μs  Mean=4.5μs
Decisions: 100% PERMIT (low error rate)

Try with higher error rate to see DENY decisions:

cargo run -p ruqu --bin ruqu_demo --release -- --distance 3 --rounds 200 --error-rate 0.10
# Output: 62% DENY, 38% DEFER at 10% error rate

Metrics file generated: ruqu_metrics.json with full histogram data for analysis.

---

Key Capabilities

✅ What ruQu Does

Capability	Description	Latency
Coherence Gating	Decide if system is safe enough to act	<4μs
Early Warning	Detect correlated failures 100+ cycles ahead	Real-time
Region Isolation	Quarantine failing areas, keep rest running	<10μs
Cryptographic Audit	Blake3 hash chain of every decision	Tamper-evident
Adaptive Control	Switch decoder modes based on conditions	Per-cycle

❌ What ruQu Does NOT Do

• Not a decoder: ruQu doesn't correct errors — it tells decoders when/where it's safe to act
• Not a simulator: ruQu processes real syndrome data, it doesn't simulate quantum systems
• Not calibration: ruQu doesn't tune qubit parameters — it tells calibration systems when to run

---

Predictive Early Warning

ruQu is predictive, not reactive.

Logical failures in topological codes occur when errors form a connected path between boundaries. ruQu continuously measures this vulnerability using boundary-to-boundary min-cut.

In experiments, ruQu detects degradation N cycles before logical failure.

We evaluate this using three metrics:

• Lead time: how many cycles before failure the first warning occurs
• False alarm rate: how often warnings do not result in failure
• Actionable window: whether warnings arrive early enough to mitigate

ruQu is considered predictive if it satisfies all three simultaneously.

Validated Results (Correlated Burst Injection)

Metric	Result (d=5, p=0.1%)
Median lead time	4 cycles
Recall	85.7%
False alarms	2.0 per 10k cycles
Actionable (2-cycle mitigation)	100%

Cut Dynamics

ruQu tracks not just the absolute cut value, but also its dynamics:

pub struct StructuralSignal {
    pub cut: f64,        // Current min-cut value
    pub velocity: f64,   // Δλ: rate of change
    pub curvature: f64,  // Δ²λ: acceleration of change
}

Most early warnings come from consistent decline (negative velocity), not just low absolute value. This improves lead time without increasing false alarms.

Run the Evaluation

# Full predictive evaluation with formal metrics (recommended)
cargo run --example early_warning_validation --features "structural" --release

# Output includes:
# - Recall, precision, false alarm rate
# - Lead time distribution (median, p10, p90)
# - Comparison with event-count baselines
# - Bootstrap confidence intervals
# - Acceptance criteria check

# Quick demo for exploration
cargo run --bin ruqu_predictive_eval --release -- --distance 5 --error-rate 0.01 --runs 50

---

Quick Start

[dependencies]
ruqu = "0.1"

# Enable all features for full capability
ruqu = { version = "0.1", features = ["full"] }

Feature Flags

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

use ruqu::{QuantumFabric, FabricBuilder, GateDecision};

fn main() -> Result<(), ruqu::RuQuError> {
    // Build a fabric with 256 tiles
    let mut fabric = FabricBuilder::new()
        .num_tiles(256)
        .syndrome_buffer_depth(1024)
        .build()?;

    // Process a syndrome cycle
    let syndrome_data = [0u8; 64]; // From 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, quarantine"),
    }

    Ok(())
}

---

What's New (v0.2.0)

New Modules

Module	Description	Performance
adaptive.rs	Drift detection from arXiv:2511.09491	5 drift profiles detected
parallel.rs	Rayon-based multi-tile processing	2-4× speedup on multi-core
metrics.rs	Prometheus-compatible observability	<100ns overhead
stim.rs	Surface code syndrome generation	2.5M syndromes/sec

Drift Detection (Research Discovery)

Based on window-based estimation from arXiv:2511.09491:

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

Model Export/Import for Reproducibility

// Export trained model
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);

Real Algorithms, Not Stubs

Feature	Before	Now
Min-cut algorithm	Placeholder	Real El-Hayek/Henzinger/Li O(n^{o(1)})
Token signing	[0u8; 64] placeholder	Real Ed25519 signatures
Hash chain	Weak XOR	Blake3 cryptographic hashing
Bitmap ops	Scalar	AVX2 SIMD (13ns popcount)
Drift detection	None	Window-based arXiv:2511.09491
Threshold learning	Static	Adaptive EMA with auto-adjust

Performance Validated

Integrated QEC Simulation (Seed: 42)
════════════════════════════════════════════════════════
Code Distance: d=7  | Error Rate: 0.001 | Rounds: 10,000
────────────────────────────────────────────────────────
Throughput:        932,119 rounds/sec
Avg Latency:           719 ns
Permit Rate:          29.7%
────────────────────────────────────────────────────────
Learned Thresholds:
  structural_min_cut:  5.14  (from cut_mean ± σ)
  shift_max:           0.014
  tau_permit:          0.148
  tau_deny:            0.126
────────────────────────────────────────────────────────
Statistics:
  cut_mean:            5.99 ± 0.42
  shift_mean:          0.0024
  samples:             10,000
────────────────────────────────────────────────────────
Model Export:          105 bytes (RUQU binary format)
Reproducible:          ✅ Identical results with same seed

Scaling Across Code Distances:
┌────────────┬──────────────┬──────────────┐
│ Distance   │ Avg Latency  │ Throughput   │
├────────────┼──────────────┼──────────────┤
│ d=5        │      432 ns  │  1,636K/sec  │
│ d=7        │      717 ns  │    921K/sec  │
│ d=9        │    1,056 ns  │    606K/sec  │
│ d=11       │    1,524 ns  │    416K/sec  │
└────────────┴──────────────┴──────────────┘

---

Tutorials

Setting Up a Basic Gate

This tutorial walks through creating a simple coherence gate that monitors syndrome data and makes permit/deny decisions.

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

How Decisions Are Made

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?

use ruqu::filters::{
    StructuralFilter, ShiftFilter, EvidenceFilter, FilterPipeline
};

fn main() {
    // Configure thresholds
    let structural = StructuralFilter::new(5.0);   // Min-cut threshold
    let shift = ShiftFilter::new(0.3, 100);        // Max drift, window size
    let evidence = EvidenceFilter::new(0.01, 100.0); // tau_deny, tau_permit

    // Create pipeline
    let pipeline = FilterPipeline::new(structural, shift, evidence);

    // Evaluate with current state
    let state = get_current_state();
    let result = pipeline.evaluate(&state);

    println!("Structural: {:?}", result.structural);
    println!("Shift: {:?}", result.shift);
    println!("Evidence: {:?}", result.evidence);
    println!("Final verdict: {:?}", result.verdict());
}

Filter Details:

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

Tamper-Evident Decision Logging

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

    // Tampering would be detected
    // Any modification breaks the hash chain
}

Security Properties:

• Blake3 hashing: Fast, cryptographically secure
• Chain integrity: Each entry links to previous
• Constant-time verification: Prevents timing attacks

Ed25519 Signed Authorization Tokens

Actions require cryptographically signed permit tokens.

use ruqu::tile::PermitToken;
use ed25519_dalek::{SigningKey, Signer};

fn main() {
    // Generate a signing key (TileZero would hold this)
    let signing_key = SigningKey::generate(&mut rand::thread_rng());
    let verifying_key = signing_key.verifying_key();

    // Create a permit token
    let token = PermitToken {
        decision: GateDecision::Permit,
        sequence: 42,
        timestamp: current_time_ns(),
        ttl_ns: 1_000_000, // 1ms validity
        witness_hash: compute_witness_hash(),
        signature: sign_token(&signing_key, &token_data),
    };

    // Verify the token
    let pubkey_bytes = verifying_key.to_bytes();
    if token.verify_signature(&pubkey_bytes) {
        println!("✅ Valid token, action authorized");
    } else {
        println!("❌ Invalid signature, reject action");
    }

    // Check time validity
    if token.is_valid(current_time_ns()) {
        println!("⏰ Token still valid");
    }
}

Skip Computations When Coherence is Stable

When your quantum system is running smoothly, you don't need to analyze every syndrome entry. ruQu's coherence attention lets you skip up to 50% of computations while maintaining safety.

use ruqu::attention::{CoherenceAttention, AttentionConfig};
use ruqu::tile::{WorkerTile, TileReport};

fn main() {
    // Configure for 50% FLOPs reduction
    let config = AttentionConfig::default();
    let mut attention = CoherenceAttention::new(config);

    // Collect worker reports
    let reports: Vec<TileReport> = workers.iter_mut()
        .map(|w| w.tick(&syndrome))
        .collect();

    // Get coherence-aware routing
    let (gate_packet, routes) = attention.optimize(&reports);

    // Process only what's needed
    for (i, route) in routes.iter().enumerate() {
        match route {
            TokenRoute::Compute => {
                // Full analysis - this entry matters
                analyze_fully(&reports[i]);
            }
            TokenRoute::Skip => {
                // Safe to skip - coherence is stable
                use_cached_result(i);
            }
            TokenRoute::Boundary => {
                // Boundary entry - always compute
                analyze_with_priority(&reports[i]);
            }
        }
    }

    // Check how much work we saved
    let stats = attention.stats();
    println!("Skipped {:.1}% of computations", stats.flops_reduction() * 100.0);
}

How it works:

• When λ (lambda, the coherence metric) is stable, entries can be skipped
• When λ is dropping, more entries must compute
• Boundary entries (at partition edges) always compute

When to use:

• High-throughput systems processing millions of syndromes
• Real-time control where latency matters more than thoroughness
• Systems with predictable, stable error patterns

Detecting Changes in Error Rates Over Time

Based on arXiv:2511.09491, ruQu can detect when noise characteristics change without direct hardware access.

use ruqu::adaptive::{DriftDetector, DriftProfile, DriftDirection};

fn main() {
    // Create detector with 100-sample sliding window
    let mut detector = DriftDetector::new(100);

    // Stream of min-cut values from your QEC system
    for (i, cut_value) in min_cut_stream.enumerate() {
        detector.push(cut_value);

        // Check for drift every sample
        if let Some(profile) = detector.detect() {
            match profile {
                DriftProfile::Stable => {
                    // Normal operation - no action needed
                }
                DriftProfile::Linear { slope, direction } => {
                    // Gradual drift detected
                    println!("Linear drift: slope={:.4}, dir={:?}", slope, direction);
                    // Consider: Adjust thresholds, schedule recalibration
                }
                DriftProfile::StepChange { magnitude, direction } => {
                    // Sudden shift! Possible hardware event
                    println!("⚠️ Step change: mag={:.4}, dir={:?}", magnitude, direction);
                    // Action: Alert operator, pause critical operations
                }
                DriftProfile::Oscillating { amplitude, period_samples } => {
                    // Periodic noise source (e.g., cryocooler vibrations)
                    println!("Oscillation: amp={:.4}, period={}", amplitude, period_samples);
                }
                DriftProfile::VarianceExpansion { ratio } => {
                    // Noise is becoming more unpredictable
                    println!("Variance expansion: ratio={:.2}x", ratio);
                    // Action: Widen thresholds or reduce workload
                }
            }
        }

        // Check severity for alerting
        let severity = detector.severity();
        if severity > 0.8 {
            trigger_alert("High noise drift detected");
        }
    }
}

Profile Detection:

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

Save and Load Learned Parameters

Export trained models for reproducibility, testing, and deployment.

use std::fs;
use ruqu::adaptive::{AdaptiveThresholds, LearningConfig};
use ruqu::tile::GateThresholds;

// After training your system...
fn export_model(adaptive: &AdaptiveThresholds) -> Vec<u8> {
    let stats = adaptive.stats();
    let thresholds = adaptive.current_thresholds();

    let mut data = Vec::new();

    // Magic header "RUQU" + version
    data.extend_from_slice(b"RUQU");
    data.push(1);

    // Seed for reproducibility
    data.extend_from_slice(&42u64.to_le_bytes());

    // Configuration
    data.extend_from_slice(&7u32.to_le_bytes()); // code_distance
    data.extend_from_slice(&0.001f64.to_le_bytes()); // error_rate

    // Learned thresholds (5 × 8 bytes)
    data.extend_from_slice(&thresholds.structural_min_cut.to_le_bytes());
    data.extend_from_slice(&thresholds.shift_max.to_le_bytes());
    data.extend_from_slice(&thresholds.tau_permit.to_le_bytes());
    data.extend_from_slice(&thresholds.tau_deny.to_le_bytes());
    data.extend_from_slice(&thresholds.permit_ttl_ns.to_le_bytes());

    // Statistics
    data.extend_from_slice(&stats.cut_mean.to_le_bytes());
    data.extend_from_slice(&stats.cut_std.to_le_bytes());
    data.extend_from_slice(&stats.shift_mean.to_le_bytes());
    data.extend_from_slice(&stats.evidence_mean.to_le_bytes());
    data.extend_from_slice(&stats.samples.to_le_bytes());

    data // 105 bytes total
}

// Save and load
fn main() -> std::io::Result<()> {
    // Export
    let model_data = export_model(&trained_system);
    fs::write("model.ruqu", &model_data)?;
    println!("Exported {} bytes", model_data.len());

    // Import for testing
    let loaded = fs::read("model.ruqu")?;
    if &loaded[0..4] == b"RUQU" {
        println!("Valid ruQu model, version {}", loaded[4]);
        // Parse and apply thresholds...
    }

    Ok(())
}

Format Specification:

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      8     structural_min_cut (f64)
33      8     shift_max (f64)
41      8     tau_permit (f64)
49      8     tau_deny (f64)
57      8     permit_ttl_ns (u64)
65      8     cut_mean (f64)
73      8     cut_std (f64)
81      8     shift_mean (f64)
89      8     evidence_mean (f64)
97      8     samples (u64)
───────────────────────────────
Total: 105 bytes

Full QEC Simulation with All Features

Run the integrated simulation that demonstrates all ruQu capabilities.

# Build and run with structural feature
cargo run --example integrated_qec_simulation --features "structural" --release

What the simulation does:

1. Initializes a surface code topology graph (d=7 by default)
2. Generates syndromes using Stim-like random sampling
3. Computes min-cut values representing graph connectivity
4. Detects drift in noise characteristics
5. Learns adaptive thresholds from data
6. Makes gate decisions (Permit/Defer/Deny)
7. Exports the trained model for reproducibility
8. Benchmarks across error rates and code distances

Expected output:

═══════════════════════════════════════════════════════════════
     ruQu QEC Simulation with Model Export/Import
═══════════════════════════════════════════════════════════════

Code Distance: d=7  | Error Rate: 0.001 | Rounds: 10,000
────────────────────────────────────────────────────────────────
Throughput:        932,119 rounds/sec
Permit Rate:          29.7%
Learned cut_mean:      5.99 ± 0.42
────────────────────────────────────────────────────────────────
Model exported: 105 bytes
Reproducible: ✅ Identical results with same seed

Customizing the simulation:

let config = SimConfig {
    seed: 12345,           // For reproducibility
    code_distance: 9,      // Higher d = more qubits
    error_rate: 0.005,     // 0.5% physical error rate
    num_rounds: 50_000,    // More rounds = better statistics
    inject_drift: true,    // Simulate noise drift
    drift_start_round: 25_000,
};

---

Use Cases

Surface Code Experiments

For researchers running surface code experiments, ruQu provides real-time visibility into system health.

// Monitor a d=7 surface code experiment
let fabric = QuantumFabric::builder()
    .surface_code_distance(7)
    .syndrome_rate_hz(1_000_000)  // 1 MHz
    .build()?;

// During experiment
for round in experiment.syndrome_rounds() {
    let decision = fabric.process(round)?;

    if decision == GateDecision::Deny {
        // Log correlation event for analysis
        correlations.record(round, fabric.diagnostics());

        // Optionally pause data collection
        if correlations.recent_count() > threshold {
            experiment.pause_for_recalibration();
        }
    }
}

// Post-experiment analysis
println!("Correlation events: {}", correlations.len());
println!("Mean lead time: {} cycles", correlations.mean_lead_time());

Benefits:

• Detect correlated errors during experiments
• Quantify system stability over time
• Identify which qubits/couplers are problematic

Multi-Tenant Job Scheduling

Cloud providers can use ruQu to maximize QPU utilization while maintaining SLAs.

// Job scheduler with coherence awareness
struct CoherenceAwareScheduler {
    fabric: QuantumFabric,
    job_queue: PriorityQueue<Job>,
}

impl CoherenceAwareScheduler {
    fn schedule_next(&mut self) -> Option<Job> {
        let decision = self.fabric.current_decision();

        match decision {
            GateDecision::Permit => {
                // Full capacity, run any job
                self.job_queue.pop()
            }
            GateDecision::Defer => {
                // Reduced capacity, only run resilient jobs
                self.job_queue.pop_where(|j| j.is_error_tolerant())
            }
            GateDecision::Deny => {
                // System degraded, run diagnostic jobs only
                self.job_queue.pop_where(|j| j.is_diagnostic())
            }
        }
    }
}

Benefits:

• Higher QPU utilization (don't stop for minor issues)
• Better SLA compliance (warn before failures)
• Automated degraded-mode operation

Multi-QPU Coherence Coordination

For quantum networks with multiple connected QPUs, ruQu can coordinate coherence across the federation.

// Federated coherence gate
struct FederatedGate {
    local_fabrics: HashMap<QpuId, QuantumFabric>,
    network_coordinator: NetworkCoordinator,
}

impl FederatedGate {
    async fn evaluate_distributed_circuit(&self, circuit: &Circuit) -> Decision {
        // Gather local coherence status from each QPU
        let local_decisions: Vec<_> = circuit.involved_qpus()
            .map(|qpu| (qpu, self.local_fabrics[&qpu].decision()))
            .collect();

        // Network links also need to be coherent
        let link_health = self.network_coordinator.link_status();

        // Conservative: all must be coherent
        if local_decisions.iter().all(|(_, d)| *d == GateDecision::Permit)
            && link_health.all_healthy()
        {
            Decision::Permit
        } else {
            // Identify which components are problematic
            Decision::PartialDeny {
                healthy_qpus: local_decisions.iter()
                    .filter(|(_, d)| *d == GateDecision::Permit)
                    .map(|(qpu, _)| *qpu)
                    .collect(),
                degraded_qpus: local_decisions.iter()
                    .filter(|(_, d)| *d != GateDecision::Permit)
                    .map(|(qpu, _)| *qpu)
                    .collect(),
            }
        }
    }
}

Self-Healing Quantum Systems

Future quantum systems could use ruQu as part of an autonomous control loop that learns and adapts.

// Autonomous quantum control agent
struct QuantumAutonomousAgent {
    fabric: QuantumFabric,
    learning_model: ReinforcementLearner,
    action_space: Vec<ControlAction>,
}

impl QuantumAutonomousAgent {
    fn autonomous_cycle(&mut self) {
        // 1. Observe current state
        let state = self.fabric.full_state();
        let decision = self.fabric.evaluate();

        // 2. Decide action based on learned policy
        let action = self.learning_model.select_action(&state);

        // 3. ruQu gates the action
        if decision == GateDecision::Permit || action.is_safe_when_degraded() {
            self.execute_action(action);
        } else {
            // System says "no" - learn from this
            self.learning_model.record_blocked_action(&state, &action);
        }

        // 4. Observe outcome
        let next_state = self.fabric.full_state();
        let reward = self.compute_reward(&state, &next_state);

        // 5. Update policy
        self.learning_model.update(&state, &action, reward, &next_state);
    }
}

Exotic Applications:

• Self-calibrating quantum computers
• Adaptive error correction strategies
• Autonomous quantum chemistry exploration

Cryogenic FPGA/ASIC Deployment

ruQu is designed for eventual deployment on cryogenic control hardware.

// ruQu kernel for FPGA/ASIC (no_std compatible design)
#![no_std]

// Memory budget: 64KB per tile
const TILE_MEMORY: usize = 65536;

// Latency budget: 2.35μs total
const LATENCY_BUDGET_NS: u64 = 2350;

// The core decision loop
#[inline(always)]
fn gate_tick(
    syndrome: &[u8; 128],
    state: &mut TileState,
) -> GateDecision {
    // 1. Update syndrome buffer (50ns)
    state.syndrome_buffer.push(syndrome);

    // 2. Update patch graph (200ns)
    let delta = state.compute_delta();
    state.graph.apply_delta(&delta);

    // 3. Evaluate structural filter (500ns)
    let cut = state.graph.estimate_cut();

    // 4. Evaluate shift filter (300ns)
    let shift = state.shift_detector.update(&delta);

    // 5. Evaluate evidence (100ns)
    let evidence = state.evidence.update(cut, shift);

    // 6. Make decision (50ns)
    if cut < MIN_CUT_THRESHOLD {
        GateDecision::Deny
    } else if shift > MAX_SHIFT || evidence < TAU_DENY {
        GateDecision::Defer
    } else {
        GateDecision::Permit
    }
}

Target Specs:

• Latency: <4μs p99 (achievable: ~2.35μs)
• Memory: <64KB per tile
• Power: <100mW (cryo-compatible)
• Temp: 4K operation

---

Architecture

Hierarchical Processing

                    ┌─────────────┐
                    │   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]

Per-Tile Memory (64KB):

• Patch Graph: ~32KB
• Syndrome Buffer: ~16KB
• Evidence Accumulator: ~4KB
• Local Cut State: ~8KB
• Control/Scratch: ~4KB

Critical Path Analysis

Operation                    Time      Cumulative
─────────────────────────────────────────────────
Syndrome arrival            0 ns          0 ns
Ring buffer append         50 ns         50 ns
Graph delta computation   200 ns        250 ns
Worker tick (cut eval)    500 ns        750 ns
Report generation         100 ns        850 ns
TileZero merge            500 ns      1,350 ns
Global cut computation    300 ns      1,650 ns
Three-filter evaluation   100 ns      1,750 ns
Token signing (Ed25519)   500 ns      2,250 ns
Receipt append (Blake3)   100 ns      2,350 ns
─────────────────────────────────────────────────
Total                               ~2,350 ns

Margin to 4μs target: 1,650 ns (41% headroom)

---

API Reference

GateDecision

pub enum GateDecision {
    /// System coherent, safe to proceed
    Permit,
    /// Borderline, proceed with caution
    Defer,
    /// Structural issue detected, deny action
    Deny,
}

RegionMask

/// 256-bit mask for tile regions
pub struct RegionMask {
    bits: [u64; 4],
}

impl RegionMask {
    pub fn all() -> Self;
    pub fn none() -> Self;
    pub fn set(&mut self, tile_id: u8, value: bool);
    pub fn get(&self, tile_id: u8) -> bool;
    pub fn count_set(&self) -> usize;
}

FilterResults

pub struct FilterResults {
    pub structural: StructuralResult,
    pub shift: ShiftResult,
    pub evidence: EvidenceResult,
}

impl FilterResults {
    pub fn verdict(&self) -> Verdict;
}

WorkerTile

impl WorkerTile {
    pub fn new(tile_id: u8) -> Self;
    pub fn tick(&mut self, detectors: &DetectorBitmap) -> TileReport;
    pub fn reset(&mut self);
}

TileZero

impl TileZero {
    pub fn new() -> Self;
    pub fn merge(&mut self, reports: &[TileReport]) -> GateDecision;
    pub fn issue_permit(&self) -> PermitToken;
}

ReceiptLog

impl ReceiptLog {
    pub fn new() -> Self;
    pub fn append(&mut self, decision: GateDecision, seq: u64, ts: u64, witness: [u8; 32]);
    pub fn verify_chain(&self) -> bool;
    pub fn get(&self, sequence: u64) -> Option<&ReceiptEntry>;
}

---

Security

ruQu implements cryptographic security for all critical operations:

Component	Algorithm	Purpose
Hash chain	Blake3	Tamper-evident audit trail
Token signing	Ed25519	Unforgeable permit tokens
Comparisons	constant-time	Timing attack prevention

Security Audit Status

• ✅ 3 Critical findings fixed
• ✅ 5 High findings fixed
• 📝 7 Medium findings documented
• 📝 4 Low findings documented

See SECURITY-REVIEW.md for details.

---

Performance

Run the benchmark suite:

# Full benchmark suite
cargo bench -p ruqu --features structural

# Coherence simulation
cargo run --example coherence_simulation -p ruqu --features structural --release

Measured Performance (January 2026)

Metric	Target	Measured	Status
Tick P99	<4,000 ns	468 ns	✅ 8.5× better
Tick Average	<2,000 ns	260 ns	✅ 7.7× better
Merge P99	<10,000 ns	3,133 ns	✅ 3.2× better
Min-cut query	<5,000 ns	1,026 ns	✅ 4.9× better
Throughput	1M/sec	3.8M/sec	✅ 3.8× better
Popcount (1024 bits)	-	13 ns	✅ SIMD

Simulation Results

=== Coherence Gate Simulation ===
Tiles: 64
Rounds: 10,000
Surface code distance: 7 (49 qubits)
Error rate: 1%

Results:
- Total ticks: 640,000
- Receipt log: 10,000 entries, chain intact ✅
- Ed25519 signing: verified ✅
- Throughput: 3,839,921 syndromes/sec

---

Limitations & Roadmap

Current Limitations

Limitation	Impact	Mitigation Path
Simulation-only validation	Hardware behavior may differ	Partner with hardware teams for on-device testing
Surface code focus	Other codes (color, Floquet) untested	Architecture is code-agnostic; validation needed
Fixed grid topology	Assumes regular detector layout	Extend to arbitrary graphs
API stability	v0.x means breaking changes possible	Semantic versioning; deprecation warnings

What We Don't Know Yet

• Scaling behavior at d>11 — Algorithm is O(n^{o(1)}) in theory; large-scale benchmarks pending
• Real hardware noise models — Simulation uses idealized correlated bursts; real drift patterns may differ
• Optimal threshold selection — Current thresholds are empirically tuned; adaptive learning may improve

Roadmap

Phase	Goal	Status
v0.1	Core coherence gate with min-cut	✅ Complete
v0.2	Predictive early warning, drift detection	✅ Complete
v0.3	Hardware integration API	🔄 In progress
v0.4	Multi-code support (color codes)	📋 Planned
v1.0	Production-ready with hardware validation	📋 Planned

How to Help

• Hardware partners: We need access to real syndrome streams for validation
• Algorithm experts: Optimize min-cut for specific code geometries
• Application developers: Build on ruQu for healthcare, finance, or security use cases

---

References

ruv.io Resources

• ruv.io — Quantum computing infrastructure and tools
• RuVector GitHub — Full monorepo with all quantum tools
• ruQu Demo — This crate's source code

Documentation

• ADR-001: ruQu Architecture Decision Record
• DDD-001: Domain-Driven Design - Coherence Gate
• DDD-002: Domain-Driven Design - Syndrome Processing
• Simulation Integration Guide — Using Stim, stim-rs, and Rust quantum simulators

Academic References

• El-Hayek, Henzinger, Li. "Dynamic Min-Cut with Subpolynomial Update Time." arXiv:2512.13105, 2025 — The core algorithm ruQu implements
• Google Quantum AI. "Quantum error correction below the surface code threshold." Nature, 2024 — Context for QEC research
• Riverlane. "Collision Clustering Decoder." Nature Communications, 2025 — Complementary decoder technology
• Stim: High-performance Quantum Error Correction Simulator — Syndrome generation tool

---

License

MIT OR Apache-2.0

---