Skip to content

Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.

feat: add Poincaré ball geometry module — distance, exp_map, Riemannian SGD

FABIOTESSeb41482af12a
diff --git a/src/lib.rs b/src/lib.rs
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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}");
+}