🚀 Quantum Virtual Machine (QVM)

A high-performance, backend-agnostic quantum circuit scheduler and runtime for multi-job quantum computing

📋 Table of Contents

• Introduction
• Features
• Architecture
• Installation
• Quick Start
• Advanced Usage
• SDK & API
• Performance
• Contributing
• License

🌟 Introduction

The Quantum Virtual Machine (QVM) is a cutting-edge scheduler and runtime system designed to optimize the execution of multiple quantum circuits on quantum hardware. By intelligently partitioning device topologies and scheduling jobs with spatial and temporal multiplexing, QVM maximizes quantum resource utilization while minimizing crosstalk and execution time.

Why QVM?

• 🎯 Multi-Job Scheduling: Run multiple quantum circuits simultaneously on the same hardware
• 🔧 Hardware Agnostic: Works with any OpenQASM 3.0 compatible quantum backend
• ⚡ WASM Ready: Deploy quantum scheduling directly in web browsers
• 🛡️ Crosstalk Mitigation: Intelligent buffer zones between quantum operations
• 📊 Optimal Resource Usage: Advanced bin-packing algorithms for maximum efficiency

✨ Features

Core Capabilities

Supported Quantum Gates

// Single-qubit gates
h, x, y, z, s, sdg, t, tdg, sx, rx, ry, rz, p, u

// Two-qubit gates
cx, cy, cz, ch, cp, crx, cry, crz, swap, iswap

// Three-qubit gates
ccx (Toffoli), cswap (Fredkin)

Hardware Topologies

• Grid - 2D rectangular lattice
• Linear - 1D chain topology
• Ring - Circular connectivity
• Star - Central hub architecture
• Heavy-Hex - IBM-style hexagonal lattice
• Custom - User-defined topologies via JSON

🏗️ Architecture

graph TB
    A[OpenQASM 3 Input] --> B[Parser]
    B --> C[Circuit IR]
    C --> D[Scheduler]
    E[Hardware Topology] --> D
    D --> F[Bin-Packing]
    F --> G[Tile Assignment]
    G --> H[Composer]
    H --> I[Composite QASM Output]

📦 Installation

From Source

# Clone the repository
git clone https://github.com/ruvnet/Quantum-Virtual-Machine.git
cd Quantum-Virtual-Machine

# Build the project
cargo build --release

# Run tests
cargo test

As a Rust Dependency

Add to your Cargo.toml:

[dependencies]
qvm-scheduler = "0.1.0"

WASM Build

# Install wasm-pack
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

# Build WASM module
wasm-pack build --target web --out-dir pkg

🚀 Quick Start

Basic Usage

use qvm_scheduler::{QvmScheduler, TopologyBuilder, CircuitBuilder};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a 5x5 grid topology
    let topology = TopologyBuilder::grid(5, 5);
    
    // Initialize scheduler
    let scheduler = QvmScheduler::new(topology);
    
    // Create quantum circuits
    let bell_state = CircuitBuilder::new("bell", 2, 2)
        .h(0)?
        .cx(0, 1)?
        .measure_all()?
        .build();
    
    let ghz_state = CircuitBuilder::new("ghz", 3, 3)
        .h(0)?
        .cx(0, 1)?
        .cx(1, 2)?
        .measure_all()?
        .build();
    
    // Schedule circuits
    let circuits = vec![bell_state, ghz_state];
    let composite = scheduler.schedule(&circuits).await?;
    
    // Generate composite QASM
    let qasm = composite.to_qasm()?;
    println!("{}", qasm);
    
    Ok(())
}

CLI Usage

# Schedule quantum circuits from QASM files
qvm-scheduler schedule circuit1.qasm circuit2.qasm --topology grid:5x5

# Use custom topology
qvm-scheduler schedule *.qasm --topology-file ibm_topology.json

# Generate visualization
qvm-scheduler visualize --topology heavy-hex:27 --output topology.svg

🔧 Advanced Usage

Custom Scheduling Strategies

use qvm_scheduler::{SchedulerConfig, SchedulingStrategy, OptimizationLevel};

let config = SchedulerConfig::builder()
    .strategy(SchedulingStrategy::Hybrid)
    .optimization_level(OptimizationLevel::Aggressive)
    .enable_lookahead(true)
    .max_lookahead_depth(3)
    .build();

let scheduler = QvmScheduler::new(topology)
    .with_config(config);

