quantrs2_anneal/solution_clustering/
types.rs

1//! Core data structures for solution clustering
2
3use std::collections::HashMap;
4use std::time::{Duration, Instant};
5
6/// Solution representation for clustering
7#[derive(Debug, Clone)]
8pub struct SolutionPoint {
9    /// Solution vector (spin configuration)
10    pub solution: Vec<i8>,
11    /// Energy of the solution
12    pub energy: f64,
13    /// Additional metrics
14    pub metrics: HashMap<String, f64>,
15    /// Solution metadata
16    pub metadata: SolutionMetadata,
17    /// Feature vector for clustering
18    pub features: Option<Vec<f64>>,
19}
20
21/// Solution metadata
22#[derive(Debug, Clone)]
23pub struct SolutionMetadata {
24    /// Solution ID
25    pub id: usize,
26    /// Source algorithm or run
27    pub source: String,
28    /// Timestamp when solution was found
29    pub timestamp: Instant,
30    /// Number of iterations to find this solution
31    pub iterations: usize,
32    /// Quality rank among all solutions
33    pub quality_rank: Option<usize>,
34    /// Feasibility status
35    pub is_feasible: bool,
36}
37
38/// Cluster representation
39#[derive(Debug, Clone)]
40pub struct SolutionCluster {
41    /// Cluster ID
42    pub id: usize,
43    /// Solutions in this cluster
44    pub solutions: Vec<SolutionPoint>,
45    /// Cluster centroid
46    pub centroid: Vec<f64>,
47    /// Representative solution (closest to centroid)
48    pub representative: Option<SolutionPoint>,
49    /// Cluster statistics
50    pub statistics: ClusterStatistics,
51    /// Cluster quality metrics
52    pub quality_metrics: ClusterQualityMetrics,
53}
54
55/// Cluster statistics
56#[derive(Debug, Clone)]
57pub struct ClusterStatistics {
58    /// Number of solutions in cluster
59    pub size: usize,
60    /// Mean energy
61    pub mean_energy: f64,
62    /// Energy standard deviation
63    pub energy_std: f64,
64    /// Minimum energy in cluster
65    pub min_energy: f64,
66    /// Maximum energy in cluster
67    pub max_energy: f64,
68    /// Intra-cluster distance (compactness)
69    pub intra_cluster_distance: f64,
70    /// Cluster diameter (maximum distance between any two points)
71    pub diameter: f64,
72    /// Cluster density
73    pub density: f64,
74}
75
76/// Cluster quality metrics
77#[derive(Debug, Clone)]
78pub struct ClusterQualityMetrics {
79    /// Silhouette coefficient
80    pub silhouette_coefficient: f64,
81    /// Inertia (within-cluster sum of squares)
82    pub inertia: f64,
83    /// Calinski-Harabasz index
84    pub calinski_harabasz_index: f64,
85    /// Davies-Bouldin index
86    pub davies_bouldin_index: f64,
87    /// Cluster stability measure
88    pub stability: f64,
89}
90
91/// Clustering results containing all clusters and analysis
92#[derive(Debug, Clone)]
93pub struct ClusteringResults {
94    /// All clusters found
95    pub clusters: Vec<SolutionCluster>,
96    /// Clustering algorithm used
97    pub algorithm: super::algorithms::ClusteringAlgorithm,
98    /// Distance metric used
99    pub distance_metric: super::algorithms::DistanceMetric,
100    /// Overall clustering quality
101    pub overall_quality: OverallClusteringQuality,
102    /// Landscape analysis
103    pub landscape_analysis: LandscapeAnalysis,
104    /// Statistical summary
105    pub statistical_summary: StatisticalSummary,
106    /// Clustering performance metrics
107    pub performance_metrics: ClusteringPerformanceMetrics,
108    /// Recommendations for optimization
109    pub recommendations: Vec<OptimizationRecommendation>,
110}
111
112/// Overall clustering quality assessment
113#[derive(Debug, Clone)]
114pub struct OverallClusteringQuality {
115    /// Overall silhouette score
116    pub silhouette_score: f64,
117    /// Adjusted Rand Index (if ground truth available)
118    pub adjusted_rand_index: Option<f64>,
119    /// Normalized Mutual Information
120    pub normalized_mutual_information: Option<f64>,
121    /// Inter-cluster separation
122    pub inter_cluster_separation: f64,
123    /// Cluster cohesion
124    pub cluster_cohesion: f64,
125    /// Number of clusters found
126    pub num_clusters: usize,
127    /// Optimal number of clusters estimate
128    pub optimal_num_clusters: usize,
129}
130
131/// Landscape analysis results
132#[derive(Debug, Clone)]
133pub struct LandscapeAnalysis {
134    /// Energy landscape statistics
135    pub energy_statistics: EnergyStatistics,
136    /// Basin detection results
137    pub basins: Vec<EnergyBasin>,
138    /// Connectivity analysis
139    pub connectivity: ConnectivityAnalysis,
140    /// Multi-modality assessment
141    pub multi_modality: MultiModalityAnalysis,
142    /// Ruggedness measures
143    pub ruggedness: RuggednessMetrics,
144    /// Funnel structure analysis
145    pub funnel_analysis: FunnelAnalysis,
146}
147
148/// Energy statistics across the solution set
149#[derive(Debug, Clone)]
150pub struct EnergyStatistics {
151    /// Mean energy
152    pub mean: f64,
153    /// Energy standard deviation
154    pub std_dev: f64,
155    /// Minimum energy found
156    pub min: f64,
157    /// Maximum energy found
158    pub max: f64,
159    /// Energy distribution percentiles
160    pub percentiles: Vec<f64>,
161    /// Skewness of energy distribution
162    pub skewness: f64,
163    /// Kurtosis of energy distribution
164    pub kurtosis: f64,
165    /// Number of distinct energy levels
166    pub num_distinct_energies: usize,
167}
168
169/// Energy basin in the landscape
170#[derive(Debug, Clone)]
171pub struct EnergyBasin {
172    /// Basin ID
173    pub id: usize,
174    /// Solutions in this basin
175    pub solutions: Vec<usize>,
176    /// Basin minimum energy
177    pub min_energy: f64,
178    /// Basin size (number of solutions)
179    pub size: usize,
180    /// Basin depth (relative to global minimum)
181    pub depth: f64,
182    /// Basin width (energy range)
183    pub width: f64,
184    /// Escape barrier height
185    pub escape_barrier: f64,
186}
187
188/// Connectivity analysis of the solution landscape
189#[derive(Debug, Clone)]
190pub struct ConnectivityAnalysis {
191    /// Number of connected components
192    pub num_components: usize,
193    /// Largest connected component size
194    pub largest_component_size: usize,
195    /// Average path length between solutions
196    pub average_path_length: f64,
197    /// Clustering coefficient
198    pub clustering_coefficient: f64,
199    /// Network diameter
200    pub diameter: usize,
201}
202
203/// Multi-modality analysis
204#[derive(Debug, Clone)]
205pub struct MultiModalityAnalysis {
206    /// Number of modes detected
207    pub num_modes: usize,
208    /// Mode locations (energy values)
209    pub mode_energies: Vec<f64>,
210    /// Mode strengths (relative populations)
211    pub mode_strengths: Vec<f64>,
212    /// Inter-mode distances
213    pub inter_mode_distances: Vec<Vec<f64>>,
214    /// Multi-modality index
215    pub multi_modality_index: f64,
216}
217
218/// Ruggedness metrics for the landscape
219#[derive(Debug, Clone)]
220pub struct RuggednessMetrics {
221    /// Autocorrelation function
222    pub autocorrelation: Vec<f64>,
223    /// Ruggedness coefficient
224    pub ruggedness_coefficient: f64,
225    /// Number of local optima
226    pub num_local_optima: usize,
227    /// Epistasis measure
228    pub epistasis: f64,
229    /// Neutrality measure
230    pub neutrality: f64,
231}
232
233/// Funnel structure analysis
234#[derive(Debug, Clone)]
235pub struct FunnelAnalysis {
236    /// Number of funnels detected
237    pub num_funnels: usize,
238    /// Funnel depths
239    pub funnel_depths: Vec<f64>,
240    /// Funnel widths
241    pub funnel_widths: Vec<f64>,
242    /// Global funnel identification
243    pub global_funnel: Option<usize>,
244    /// Funnel competition index
245    pub competition_index: f64,
246}
247
248/// Statistical summary of clustering results
249#[derive(Debug, Clone)]
250pub struct StatisticalSummary {
251    /// Distribution of cluster sizes
252    pub cluster_size_distribution: Vec<usize>,
253    /// Energy distribution analysis
254    pub energy_distribution: DistributionAnalysis,
255    /// Convergence analysis
256    pub convergence_analysis: ConvergenceAnalysis,
257    /// Correlation analysis
258    pub correlation_analysis: CorrelationAnalysis,
259    /// Outlier detection results
260    pub outliers: Vec<OutlierInfo>,
261}
262
263/// Distribution analysis results
264#[derive(Debug, Clone)]
265pub struct DistributionAnalysis {
266    /// Distribution type detected
267    pub distribution_type: DistributionType,
268    /// Distribution parameters
269    pub parameters: HashMap<String, f64>,
270    /// Goodness of fit score
271    pub goodness_of_fit: f64,
272    /// Confidence intervals
273    pub confidence_intervals: Vec<(f64, f64)>,
274}
275
276/// Distribution types
277#[derive(Debug, Clone, PartialEq, Eq)]
278pub enum DistributionType {
279    /// Normal distribution
280    Normal,
281    /// Exponential distribution
282    Exponential,
283    /// Gamma distribution
284    Gamma,
285    /// Beta distribution
286    Beta,
287    /// Weibull distribution
288    Weibull,
289    /// Log-normal distribution
290    LogNormal,
291    /// Uniform distribution
292    Uniform,
293    /// Multimodal distribution
294    Multimodal,
295    /// Unknown/custom distribution
296    Unknown,
297}
298
299/// Convergence analysis results
300#[derive(Debug, Clone)]
301pub struct ConvergenceAnalysis {
302    /// Convergence trajectory clusters
303    pub trajectory_clusters: Vec<TrajectoryCluster>,
304    /// Convergence rates by cluster
305    pub convergence_rates: Vec<f64>,
306    /// Plateau analysis
307    pub plateau_analysis: PlateauAnalysis,
308    /// Premature convergence detection
309    pub premature_convergence: bool,
310    /// Diversity evolution
311    pub diversity_evolution: Vec<f64>,
312}
313
314/// Trajectory cluster for convergence analysis
315#[derive(Debug, Clone)]
316pub struct TrajectoryCluster {
317    /// Cluster ID
318    pub id: usize,
319    /// Trajectory patterns in this cluster
320    pub trajectories: Vec<Vec<f64>>,
321    /// Representative trajectory
322    pub representative_trajectory: Vec<f64>,
323    /// Convergence characteristics
324    pub convergence_characteristics: ConvergenceCharacteristics,
325}
326
327/// Convergence characteristics
328#[derive(Debug, Clone)]
329pub struct ConvergenceCharacteristics {
330    /// Convergence speed
331    pub speed: f64,
332    /// Final convergence quality
333    pub final_quality: f64,
334    /// Stability measure
335    pub stability: f64,
336    /// Exploration vs exploitation balance
337    pub exploration_exploitation_ratio: f64,
338}
339
340/// Plateau analysis in convergence trajectories
341#[derive(Debug, Clone)]
342pub struct PlateauAnalysis {
343    /// Number of plateaus detected
344    pub num_plateaus: usize,
345    /// Plateau durations
346    pub plateau_durations: Vec<usize>,
347    /// Plateau energy levels
348    pub plateau_energies: Vec<f64>,
349    /// Escape probabilities from plateaus
350    pub escape_probabilities: Vec<f64>,
351}
352
353/// Correlation analysis results
354#[derive(Debug, Clone)]
355pub struct CorrelationAnalysis {
356    /// Variable correlation matrix
357    pub variable_correlations: Vec<Vec<f64>>,
358    /// Energy-variable correlations
359    pub energy_correlations: Vec<f64>,
360    /// Significant correlations
361    pub significant_correlations: Vec<(usize, usize, f64)>,
362    /// Correlation patterns
363    pub correlation_patterns: Vec<CorrelationPattern>,
364}
365
366/// Correlation patterns
367#[derive(Debug, Clone)]
368pub struct CorrelationPattern {
369    /// Pattern description
370    pub description: String,
371    /// Variables involved
372    pub variables: Vec<usize>,
373    /// Pattern strength
374    pub strength: f64,
375    /// Pattern type
376    pub pattern_type: PatternType,
377}
378
379/// Types of correlation patterns
380#[derive(Debug, Clone, PartialEq, Eq)]
381pub enum PatternType {
382    /// Positive correlation
383    Positive,
384    /// Negative correlation
385    Negative,
386    /// Non-linear correlation
387    NonLinear,
388    /// Conditional correlation
389    Conditional,
390    /// Cluster-specific correlation
391    ClusterSpecific,
392}
393
394/// Outlier information
395#[derive(Debug, Clone)]
396pub struct OutlierInfo {
397    /// Solution ID
398    pub solution_id: usize,
399    /// Outlier score
400    pub outlier_score: f64,
401    /// Outlier type
402    pub outlier_type: OutlierType,
403    /// Distance to nearest cluster
404    pub distance_to_cluster: f64,
405}
406
407/// Types of outliers
408#[derive(Debug, Clone, PartialEq, Eq)]
409pub enum OutlierType {
410    /// Energy outlier (unusually high/low energy)
411    Energy,
412    /// Structural outlier (unusual solution structure)
413    Structural,
414    /// Performance outlier (unusual algorithm performance)
415    Performance,
416    /// Global outlier (outlier in multiple dimensions)
417    Global,
418}
419
420/// Clustering performance metrics
421#[derive(Debug, Clone)]
422pub struct ClusteringPerformanceMetrics {
423    /// Clustering time
424    pub clustering_time: Duration,
425    /// Analysis time
426    pub analysis_time: Duration,
427    /// Memory usage
428    pub memory_usage: usize,
429    /// Scalability metrics
430    pub scalability_metrics: ScalabilityMetrics,
431    /// Algorithm efficiency
432    pub efficiency_metrics: EfficiencyMetrics,
433}
434
435/// Scalability metrics
436#[derive(Debug, Clone)]
437pub struct ScalabilityMetrics {
438    /// Time complexity estimate
439    pub time_complexity: String,
440    /// Space complexity estimate
441    pub space_complexity: String,
442    /// Performance vs data size relationship
443    pub scaling_factor: f64,
444    /// Parallelization efficiency
445    pub parallelization_efficiency: f64,
446}
447
448/// Algorithm efficiency metrics
449#[derive(Debug, Clone)]
450pub struct EfficiencyMetrics {
451    /// Convergence efficiency
452    pub convergence_efficiency: f64,
453    /// Resource utilization
454    pub resource_utilization: f64,
455    /// Quality vs time trade-off
456    pub quality_time_ratio: f64,
457    /// Robustness measure
458    pub robustness: f64,
459}
460
461/// Optimization recommendations based on clustering analysis
462#[derive(Debug, Clone)]
463pub struct OptimizationRecommendation {
464    /// Recommendation type
465    pub recommendation_type: RecommendationType,
466    /// Recommendation description
467    pub description: String,
468    /// Expected improvement
469    pub expected_improvement: f64,
470    /// Implementation difficulty
471    pub difficulty: DifficultyLevel,
472    /// Priority level
473    pub priority: PriorityLevel,
474    /// Supporting evidence
475    pub evidence: Vec<String>,
476}
477
478/// Types of optimization recommendations
479#[derive(Debug, Clone, PartialEq, Eq)]
480pub enum RecommendationType {
481    /// Parameter tuning recommendation
482    ParameterTuning,
483    /// Algorithm modification
484    AlgorithmModification,
485    /// Problem reformulation
486    ProblemReformulation,
487    /// Initialization strategy
488    InitializationStrategy,
489    /// Termination criteria
490    TerminationCriteria,
491    /// Hybrid approach
492    HybridApproach,
493    /// Multi-start strategy
494    MultiStart,
495    /// Constraint handling
496    ConstraintHandling,
497}
498
499/// Difficulty levels for implementing recommendations
500#[derive(Debug, Clone, PartialEq, Eq)]
501pub enum DifficultyLevel {
502    /// Easy to implement
503    Easy,
504    /// Moderate implementation effort
505    Moderate,
506    /// Difficult implementation
507    Difficult,
508    /// Very difficult, requires significant changes
509    VeryDifficult,
510}
511
512/// Priority levels for recommendations
513#[derive(Debug, Clone, PartialEq, Eq)]
514pub enum PriorityLevel {
515    /// Low priority
516    Low,
517    /// Medium priority
518    Medium,
519    /// High priority
520    High,
521    /// Critical priority
522    Critical,
523}
524
525/// Analysis statistics
526#[derive(Debug, Clone)]
527pub struct AnalysisStatistics {
528    /// Total solutions analyzed
529    pub total_solutions: usize,
530    /// Total analysis time
531    pub total_time: Duration,
532    /// Cache hit rate
533    pub cache_hit_rate: f64,
534    /// Memory usage peak
535    pub peak_memory: usize,
536}
quantrs2_anneal/solution_clustering/types.rs

quantrs2_anneal/solution_clustering/
types.rs
