scirs2_optimize/quantum_classical/
mod.rs

1//! Quantum-Classical Hybrid Optimization
2//!
3//! This module provides classical simulation of quantum optimization algorithms:
4//! - QAOA (Quantum Approximate Optimization Algorithm) for combinatorial problems
5//! - VQE (Variational Quantum Eigensolver) for ground-state energy estimation
6//! - Tensor network methods (MPS/DMRG) for quantum many-body systems
7//!
8//! # Overview
9//!
10//! The module implements exact statevector simulation of quantum circuits, enabling
11//! benchmarking of quantum optimization protocols on small problem instances (up to
12//! ~20 qubits on classical hardware).
13//!
14//! # Example: MaxCut with QAOA
15//!
16//! ```rust
17//! use scirs2_optimize::quantum_classical::qaoa::{MaxCutProblem, QaoaConfig, QaoaCircuit};
18//!
19//! // Triangle graph: edges (0,1), (1,2), (0,2)
20//! let problem = MaxCutProblem::new(3, vec![(0, 1, 1.0), (1, 2, 1.0), (0, 2, 1.0)]);
21//! let config = QaoaConfig::default();
22//! let circuit = QaoaCircuit::new(problem, config);
23//! let result = circuit.optimize().expect("QAOA should converge");
24//! println!("Expected cut value: {:.4}", result.optimal_value);
25//! ```
26
27pub mod qaoa;
28pub mod statevector;
29pub mod tensor_network;
30pub mod vqe;
31
32use crate::error::OptimizeError;
33
34/// Result type for quantum-classical optimization operations
35pub type QcResult<T> = Result<T, OptimizeError>;
36
37/// Configuration for quantum-classical optimizers
38#[derive(Debug, Clone)]
39pub struct QcConfig {
40    /// Maximum number of outer optimization iterations
41    pub max_iter: usize,
42    /// Convergence tolerance for parameter updates
43    pub tol: f64,
44    /// Whether to print iteration progress
45    pub verbose: bool,
46}
47
48impl Default for QcConfig {
49    fn default() -> Self {
50        Self {
51            max_iter: 100,
52            tol: 1e-6,
53            verbose: false,
54        }
55    }
56}
57
58/// Result of a quantum-classical optimization run
59#[derive(Debug, Clone)]
60pub struct QcOptResult {
61    /// Optimal circuit parameters found
62    pub optimal_params: Vec<f64>,
63    /// Optimal objective value achieved
64    pub optimal_value: f64,
65    /// Total number of circuit evaluations performed
66    pub n_evaluations: usize,
67    /// Whether the optimizer converged within tolerance
68    pub converged: bool,
69}
70
71/// Trait for quantum-classical hybrid optimizers
72pub trait QuantumClassicalOptimizer {
73    /// Run the optimization and return a result
74    fn optimize(&mut self) -> QcResult<QcOptResult>;
75
76    /// Evaluate the objective at a given parameter vector
77    fn evaluate(&self, params: &[f64]) -> f64;
78
79    /// Return the number of parameters in the circuit
80    fn n_params(&self) -> usize;
81}
82
83// Re-export the most commonly used types
84pub use qaoa::{MaxCutProblem, QaoaCircuit, QaoaConfig, QaoaResult};
85pub use statevector::Statevector;
86pub use tensor_network::{ising_1d_mpo, MPS};
87pub use vqe::{HardwareEfficientAnsatz, PauliHamiltonian, PauliOp, VqeOptimizer, VqeResult};
scirs2_optimize/quantum_classical/mod.rs

scirs2_optimize/quantum_classical/
mod.rs
