quantrs2-tytan 0.1.0-rc.1

High-level quantum annealing interface inspired by Tytan for the QuantRS2 framework
Documentation

QuantRS2-Tytan

Crates.io Documentation License

QuantRS2-Tytan is a comprehensive, high-performance quantum annealing library for the QuantRS2 framework. Inspired by the Python Tytan library, it provides powerful tools for formulating and solving quantum optimization problems with state-of-the-art performance.

Version 0.1.0-beta.2

This release features refined integration with SciRS2 v0.1.0-beta.3:

  • High-performance sparse matrix operations via SciRS2
  • Parallel optimization using scirs2_core::parallel_ops
  • SIMD-accelerated energy calculations
  • Memory-efficient large problem handling

Key Features

Core Capabilities

  • Symbolic Problem Construction: Define optimization problems using intuitive symbolic expressions
  • Higher-Order Binary Optimization (HOBO): Support for problems beyond quadratic (3rd order and higher)
  • Advanced Samplers:
    • Simulated Annealing (SA) with SIMD optimization
    • Genetic Algorithm (GA) with adaptive operators
    • GPU-accelerated samplers (Armin, MIKAS)
    • Parallel Tempering with adaptive scheduling
    • Machine Learning guided sampling
    • D-Wave quantum hardware integration
  • Auto Result Processing: Intelligent conversion of solutions to multi-dimensional arrays

Performance Features

  • GPU Acceleration: Up to 50x speedup for large problems
  • SIMD Optimizations: 2-5x faster energy calculations
  • Sparse Matrix Support: 80-97% memory reduction
  • Problem Decomposition: Handle problems with 10,000+ variables
  • Multi-GPU Support: Scale across multiple GPUs

Advanced Capabilities

  • Constraint Handling: Equality, inequality, and soft constraints
  • Variable Encodings: One-hot, binary, unary, and custom encodings
  • Hybrid Algorithms: Combine quantum and classical approaches
  • Solution Analysis: Clustering, diversity metrics, correlation analysis
  • Visualization Tools: Energy landscapes, convergence plots, solution analysis
  • ML Integration: Neural networks, reinforcement learning, quantum ML

🆕 Cutting-Edge Quantum Computing Features

  • Quantum Neural Networks: Hybrid quantum-classical architectures with advanced training
  • Quantum State Tomography: State reconstruction with shadow tomography and ML methods
  • Quantum Error Correction: Advanced QEC codes with ML-based decoding algorithms
  • Tensor Network Algorithms: MPS, PEPS, MERA algorithms for quantum optimization
  • Advanced Performance Analysis: Real-time monitoring with ML-based predictions

Enterprise Features

  • Cloud Integration: AWS, Azure, and Google Cloud support
  • Benchmarking Framework: Comprehensive performance analysis
  • Problem Templates: Pre-built solutions for finance, logistics, drug discovery
  • Testing Framework: Property-based testing and performance regression
  • Production Ready: Error handling, logging, monitoring

Quick Start

Installation

Add to your Cargo.toml:

[dependencies]
quantrs2-tytan = "0.1.0-beta.3"

# Optional features
# quantrs2-tytan = { version = "0.1.0-beta.3", features = ["gpu", "dwave", "scirs"] }

Basic Example

use quantrs2_tytan::sampler::{SASampler, Sampler};
use ndarray::Array2;
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a QUBO matrix
    let mut qubo = Array2::zeros((3, 3));
    qubo[[0, 0]] = -1.0;
    qubo[[1, 1]] = -1.0;
    qubo[[2, 2]] = -1.0;
    qubo[[0, 1]] = 2.0;
    qubo[[1, 0]] = 2.0;

    // Create variable map
    let mut var_map = HashMap::new();
    var_map.insert("x".to_string(), 0);
    var_map.insert("y".to_string(), 1);
    var_map.insert("z".to_string(), 2);

    // Solve with simulated annealing
    let solver = SASampler::new(None);
    let results = solver.run_qubo(&(qubo, var_map), 100)?;

    // Print best solution
    let best = results.iter().min_by_key(|r| r.energy as i32).unwrap();
    println!("Best energy: {}, solution: {:?}", best.energy, best.solution);

    Ok(())
}

Symbolic Example (requires 'dwave' feature)

#[cfg(feature = "dwave")]
use quantrs2_tytan::{symbols, Compile};
use quantrs2_tytan::sampler::{SASampler, Sampler};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Define symbolic variables
    let x = symbols("x");
    let y = symbols("y");
    let z = symbols("z");

    // Create constraint: exactly one variable should be 1
    let expr = (x + y + z - 1).pow(2);

    // Compile to QUBO
    let (qubo, offset) = Compile::new(&expr).get_qubo()?;

    // Solve
    let solver = SASampler::new(None);
    let results = solver.run_qubo(&qubo, 100)?;

    Ok(())
}

Performance

QuantRS2-Tytan delivers exceptional performance across all problem types:

  • Small problems (< 50 variables): 2-5x faster with SIMD
  • Medium problems (50-500 variables): 10-50x faster with GPU
  • Large problems (> 1000 variables): 40-45x faster with GPU
  • HOBO problems: 50-100x faster with tensor decomposition

See BENCHMARKS.md for detailed performance analysis.

Advanced Examples

🆕 Quantum Neural Networks

use quantrs2_tytan::quantum_neural_networks::{QuantumNeuralNetwork, QNNConfig, create_qnn_for_optimization};

fn qnn_example() -> Result<(), Box<dyn std::error::Error>> {
    // Create QNN for optimization
    let mut qnn = create_qnn_for_optimization(4)?; // 4 qubits
    
    // Train on quantum data
    qnn.train_quantum_model()?;
    
    // Use for quantum-enhanced optimization
    let optimized_params = qnn.optimize_parameters()?;
    
    Ok(())
}

