photonlayer_ruvector/
coherence.rs1use ruvector_coherence::cosine_similarity;
9use ruvector_coherence::spectral::{
10 estimate_fiedler, estimate_largest_eigenvalue, estimate_spectral_gap, CsrMatrixView,
11};
12use serde::{Deserialize, Serialize};
13
14const PROMOTE_SPECTRAL_GAP: f64 = 0.05;
16const PROMOTE_MEAN_SIM: f64 = 0.6;
18
19#[derive(Clone, Debug, Serialize, Deserialize)]
21pub struct FamilyCoherence {
22 pub spectral_gap: f64,
24 pub mean_similarity: f64,
26 pub compactness: f64,
28}
29
30impl FamilyCoherence {
31 pub fn is_promotable(&self) -> bool {
39 if self.mean_similarity < PROMOTE_MEAN_SIM {
40 return false;
41 }
42 let high_sim_clique = self.compactness >= 1.0 && self.mean_similarity >= 0.95;
45 high_sim_clique || self.spectral_gap >= PROMOTE_SPECTRAL_GAP
46 }
47}
48
49const EDGE_THRESHOLD: f64 = 0.3;
51
52pub fn mask_family_coherence(embeddings: &[Vec<f32>]) -> FamilyCoherence {
60 let n = embeddings.len();
61 if n < 2 {
62 return FamilyCoherence {
63 spectral_gap: 0.0,
64 mean_similarity: 0.0,
65 compactness: 0.0,
66 };
67 }
68
69 let total_pairs = n * (n - 1) / 2;
70 let mut edges: Vec<(usize, usize, f64)> = Vec::with_capacity(total_pairs);
71 let mut sim_sum = 0.0_f64;
72 let mut edges_above = 0usize;
73
74 for i in 0..n {
75 for j in (i + 1)..n {
76 let sim = cosine_similarity(&embeddings[i], &embeddings[j]);
77 sim_sum += sim;
78 if sim >= EDGE_THRESHOLD {
79 edges.push((i, j, sim));
80 edges_above += 1;
81 }
82 }
83 }
84
85 let mean_similarity = sim_sum / total_pairs as f64;
86 let compactness = edges_above as f64 / total_pairs as f64;
87
88 let lap = CsrMatrixView::build_laplacian(n, &edges);
90 let (fiedler_raw, _) = estimate_fiedler(&lap, 100, 1e-6);
91 let largest = estimate_largest_eigenvalue(&lap, 100);
92 let spectral_gap = estimate_spectral_gap(fiedler_raw, largest);
93
94 FamilyCoherence {
95 spectral_gap,
96 mean_similarity,
97 compactness,
98 }
99}
100
101#[cfg(test)]
102mod tests {
103 use super::*;
104 use photonlayer_core::prelude::PhaseMask;
105
106 use crate::embedding::mask_embedding;
107
108 fn embeddings_for_seeds(seeds: &[u64]) -> Vec<Vec<f32>> {
109 seeds
110 .iter()
111 .map(|&s| mask_embedding(&PhaseMask::random(16, 16, s)))
112 .collect()
113 }
114
115 #[test]
116 fn single_member_family_returns_zero() {
117 let embs = embeddings_for_seeds(&[1]);
118 let fc = mask_family_coherence(&embs);
119 assert_eq!(fc.spectral_gap, 0.0);
120 assert_eq!(fc.mean_similarity, 0.0);
121 assert!(!fc.is_promotable());
122 }
123
124 #[test]
125 fn identical_masks_form_coherent_family() {
126 let embs: Vec<Vec<f32>> = (0..4)
128 .map(|_| mask_embedding(&PhaseMask::random(16, 16, 7)))
129 .collect();
130 let fc = mask_family_coherence(&embs);
131 assert!(
132 fc.mean_similarity > 0.99,
133 "mean_sim = {}",
134 fc.mean_similarity
135 );
136 assert!(
138 (fc.compactness - 1.0).abs() < 1e-9,
139 "compactness = {}",
140 fc.compactness
141 );
142 assert!(fc.is_promotable(), "fc = {:?}", fc);
144 }
145
146 #[test]
147 fn diverse_masks_have_lower_coherence_than_similar() {
148 let diverse_seeds: Vec<u64> = (0..5).map(|i| i * 1_000_003).collect();
150 let diverse_embs = embeddings_for_seeds(&diverse_seeds);
151 let fc_diverse = mask_family_coherence(&diverse_embs);
152
153 let uniform_embs: Vec<Vec<f32>> = (0..5)
155 .map(|_| mask_embedding(&PhaseMask::random(16, 16, 42)))
156 .collect();
157 let fc_uniform = mask_family_coherence(&uniform_embs);
158
159 assert!(
160 fc_uniform.mean_similarity > fc_diverse.mean_similarity,
161 "uniform={} diverse={}",
162 fc_uniform.mean_similarity,
163 fc_diverse.mean_similarity
164 );
165 }
166
167 #[test]
168 fn promotable_gate_works() {
169 let uniform: Vec<Vec<f32>> = (0..4)
172 .map(|_| mask_embedding(&PhaseMask::random(16, 16, 99)))
173 .collect();
174 let fc_uniform = mask_family_coherence(&uniform);
175 assert!(fc_uniform.is_promotable(), "fc = {:?}", fc_uniform);
176
177 let single = embeddings_for_seeds(&[1]);
179 assert!(!mask_family_coherence(&single).is_promotable());
180
181 let diverse: Vec<Vec<f32>> = (0..5)
183 .map(|i| mask_embedding(&PhaseMask::random(16, 16, i * 999_983 + 1)))
184 .collect();
185 let fc_diverse = mask_family_coherence(&diverse);
186 assert_eq!(
189 fc_diverse.is_promotable(),
190 (fc_diverse.compactness >= 1.0 && fc_diverse.mean_similarity >= 0.95)
191 || (fc_diverse.spectral_gap >= PROMOTE_SPECTRAL_GAP
192 && fc_diverse.mean_similarity >= PROMOTE_MEAN_SIM),
193 "fc = {:?}",
194 fc_diverse
195 );
196 }
197
198 #[test]
199 fn coherence_fields_are_in_range() {
200 let embs = embeddings_for_seeds(&[10, 20, 30, 40]);
201 let fc = mask_family_coherence(&embs);
202 assert!(fc.spectral_gap >= 0.0 && fc.spectral_gap <= 1.0);
203 assert!(fc.mean_similarity >= -1.0 && fc.mean_similarity <= 1.0);
204 assert!(fc.compactness >= 0.0 && fc.compactness <= 1.0);
205 }
206}