optirs_core/quantum_inspired/
mod.rs

1// Quantum-inspired optimization algorithms
2//
3// This module provides optimization algorithms inspired by quantum computing
4// concepts, implemented on classical hardware. These methods leverage ideas
5// from quantum annealing, variational quantum eigensolvers (VQE), and hybrid
6// quantum-classical optimization to explore non-convex loss landscapes more
7// effectively than purely gradient-based methods.
8//
9// # Features
10//
11// - **Quantum Annealing**: Simulated quantum annealing with temperature-driven
12//   exploration and an optional tunneling term that lets the optimizer escape
13//   local minima.
14// - **Variational Quantum Optimizer (VQE)**: A SPSA-based optimizer with a
15//   quantum-inspired ansatz update rule that mimics rotation gate semantics.
16// - **Hybrid Quantum-Classical**: A two-phase optimizer that performs broad
17//   exploration with quantum annealing followed by fine-grained Adam-based
18//   refinement once the search has localised.
19//
20// # Mathematical Background
21//
22// Classical Metropolis acceptance in quantum annealing uses the rule
23//
24// ```text
25//     P(accept) = min(1, exp(-ΔE / (k * T) + Γ * K(δ)))
26// ```
27//
28// where `Γ` is the tunneling strength and `K(δ) = exp(-‖δ‖²)` is a kernel that
29// boosts the acceptance probability of nearby candidate moves to model
30// quantum tunneling on classical hardware.
31//
32// # Examples
33//
34// ```ignore
35// use optirs_core::quantum_inspired::{QuantumAnnealing, QuantumOptimizerConfig};
36// use optirs_core::optimizers::Optimizer;
37// use scirs2_core::ndarray::Array1;
38//
39// let mut optimizer: QuantumAnnealing<f64> = QuantumAnnealing::new(0.05)
40//     .with_temperature_schedule(2.0, 0.01)
41//     .with_tunneling(0.5)
42//     .with_iterations(500)
43//     .with_seed(42);
44//
45// let params = Array1::from_vec(vec![3.0, -2.0, 1.5]);
46// let gradients = params.mapv(|x| 2.0 * x);
47// let next = optimizer.step(&params, &gradients).expect("step failed");
48// assert_eq!(next.len(), params.len());
49// ```
50
51mod annealing;
52mod hybrid;
53mod vqe;
54
55pub use annealing::QuantumAnnealing;
56pub use hybrid::{HybridQuantumClassical, OptimizationPhase};
57pub use vqe::VariationalQuantumOptimizer;
58
59/// Default initial temperature for quantum annealing schedules.
60pub const DEFAULT_INITIAL_TEMP: f64 = 1.0;
61/// Default final temperature for quantum annealing schedules.
62pub const DEFAULT_FINAL_TEMP: f64 = 1.0e-3;
63/// Default number of cooling iterations.
64pub const DEFAULT_NUM_ITERATIONS: usize = 1000;
65/// Default tunneling strength for the quantum-inspired Metropolis kernel.
66pub const DEFAULT_TUNNELING_STRENGTH: f64 = 0.1;
67/// Default RNG seed used when none is supplied.
68pub const DEFAULT_SEED: u64 = 0xC001_5EED_F00D_BABE;
69
70/// Shared configuration for quantum-inspired optimizers.
71///
72/// `QuantumOptimizerConfig` collects the high level knobs that drive every
73/// quantum-inspired optimizer in this module. Sensible defaults are provided
74/// via [`QuantumOptimizerConfig::default`] so users can opt into only the
75/// parameters they care about.
76#[derive(Debug, Clone, Copy, PartialEq)]
77pub struct QuantumOptimizerConfig {
78    /// Initial temperature used at the start of the annealing schedule.
79    pub initial_temperature: f64,
80    /// Final temperature used at the end of the annealing schedule.
81    pub final_temperature: f64,
82    /// Total number of cooling iterations the schedule should span.
83    pub num_iterations: usize,
84    /// Strength of the quantum-inspired tunneling kernel.
85    pub tunneling_strength: f64,
86    /// Seed used to drive the deterministic RNG.
87    pub seed: u64,
88}
89
90impl Default for QuantumOptimizerConfig {
91    fn default() -> Self {
92        Self {
93            initial_temperature: DEFAULT_INITIAL_TEMP,
94            final_temperature: DEFAULT_FINAL_TEMP,
95            num_iterations: DEFAULT_NUM_ITERATIONS,
96            tunneling_strength: DEFAULT_TUNNELING_STRENGTH,
97            seed: DEFAULT_SEED,
98        }
99    }
100}
optirs_core/quantum_inspired/mod.rs

optirs_core/quantum_inspired/
mod.rs
