Skip to main content

photonlayer_ruvector/
coherence.rs

1//! Mask-family coherence scoring using spectral graph analysis (ADR-260 ยง14).
2//!
3//! A *mask family* is a group of embeddings (one per mask) whose structural
4//! similarity is measured by the spectral gap of the cosine-similarity graph.
5//! Families with a large spectral gap and high mean similarity are considered
6//! stable / coherent and can be promoted to demo mode.
7
8use ruvector_coherence::cosine_similarity;
9use ruvector_coherence::spectral::{
10    estimate_fiedler, estimate_largest_eigenvalue, estimate_spectral_gap, CsrMatrixView,
11};
12use serde::{Deserialize, Serialize};
13
14/// Minimum spectral gap for a family to be considered promotable.
15const PROMOTE_SPECTRAL_GAP: f64 = 0.05;
16/// Minimum mean pairwise similarity for a family to be considered promotable.
17const PROMOTE_MEAN_SIM: f64 = 0.6;
18
19/// Spectral coherence summary for a family of mask embeddings.
20#[derive(Clone, Debug, Serialize, Deserialize)]
21pub struct FamilyCoherence {
22    /// Spectral gap of the cosine-similarity graph (0 = disconnected, 1 = clique).
23    pub spectral_gap: f64,
24    /// Mean pairwise cosine similarity over all pairs in the family.
25    pub mean_similarity: f64,
26    /// Compactness: fraction of edges whose similarity exceeds the threshold.
27    pub compactness: f64,
28}
29
30impl FamilyCoherence {
31    /// Whether this family qualifies for promotion to demo mode.
32    ///
33    /// A family is promotable when:
34    /// - its mean pairwise similarity exceeds [`PROMOTE_MEAN_SIM`], AND
35    /// - either the spectral gap exceeds [`PROMOTE_SPECTRAL_GAP`], OR the
36    ///   family is fully connected (compactness == 1.0 and mean_similarity is
37    ///   near 1.0), which can occur when all masks are numerically identical.
38    pub fn is_promotable(&self) -> bool {
39        if self.mean_similarity < PROMOTE_MEAN_SIM {
40            return false;
41        }
42        // A fully connected, very high similarity family is coherent even when
43        // the spectral solver returns 0 for a near-degenerate Laplacian.
44        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
49/// Edge-inclusion threshold for the similarity graph.
50const EDGE_THRESHOLD: f64 = 0.3;
51
52/// Compute the coherence of a family of mask embeddings.
53///
54/// `embeddings` contains one L2-normalised 32-dim vector per mask.
55///
56/// # Edge cases
57/// - Returns all-zero [`FamilyCoherence`] for families with fewer than 2 members.
58/// - Single-node families have a spectral gap and mean similarity of `0.0`.
59pub 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    // Build Laplacian of the similarity graph and estimate spectral gap.
89    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        // Same seed => identical embeddings => cosine sim = 1.0.
127        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        // Compactness must be 1.0 since all pairs exceed the threshold.
137        assert!(
138            (fc.compactness - 1.0).abs() < 1e-9,
139            "compactness = {}",
140            fc.compactness
141        );
142        // The family is promotable via the high-similarity-clique path.
143        assert!(fc.is_promotable(), "fc = {:?}", fc);
144    }
145
146    #[test]
147    fn diverse_masks_have_lower_coherence_than_similar() {
148        // Very diverse seeds โ€” low similarity.
149        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        // Same mask repeated โ€” high similarity.
154        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        // Identical embeddings: high similarity clique => promotable via
170        // the compactness + high mean_similarity path.
171        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        // A single-member family is not promotable.
178        let single = embeddings_for_seeds(&[1]);
179        assert!(!mask_family_coherence(&single).is_promotable());
180
181        // A very diverse family should not be promotable (low mean_similarity).
182        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        // If it happens to be promotable due to high similarity, that is fine โ€”
187        // we just check the gate logic is consistent with the fields.
188        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}