use ruvector_coherence::cosine_similarity;
use ruvector_coherence::spectral::{
estimate_fiedler, estimate_largest_eigenvalue, estimate_spectral_gap, CsrMatrixView,
};
use serde::{Deserialize, Serialize};
const PROMOTE_SPECTRAL_GAP: f64 = 0.05;
const PROMOTE_MEAN_SIM: f64 = 0.6;
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct FamilyCoherence {
pub spectral_gap: f64,
pub mean_similarity: f64,
pub compactness: f64,
}
impl FamilyCoherence {
pub fn is_promotable(&self) -> bool {
if self.mean_similarity < PROMOTE_MEAN_SIM {
return false;
}
let high_sim_clique = self.compactness >= 1.0 && self.mean_similarity >= 0.95;
high_sim_clique || self.spectral_gap >= PROMOTE_SPECTRAL_GAP
}
}
const EDGE_THRESHOLD: f64 = 0.3;
pub fn mask_family_coherence(embeddings: &[Vec<f32>]) -> FamilyCoherence {
let n = embeddings.len();
if n < 2 {
return FamilyCoherence {
spectral_gap: 0.0,
mean_similarity: 0.0,
compactness: 0.0,
};
}
let total_pairs = n * (n - 1) / 2;
let mut edges: Vec<(usize, usize, f64)> = Vec::with_capacity(total_pairs);
let mut sim_sum = 0.0_f64;
let mut edges_above = 0usize;
for i in 0..n {
for j in (i + 1)..n {
let sim = cosine_similarity(&embeddings[i], &embeddings[j]);
sim_sum += sim;
if sim >= EDGE_THRESHOLD {
edges.push((i, j, sim));
edges_above += 1;
}
}
}
let mean_similarity = sim_sum / total_pairs as f64;
let compactness = edges_above as f64 / total_pairs as f64;
let lap = CsrMatrixView::build_laplacian(n, &edges);
let (fiedler_raw, _) = estimate_fiedler(&lap, 100, 1e-6);
let largest = estimate_largest_eigenvalue(&lap, 100);
let spectral_gap = estimate_spectral_gap(fiedler_raw, largest);
FamilyCoherence {
spectral_gap,
mean_similarity,
compactness,
}
}
#[cfg(test)]
mod tests {
use super::*;
use photonlayer_core::prelude::PhaseMask;
use crate::embedding::mask_embedding;
fn embeddings_for_seeds(seeds: &[u64]) -> Vec<Vec<f32>> {
seeds
.iter()
.map(|&s| mask_embedding(&PhaseMask::random(16, 16, s)))
.collect()
}
#[test]
fn single_member_family_returns_zero() {
let embs = embeddings_for_seeds(&[1]);
let fc = mask_family_coherence(&embs);
assert_eq!(fc.spectral_gap, 0.0);
assert_eq!(fc.mean_similarity, 0.0);
assert!(!fc.is_promotable());
}
#[test]
fn identical_masks_form_coherent_family() {
let embs: Vec<Vec<f32>> = (0..4)
.map(|_| mask_embedding(&PhaseMask::random(16, 16, 7)))
.collect();
let fc = mask_family_coherence(&embs);
assert!(
fc.mean_similarity > 0.99,
"mean_sim = {}",
fc.mean_similarity
);
assert!(
(fc.compactness - 1.0).abs() < 1e-9,
"compactness = {}",
fc.compactness
);
assert!(fc.is_promotable(), "fc = {:?}", fc);
}
#[test]
fn diverse_masks_have_lower_coherence_than_similar() {
let diverse_seeds: Vec<u64> = (0..5).map(|i| i * 1_000_003).collect();
let diverse_embs = embeddings_for_seeds(&diverse_seeds);
let fc_diverse = mask_family_coherence(&diverse_embs);
let uniform_embs: Vec<Vec<f32>> = (0..5)
.map(|_| mask_embedding(&PhaseMask::random(16, 16, 42)))
.collect();
let fc_uniform = mask_family_coherence(&uniform_embs);
assert!(
fc_uniform.mean_similarity > fc_diverse.mean_similarity,
"uniform={} diverse={}",
fc_uniform.mean_similarity,
fc_diverse.mean_similarity
);
}
#[test]
fn promotable_gate_works() {
let uniform: Vec<Vec<f32>> = (0..4)
.map(|_| mask_embedding(&PhaseMask::random(16, 16, 99)))
.collect();
let fc_uniform = mask_family_coherence(&uniform);
assert!(fc_uniform.is_promotable(), "fc = {:?}", fc_uniform);
let single = embeddings_for_seeds(&[1]);
assert!(!mask_family_coherence(&single).is_promotable());
let diverse: Vec<Vec<f32>> = (0..5)
.map(|i| mask_embedding(&PhaseMask::random(16, 16, i * 999_983 + 1)))
.collect();
let fc_diverse = mask_family_coherence(&diverse);
assert_eq!(
fc_diverse.is_promotable(),
(fc_diverse.compactness >= 1.0 && fc_diverse.mean_similarity >= 0.95)
|| (fc_diverse.spectral_gap >= PROMOTE_SPECTRAL_GAP
&& fc_diverse.mean_similarity >= PROMOTE_MEAN_SIM),
"fc = {:?}",
fc_diverse
);
}
#[test]
fn coherence_fields_are_in_range() {
let embs = embeddings_for_seeds(&[10, 20, 30, 40]);
let fc = mask_family_coherence(&embs);
assert!(fc.spectral_gap >= 0.0 && fc.spectral_gap <= 1.0);
assert!(fc.mean_similarity >= -1.0 && fc.mean_similarity <= 1.0);
assert!(fc.compactness >= 0.0 && fc.compactness <= 1.0);
}
}