Crate ruqu 

ruQu - Classical Nervous System for Quantum Machines

Real-time syndrome processing and coherence assessment for quantum systems.

This crate provides high-throughput, low-latency data pipelines for ingesting, buffering, and transforming quantum error syndromes into coherence-relevant signals.

Architecture

ruQu is organized into several bounded contexts following Domain-Driven Design:

• Syndrome Processing (Supporting Domain): High-throughput data acquisition
• Coherence Gate (Core Domain): Real-time structural assessment
• Tile Architecture: 256-tile WASM fabric for parallel processing

The system uses a two-layer classical control approach:

1. RuVector Memory Layer: Pattern recognition and historical mitigation retrieval
2. Dynamic Min-Cut Gate: Real El-Hayek/Henzinger/Li O(n^{o(1)}) algorithm

Quick Start

use ruqu::syndrome::{DetectorBitmap, SyndromeRound, SyndromeBuffer};

// Create a detector bitmap for 64 detectors
let mut bitmap = DetectorBitmap::new(64);
bitmap.set(0, true);
bitmap.set(5, true);
bitmap.set(63, true);

assert_eq!(bitmap.fired_count(), 3);

// Create a syndrome round
let round = SyndromeRound {
    round_id: 1,
    cycle: 1000,
    timestamp: 1705500000000,
    detectors: bitmap,
    source_tile: 0,
};

// Buffer rounds for analysis
let mut buffer = SyndromeBuffer::new(1024);
buffer.push(round);

Three-Filter Decision Logic

The coherence gate uses three stacked filters:

1. Structural Filter: Min-cut based stability assessment
2. Shift Filter: Drift detection from baseline patterns
3. Evidence Filter: Anytime-valid e-value accumulation

All three must pass for PERMIT. Any one can trigger DENY or DEFER.

Performance Targets

• Gate decision latency: < 4 microseconds p99
• Syndrome ingestion: 1M rounds/second
• Memory per tile: 64KB
• Total latency budget: ~2,350ns

Feature Flags

• structural - Enable min-cut based structural filter (requires ruvector-mincut)
• tilezero - Enable TileZero arbiter integration (requires cognitum-gate-tilezero)
• simd - Enable SIMD acceleration for bitmap operations
• wasm - WASM-compatible mode (disables native SIMD)
• full - Enable all features

Re-exports

pub use error::Result;

pub use error::RuQuError;

pub use filters::EdgeId as FilterEdgeId;

pub use filters::EvidenceAccumulator;

pub use filters::EvidenceFilter;

pub use filters::EvidenceResult;

pub use filters::FilterConfig;

pub use filters::FilterPipeline;

pub use filters::FilterResults;

pub use filters::RegionMask;

pub use filters::ShiftFilter;

pub use filters::ShiftResult;

pub use filters::StructuralFilter;

pub use filters::StructuralResult;

pub use filters::SystemState;

pub use filters::Verdict;

pub use syndrome::BufferStatistics;

pub use syndrome::DetectorBitmap;

pub use syndrome::SyndromeBuffer;

pub use syndrome::SyndromeDelta;

pub use syndrome::SyndromeRound;

pub use tile::GateDecision;

pub use tile::GateThresholds;

pub use tile::LocalCutState;

pub use tile::PatchGraph;

pub use tile::PermitToken;

pub use tile::ReceiptLog;

pub use tile::TileReport;

pub use tile::TileZero;

pub use tile::WorkerTile;

pub use types::ActionId;

pub use types::CycleId;

pub use types::RoundId;

pub use types::SequenceId;

pub use types::TileId as DomainTileId;

pub use types::RegionMask as DomainRegionMask;

pub use types::GateDecision as DomainGateDecision;

pub use fabric::CoherenceGate;

pub use fabric::DecisionStats;

pub use fabric::FabricBuilder;

pub use fabric::FabricConfig;

pub use fabric::FabricState;

pub use fabric::FilterSummary;

pub use fabric::PatchMap;

pub use fabric::QuantumFabric;

pub use fabric::TileAssignment;

pub use fabric::WitnessReceipt;

pub use fabric::linear_patch_map;

pub use fabric::surface_code;

pub use fabric::surface_code_d7;

pub use mincut::DynamicMinCutEngine;

pub use mincut::MinCutResult;

pub use decoder::Correction;

pub use decoder::DecoderConfig;

pub use decoder::MWPMDecoder;

pub use decoder::StreamingDecoder;

pub use attention::AttentionConfig;

pub use attention::AttentionStats;

pub use attention::CoherenceAttention;

pub use attention::GatePacketBridge;

pub use adaptive::AdaptiveStats;

pub use adaptive::AdaptiveThresholds;

pub use adaptive::DriftConfig;

pub use adaptive::DriftDetector;

pub use adaptive::DriftDirection;

pub use adaptive::DriftProfile;

pub use adaptive::LearningConfig;

pub use metrics::Counter;

pub use metrics::Gauge;

pub use metrics::Histogram;

pub use metrics::MetricsCollector;

pub use metrics::MetricsConfig;

pub use metrics::MetricsSnapshot;

pub use parallel::ParallelConfig;

pub use parallel::ParallelFabric;

pub use parallel::ParallelStats;

pub use parallel::parallel_aggregate;

pub use stim::ErrorPatternGenerator;

pub use stim::StimSyndromeSource;

pub use stim::SurfaceCodeConfig;

pub use stim::SyndromeStats;

Modules

adaptive

Adaptive Threshold Learning

attention

Mincut-Gated Attention Integration

decoder

Quantum Error Decoder Integration

error

Error types for the ruQu coherence gate system

fabric

QuantumFabric Orchestration Layer

filters

Three-Filter Decision Pipeline for ruQu Coherence Gate

metrics

Observability and Metrics

mincut

Real Dynamic Min-Cut Integration

parallel

Parallel Processing for 256-Tile Fabric

prelude

Prelude module for convenient imports Commonly used types for syndrome processing, filters, and tile architecture.

schema

Data Model and Schema for ruQu

stim

Stim Integration for Real QEC Simulation

syndrome

Syndrome Processing Module

tile

256-Tile Coherence Gate Architecture for ruQu

traits

Standard Interface Traits for ruQu

types

Core domain types for the ruQu coherence gate system

Constants

DEFAULT_BUFFER_CAPACITY

Default buffer capacity in rounds

MAX_DETECTORS

Maximum number of detectors supported (1024 = 16 * 64 bits)

NAME

Crate name

TILE_COUNT

Total number of tiles in the fabric

TILE_MEMORY_BUDGET

Memory budget per tile in bytes (64KB)

VERSION

Crate version

WORKER_TILE_COUNT

Number of worker tiles (excluding TileZero)