quantrs2_tytan/sampler/
mod.rs

1//! Samplers for solving QUBO/HOBO problems.
2//!
3//! This module provides various samplers (solvers) for QUBO and HOBO
4//! problems, including simulated annealing, genetic algorithms, and
5//! specialized hardware samplers.
6
7pub mod errors;
8pub mod genetic_algorithm;
9pub mod gpu;
10pub mod hardware;
11pub mod simulated_annealing;
12
13use scirs2_core::ndarray::Array;
14use std::collections::HashMap;
15
16pub use errors::{SamplerError, SamplerResult};
17
18/// A sample result from a QUBO/HOBO problem
19///
20/// This struct represents a single sample result from a QUBO/HOBO
21/// problem, including the variable assignments, energy, and occurrence count.
22#[derive(Debug, Clone)]
23pub struct SampleResult {
24    /// The variable assignments (name -> value mapping)
25    pub assignments: HashMap<String, bool>,
26    /// The energy (objective function value)
27    pub energy: f64,
28    /// The number of times this solution appeared
29    pub occurrences: usize,
30}
31
32/// Trait for samplers that can solve QUBO/HOBO problems
33pub trait Sampler {
34    /// Run the sampler on a QUBO problem
35    ///
36    /// # Arguments
37    ///
38    /// * `qubo` - The QUBO problem to solve: (matrix, variable mapping)
39    /// * `shots` - The number of samples to take
40    ///
41    /// # Returns
42    ///
43    /// A vector of sample results, sorted by energy (best solutions first)
44    fn run_qubo(
45        &self,
46        qubo: &(
47            Array<f64, scirs2_core::ndarray::Ix2>,
48            HashMap<String, usize>,
49        ),
50        shots: usize,
51    ) -> SamplerResult<Vec<SampleResult>>;
52
53    /// Run the sampler on a HOBO problem
54    ///
55    /// # Arguments
56    ///
57    /// * `hobo` - The HOBO problem to solve: (tensor, variable mapping)
58    /// * `shots` - The number of samples to take
59    ///
60    /// # Returns
61    ///
62    /// A vector of sample results, sorted by energy (best solutions first)
63    fn run_hobo(
64        &self,
65        hobo: &(
66            Array<f64, scirs2_core::ndarray::IxDyn>,
67            HashMap<String, usize>,
68        ),
69        shots: usize,
70    ) -> SamplerResult<Vec<SampleResult>>;
71}
72
73/// Evaluate energy for a QUBO problem given a binary state vector
74///
75/// # Arguments
76///
77/// * `state` - Binary state vector (solution)
78/// * `h_vector` - Linear coefficients (diagonal)
79/// * `j_matrix` - Quadratic coefficients (n_vars x n_vars matrix in flattened form)
80/// * `n_vars` - Number of variables
81///
82/// # Returns
83///
84/// The energy (objective function value) for the given state
85#[allow(dead_code)]
86pub(crate) fn evaluate_qubo_energy(
87    state: &[bool],
88    h_vector: &[f64],
89    j_matrix: &[f64],
90    n_vars: usize,
91) -> f64 {
92    let mut energy = 0.0;
93
94    // Linear terms
95    for i in 0..n_vars {
96        if state[i] {
97            energy += h_vector[i];
98        }
99    }
100
101    // Quadratic terms
102    for i in 0..n_vars {
103        if state[i] {
104            for j in 0..n_vars {
105                if state[j] {
106                    energy += j_matrix[i * n_vars + j];
107                }
108            }
109        }
110    }
111
112    energy
113}
114
115// Re-export main sampler implementations
116pub use genetic_algorithm::GASampler;
117pub use gpu::ArminSampler;
118pub use hardware::{DWaveSampler, MIKASAmpler};
119pub use simulated_annealing::SASampler;
quantrs2_tytan/sampler/mod.rs

quantrs2_tytan/sampler/
mod.rs