🆕 Tensor Network Sampler

use quantrs2_tytan::tensor_network_sampler::{create_mps_sampler, create_peps_sampler};
use quantrs2_tytan::sampler::Sampler;

fn tensor_network_example() -> Result<(), Box<dyn std::error::Error>> {
    // Create MPS sampler for 1D problems
    let mps_sampler = create_mps_sampler(64); // bond dimension
    
    // Create PEPS sampler for 2D problems
    let peps_sampler = create_peps_sampler(16, (5, 5)); // 5x5 lattice
    
    // Use with existing QUBO/HOBO interface
    let results = mps_sampler.run_qubo(&qubo, 100)?;
    
    Ok(())
}

🆕 Advanced Performance Analysis

use quantrs2_tytan::advanced_performance_analysis::{create_comprehensive_analyzer, AnalysisConfig};

fn performance_analysis_example() -> Result<(), Box<dyn std::error::Error>> {
    // Create performance analyzer
    let mut analyzer = create_comprehensive_analyzer();
    
    // Start analysis
    analyzer.start_analysis()?;
    
    // Run your quantum optimization
    // ... optimization code ...
    
    // Perform comprehensive analysis
    analyzer.perform_comprehensive_analysis()?;
    
    // Get bottleneck recommendations
    for recommendation in &analyzer.analysis_results.optimization_recommendations {
        println!("Optimization: {}", recommendation.title);
        println!("Expected benefit: {:.2}%", recommendation.expected_benefit * 100.0);
    }
    
    Ok(())
}

GPU-Accelerated Solving

#[cfg(feature = "gpu")]
use quantrs2_tytan::sampler::{ArminSampler, Sampler};

fn gpu_example() -> Result<(), Box<dyn std::error::Error>> {
    // Check GPU availability
    if !quantrs2_tytan::is_gpu_available() {
        println!("GPU not available, falling back to CPU");
        return Ok(());
    }

    // Use GPU-accelerated sampler for large problems
    let solver = ArminSampler::new(None);
    let results = solver.run_qubo(&large_qubo, 1000)?;
    
    Ok(())
}

Parallel Tempering for Complex Problems

use quantrs2_tytan::parallel_tempering::{ParallelTemperingSampler, PTConfig};

fn parallel_tempering_example() -> Result<(), Box<dyn std::error::Error>> {
    let solver = ParallelTemperingSampler::new(PTConfig {
        num_replicas: 20,
        temperature_range: (0.01, 50.0),
        swap_interval: 5,
        num_sweeps: 50000,
    });

    let results = solver.run_qubo(&qubo, 10)?;
    
    Ok(())
}

Problem with Constraints

use quantrs2_tytan::constraints::add_equality_constraint;

fn constrained_problem() -> Result<(), Box<dyn std::error::Error>> {
    let mut qubo = Array2::zeros((5, 5));
    
    // Add objective function terms
    // ...
    
    // Add constraint: x1 + x2 + x3 = 2
    add_equality_constraint(&mut qubo, &[0, 1, 2], 2.0, 10.0);
    
    // Solve
    let solver = SASampler::new(None);
    let results = solver.run_qubo(&(qubo, var_map), 100)?;
    
    Ok(())
}

Available Features

Core Features

  • parallel: Multi-threading support (enabled by default)
  • gpu: GPU-accelerated samplers using OpenCL/CUDA
  • dwave: Symbolic math and D-Wave quantum hardware support

Performance Features

  • scirs: High-performance computing with SciRS2 libraries (leverages scirs2_core::parallel_ops and sparse matrix operations)
  • advanced_optimization: State-of-the-art optimization algorithms
  • gpu_accelerated: Full GPU acceleration pipeline
  • simd: SIMD optimizations for CPU operations

Analysis Features

  • clustering: Solution clustering and pattern analysis
  • plotters: Visualization tools for results and convergence
  • ml: Machine learning integration
  • benchmark: Performance benchmarking tools

Documentation

Integration with QuantRS2 Ecosystem

QuantRS2-Tytan seamlessly integrates with the entire QuantRS2 quantum computing framework:

  • quantrs2-core: Quantum circuit operations and gates
  • quantrs2-sim: State vector and tensor network simulation
  • quantrs2-anneal: Core annealing algorithms
  • quantrs2-device: Hardware backend integration
  • quantrs2-circuit: Circuit optimization and compilation
  • quantrs2-ml: Quantum machine learning algorithms

Building from Source

Standard Build

cargo build --release

With All Features

cargo build --release --all-features

With GPU Support

cargo build --release --features gpu,gpu_accelerated

Building with SymEngine (for symbolic math)

On macOS:

brew install symengine gmp mpfr
export SYMENGINE_DIR=$(brew --prefix symengine)
export GMP_DIR=$(brew --prefix gmp)
export MPFR_DIR=$(brew --prefix mpfr)
export BINDGEN_EXTRA_CLANG_ARGS="-I$(brew --prefix symengine)/include -I$(brew --prefix gmp)/include -I$(brew --prefix mpfr)/include"
cargo build --features dwave

On Linux:

sudo apt-get install libsymengine-dev libgmp-dev libmpfr-dev
cargo build --features dwave

Contributing

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

Development Setup

# Clone the repository
git clone https://github.com/cool-japan/quantrs.git
cd quantrs/tytan

# Run tests
cargo test

# Run benchmarks
cargo bench

# Check code style
cargo fmt -- --check
cargo clippy -- -D warnings

License

This project is licensed under either:

at your option.