Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.
Rust ai-nativedescription-logicsformal-verificationinfrastructure-as-codeisabelle-languageknowledge-graphleanlean4mcpmcp-serverontologyowlowl2reasoningrustshaclsparqltheorem-proving
feat: add Poincaré ball geometry module — distance, exp_map, Riemannian SGD
FABIOTESSeb41482af12a
diff --git a/src/lib.rs b/src/lib.rsindex a764bf92..172e56d1 100644--- a/src/lib.rs+++ b/src/lib.rs@@ -17,3 +17,5 @@ pub mod shacl;pub mod state;pub mod schema;pub mod tableaux;+#[cfg(feature = "embeddings")]+pub mod poincare;diff --git a/src/poincare.rs b/src/poincare.rsnew file mode 100644index 00000000..b9713aa7--- /dev/null+++ b/src/poincare.rs@@ -0,0 +1,90 @@+//! Poincaré ball model — distance, exponential map, and Riemannian SGD.+//! Curvature c = 1.0 (unit ball).++const EPS: f32 = 1e-5;++/// Poincaré ball distance: d(u,v) = arcosh(1 + 2||u-v||² / ((1-||u||²)(1-||v||²)))+pub fn poincare_distance(u: &[f32], v: &[f32]) -> f32 {+ let diff_sq: f32 = u.iter().zip(v.iter()).map(|(a, b)| (a - b).powi(2)).sum();+ let norm_u_sq: f32 = u.iter().map(|x| x * x).sum();+ let norm_v_sq: f32 = v.iter().map(|x| x * x).sum();+ let denom = (1.0 - norm_u_sq).max(EPS) * (1.0 - norm_v_sq).max(EPS);+ let x = 1.0 + 2.0 * diff_sq / denom;+ let x = x.max(1.0);+ (x + (x * x - 1.0).max(0.0).sqrt()).ln()+}++/// Cosine similarity between two vectors.+pub fn cosine_similarity(a: &[f32], b: &[f32]) -> f32 {+ let dot: f32 = a.iter().zip(b.iter()).map(|(x, y)| x * y).sum();+ let norm_a: f32 = a.iter().map(|x| x * x).sum::<f32>().sqrt();+ let norm_b: f32 = b.iter().map(|x| x * x).sum::<f32>().sqrt();+ if norm_a < EPS || norm_b < EPS {+ return 0.0;+ }+ dot / (norm_a * norm_b)+}++/// Conformal factor λ_x = 2 / (1 - ||x||²)+fn conformal_factor(x: &[f32]) -> f32 {+ let norm_sq: f32 = x.iter().map(|v| v * v).sum();+ 2.0 / (1.0 - norm_sq).max(EPS)+}++/// Exponential map: maps a tangent vector at x to a point on the Poincaré ball.+pub fn exp_map(x: &[f32], v: &[f32]) -> Vec<f32> {+ let norm_v: f32 = v.iter().map(|a| a * a).sum::<f32>().sqrt();+ if norm_v < EPS {+ return x.to_vec();+ }+ let lambda = conformal_factor(x);+ let t = (lambda * norm_v / 2.0).tanh();+ let direction: Vec<f32> = v.iter().map(|a| t * a / norm_v).collect();+ let result = mobius_add(x, &direction);+ project_to_ball(&result, EPS)+}++/// Möbius addition: x ⊕ y+fn mobius_add(x: &[f32], y: &[f32]) -> Vec<f32> {+ let x_dot_y: f32 = x.iter().zip(y.iter()).map(|(a, b)| a * b).sum();+ let norm_x_sq: f32 = x.iter().map(|a| a * a).sum();+ let norm_y_sq: f32 = y.iter().map(|a| a * a).sum();+ let denom = 1.0 + 2.0 * x_dot_y + norm_x_sq * norm_y_sq;+ let denom = denom.max(EPS);+ let num_x = 1.0 + 2.0 * x_dot_y + norm_y_sq;+ let num_y = 1.0 - norm_x_sq;+ x.iter()+ .zip(y.iter())+ .map(|(xi, yi)| (num_x * xi + num_y * yi) / denom)+ .collect()+}++/// Project point back into the Poincaré ball (clamp norm < 1 - eps).+pub fn project_to_ball(p: &[f32], eps: f32) -> Vec<f32> {+ let norm: f32 = p.iter().map(|x| x * x).sum::<f32>().sqrt();+ let max_norm = 1.0 - eps;+ if norm >= max_norm {+ let scale = max_norm / norm;+ p.iter().map(|x| x * scale).collect()+ } else {+ p.to_vec()+ }+}++/// Riemannian SGD step on the Poincaré ball.+/// Rescales Euclidean gradient by (1 - ||x||²)² / 4, then applies exp_map.+pub fn rsgd_step(point: &[f32], euclidean_grad: &[f32], lr: f32) -> Vec<f32> {+ let norm_sq: f32 = point.iter().map(|x| x * x).sum();+ let scale = ((1.0 - norm_sq).max(EPS)).powi(2) / 4.0;+ let tangent: Vec<f32> = euclidean_grad.iter().map(|g| -lr * scale * g).collect();+ exp_map(point, &tangent)+}++/// L2-normalize a vector (project onto unit sphere for cosine space).+pub fn l2_normalize(v: &[f32]) -> Vec<f32> {+ let norm: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();+ if norm < EPS {+ return v.to_vec();+ }+ v.iter().map(|x| x / norm).collect()+}diff --git a/tests/poincare_test.rs b/tests/poincare_test.rsnew file mode 100644index 00000000..675d8f99--- /dev/null+++ b/tests/poincare_test.rs@@ -0,0 +1,68 @@+use open_ontologies::poincare::*;++#[test]+fn test_poincare_distance_same_point() {+ let p = vec![0.1, 0.2, 0.3];+ let d = poincare_distance(&p, &p);+ assert!(d.abs() < 1e-6, "Distance to self should be ~0, got {d}");+}++#[test]+fn test_poincare_distance_symmetric() {+ let a = vec![0.1, 0.2];+ let b = vec![0.3, 0.4];+ let d1 = poincare_distance(&a, &b);+ let d2 = poincare_distance(&b, &a);+ assert!((d1 - d2).abs() < 1e-6, "Distance should be symmetric");+}++#[test]+fn test_poincare_distance_origin_farther() {+ let origin = vec![0.0, 0.0];+ let near = vec![0.1, 0.0];+ let far = vec![0.9, 0.0];+ let d_near = poincare_distance(&origin, &near);+ let d_far = poincare_distance(&origin, &far);+ assert!(d_far > d_near, "Boundary point should be farther: {d_far} > {d_near}");+}++#[test]+fn test_cosine_similarity_identical() {+ let a = vec![1.0, 2.0, 3.0];+ let s = cosine_similarity(&a, &a);+ assert!((s - 1.0).abs() < 1e-6, "Cosine of identical vectors should be 1.0");+}++#[test]+fn test_cosine_similarity_orthogonal() {+ let a = vec![1.0, 0.0];+ let b = vec![0.0, 1.0];+ let s = cosine_similarity(&a, &b);+ assert!(s.abs() < 1e-6, "Cosine of orthogonal vectors should be 0.0");+}++#[test]+fn test_exp_map_origin() {+ let v = vec![0.1, 0.0];+ let result = exp_map(&[0.0, 0.0], &v);+ assert_eq!(result.len(), 2);+ let norm: f32 = result.iter().map(|x| x * x).sum::<f32>().sqrt();+ assert!(norm < 1.0, "exp_map result should stay inside ball, norm={norm}");+}++#[test]+fn test_project_to_ball() {+ let p = vec![0.99, 0.99];+ let projected = project_to_ball(&p, 1e-5);+ let norm: f32 = projected.iter().map(|x| x * x).sum::<f32>().sqrt();+ assert!(norm < 1.0, "Projected point should be inside ball, norm={norm}");+}++#[test]+fn test_rsgd_step_stays_in_ball() {+ let point = vec![0.5, 0.3];+ let grad = vec![0.1, -0.2];+ let updated = rsgd_step(&point, &grad, 0.01);+ let norm: f32 = updated.iter().map(|x| x * x).sum::<f32>().sqrt();+ assert!(norm < 1.0, "RSGD step should keep point inside ball, norm={norm}");+}