ruvector_sparse_inference/pi/
mod.rs

1//! π (Pi) Integration Module - Structural Constants for Low-Precision Systems
2//!
3//! π is irrational, non-repeating, and structure-rich. This makes it an ideal
4//! reference signal in systems where precision is constrained.
5//!
6//! # Why π Matters
7//!
8//! In 3/5/7-bit math, you deliberately throw away bits. π lets you check whether
9//! the system is still behaving honestly.
10//!
11//! # Module Components
12//!
13//! - **Calibration**: π-derived constants for normalization and phase encoding
14//! - **Drift Detection**: Quantization honesty signals using π transforms
15//! - **Angular Embeddings**: Hyperspherical embeddings with π phase encoding
16//! - **Chaos Seeding**: Deterministic pseudo-randomness from π digits
17//!
18//! # Key Insight
19//!
20//! π is not about geometry here. It is about injecting infinite structure into
21//! finite machines without breaking determinism.
22//!
23//! This pairs with:
24//! - Min-cut as coherence
25//! - Vectors as motion
26//! - Agents as reflexes
27//! - Precision as policy
28
29pub mod constants;
30pub mod drift;
31pub mod angular;
32pub mod chaos;
33
34pub use constants::{PiCalibration, PI_SCALE_3BIT, PI_SCALE_5BIT, PI_SCALE_7BIT};
35pub use drift::{DriftDetector, DriftReport, QuantizationHonesty};
36pub use angular::{AngularEmbedding, PhaseEncoder, HypersphericalProjection};
37pub use chaos::{PiChaos, DeterministicJitter, PiScheduler};
38
39use crate::precision::PrecisionLane;
40
41/// π-aware quantization context that tracks honesty metrics
42#[derive(Debug, Clone)]
43pub struct PiContext {
44    /// Calibration constants
45    pub calibration: PiCalibration,
46    /// Drift detector for quantization honesty
47    pub drift: DriftDetector,
48    /// Angular embedding projector
49    pub angular: AngularEmbedding,
50    /// Chaos seeder for deterministic jitter
51    pub chaos: PiChaos,
52    /// Current precision lane
53    pub lane: PrecisionLane,
54}
55
56impl PiContext {
57    /// Create a new π context for a precision lane
58    pub fn new(lane: PrecisionLane) -> Self {
59        Self {
60            calibration: PiCalibration::for_lane(lane),
61            drift: DriftDetector::new(lane),
62            angular: AngularEmbedding::new(lane),
63            chaos: PiChaos::new(),
64            lane,
65        }
66    }
67
68    /// Calibrate a value using π-derived constants
69    pub fn calibrate(&self, value: f32) -> f32 {
70        self.calibration.normalize(value)
71    }
72
73    /// Check quantization honesty
74    pub fn check_honesty(&mut self, original: &[f32], quantized: &[f32]) -> QuantizationHonesty {
75        self.drift.check(original, quantized)
76    }
77
78    /// Project to angular space
79    pub fn to_angular(&self, values: &[f32]) -> Vec<f32> {
80        self.angular.project(values)
81    }
82
83    /// Get deterministic jitter for tie-breaking
84    pub fn jitter(&self, index: usize) -> f32 {
85        self.chaos.jitter(index)
86    }
87
88    /// Update drift tracking
89    pub fn update_drift(&mut self, error: f32) {
90        self.drift.update(error);
91    }
92
93    /// Get drift report
94    pub fn drift_report(&self) -> DriftReport {
95        self.drift.report()
96    }
97
98    /// Should escalate precision lane?
99    pub fn should_escalate(&self) -> bool {
100        self.drift.report().should_escalate
101    }
102}
103
104impl Default for PiContext {
105    fn default() -> Self {
106        Self::new(PrecisionLane::Bit5)
107    }
108}
109
110#[cfg(test)]
111mod tests {
112    use super::*;
113
114    #[test]
115    fn test_pi_context_creation() {
116        let ctx = PiContext::new(PrecisionLane::Bit3);
117        assert_eq!(ctx.lane, PrecisionLane::Bit3);
118    }
119
120    #[test]
121    fn test_pi_context_calibration() {
122        let ctx = PiContext::new(PrecisionLane::Bit5);
123        let calibrated = ctx.calibrate(1.0);
124        assert!(calibrated.is_finite());
125    }
126
127    #[test]
128    fn test_pi_context_angular_projection() {
129        let ctx = PiContext::new(PrecisionLane::Bit7);
130        let values = vec![1.0, 2.0, 3.0, 4.0];
131        let angular = ctx.to_angular(&values);
132        assert_eq!(angular.len(), values.len());
133    }
134
135    #[test]
136    fn test_pi_context_jitter() {
137        let ctx = PiContext::new(PrecisionLane::Bit5);
138        let j1 = ctx.jitter(0);
139        let j2 = ctx.jitter(1);
140        // Deterministic: same index = same jitter
141        assert_eq!(ctx.jitter(0), j1);
142        // Different indices = different jitter
143        assert_ne!(j1, j2);
144    }
145}
ruvector_sparse_inference/pi/mod.rs

ruvector_sparse_inference/pi/
mod.rs