Buffer Zone Configuration

use qvm_scheduler::{BufferConfig, BufferStrategy};

let buffer_config = BufferConfig::builder()
    .strategy(BufferStrategy::Adaptive)
    .min_distance(2)
    .effectiveness_threshold(0.95)
    .build();

let scheduler = QvmScheduler::new(topology)
    .with_buffer_config(buffer_config);

Topology Customization

// Load from JSON
let topology = Topology::from_json_file("custom_topology.json")?;

// Create programmatically
let mut builder = TopologyBuilder::new();
builder.add_qubit(0, Position::new(0.0, 0.0));
builder.add_qubit(1, Position::new(1.0, 0.0));
builder.add_connection(0, 1, 0.99); // 99% fidelity
let topology = builder.build();

WASM Integration

import init, { schedule_qasm } from './pkg/qvm_scheduler.js';

async function scheduleCircuits() {
    await init();
    
    const circuits = [
        'OPENQASM 3.0; qubit[2] q; h q[0]; cx q[0], q[1];',
        'OPENQASM 3.0; qubit[3] q; h q[0]; cx q[0], q[1]; cx q[1], q[2];'
    ];
    
    const topology = {
        type: 'grid',
        rows: 5,
        cols: 5
    };
    
    const result = await schedule_qasm(circuits, topology);
    console.log(result);
}

📚 SDK & API

Rust API

Core Types

// Main scheduler
pub struct QvmScheduler {
    pub fn new(topology: Topology) -> Self
    pub async fn schedule(&self, circuits: &[QuantumCircuit]) -> Result<CompositeCircuit>
}

// Circuit builder
pub struct CircuitBuilder {
    pub fn new(name: &str, qubits: usize, cbits: usize) -> Self
    pub fn h(&mut self, qubit: usize) -> Result<&mut Self>
    pub fn cx(&mut self, control: usize, target: usize) -> Result<&mut Self>
    pub fn measure(&mut self, qubit: usize, cbit: usize) -> Result<&mut Self>
    pub fn build(self) -> QuantumCircuit
}

// Topology builder
pub struct TopologyBuilder {
    pub fn grid(rows: usize, cols: usize) -> Topology
    pub fn linear(size: usize) -> Topology
    pub fn heavy_hex(size: usize) -> Topology
}

Scheduling Strategies

pub enum SchedulingStrategy {
    FirstComeFirstServed,
    ShortestJobFirst,
    PriorityBased,
    LongestJobFirst,
    Hybrid,
}

pub enum BinPackingAlgorithm {
    FirstFitDecreasing,
    BestFitDecreasing,
    WorstFitDecreasing,
    NextFitDecreasing,
}

REST API (Coming Soon)

# Submit scheduling job
POST /api/v1/schedule
Content-Type: application/json
{
  "circuits": ["qasm1", "qasm2"],
  "topology": "grid:5x5",
  "strategy": "hybrid"
}

# Get scheduling result
GET /api/v1/schedule/{job_id}

# List available topologies
GET /api/v1/topologies

Python SDK (Coming Soon)

from qvm_scheduler import QvmScheduler, TopologyBuilder

# Create scheduler
topology = TopologyBuilder.grid(5, 5)
scheduler = QvmScheduler(topology)

# Schedule circuits
circuits = [
    "OPENQASM 3.0; ...",
    "OPENQASM 3.0; ..."
]
result = scheduler.schedule(circuits)
print(result.to_qasm())

📊 Performance

Benchmarks

Optimization Results

┌─────────────────────────────────────┐
│ Benchmark: 100 Random Circuits      │
├─────────────────────────────────────┤
│ Naive scheduling:    15 batches     │
│ QVM scheduling:      8 batches      │
│ Improvement:         47% reduction  │
│ Qubit utilization:   78%            │
│ Crosstalk events:    0              │
└─────────────────────────────────────┘

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install development tools
cargo install cargo-watch cargo-edit cargo-expand

# Run in watch mode
cargo watch -x "test" -x "run --example demo"

Running Tests

# Unit tests
cargo test --lib

# Integration tests
cargo test --test '*'

# Benchmarks
cargo bench

# With coverage
cargo tarpaulin --out Html

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• OpenQASM 3.0 specification contributors
• Rust async community
• WebAssembly ecosystem
• Quantum computing research community

📞 Contact

• GitHub Issues: Report bugs or request features
• Discussions: Join the conversation