Expand description
Constraint Theory Core - High-Performance Geometric Engine
This crate provides the core mathematical operations for the SuperInstance Constraint Theory system, implementing the Grand Unified Constraint Theory (GUCT).
§Modules
| Module | Description |
|---|---|
manifold | Pythagorean snapping with O(log N) KD-tree lookup |
[hidden_dimensions] | Exact encoding via k = ⌈log₂(1/ε)⌉ formula |
quantizer | Constraint-preserving quantization (TurboQuant, BitNet, PolarQuant) |
holonomy | Consistency verification around cycles |
cache | Thread-safe lattice caching for performance |
kdtree | Spatial indexing for fast nearest neighbor queries |
simd | SIMD-optimized batch processing (AVX2) |
csp | Constraint satisfaction engine (Variable, Constraint, ConstraintProblem) |
ac3 | AC-3 arc consistency algorithm |
backtracking | Backtracking solvers (MRV, LCV, FC, MAC) |
cdcl | Conflict-Driven Clause Learning (1-UIP) |
puzzle | Built-in puzzles (N-Queens, Sudoku 4x4, graph coloring) |
sudoku | 9x9 Sudoku solver with AC-3 + MRV + FC pipeline |
§Core Concepts
§Pythagorean Manifold
The PythagoreanManifold is the primary data structure, representing a discrete
set of exact Pythagorean coordinates on the unit circle. It enables deterministic
projection of continuous vectors to exact rational ratios.
§Hidden Dimensions Formula
The number of hidden dimensions for precision ε:
k = ⌈log₂(1/ε)⌉This formula determines the additional dimensions needed to represent constraints exactly without floating-point errors.
§Quantization Modes
The PythagoreanQuantizer supports multiple quantization modes:
- Ternary (BitNet): {-1, 0, 1} for LLM weights, 16x memory reduction
- Polar (PolarQuant): Exact unit norm preservation for embeddings
- Turbo (TurboQuant): Near-optimal distortion for vector databases
- Hybrid: Auto-select mode based on input characteristics
§Performance
| Operation | Complexity | Notes |
|---|---|---|
| Single snap | O(log N) | KD-tree lookup |
| Batch snap | O(n log N) | SIMD optimized |
| Holonomy check | O(n²) | Spectral method |
| Lattice cache | O(1) | Thread-safe |
§Example
use constraint_theory_core::{PythagoreanManifold, snap};
let manifold = PythagoreanManifold::new(200);
let vec = [0.6f32, 0.8];
let (snapped, noise) = snap(&manifold, vec);
assert!(noise < 0.01);§Hidden Dimensions Example
use constraint_theory_core::hidden_dimensions::{hidden_dim_count, lift_to_hidden};
// Compute hidden dimensions for precision 1e-10
let k = hidden_dim_count(1e-10);
assert_eq!(k, 34);
// Lift a point to higher dimensions
let point = vec![0.6, 0.8];
let lifted = lift_to_hidden(&point, k);
assert_eq!(lifted.len(), 36); // 2 visible + 34 hidden§Quantization Example
use constraint_theory_core::quantizer::{PythagoreanQuantizer, QuantizationMode};
// Create a quantizer for embeddings (unit norm preservation)
let quantizer = PythagoreanQuantizer::for_embeddings();
let vector = vec![0.6, 0.8, 0.0, 0.0];
let result = quantizer.quantize(&vector);
// Verify unit norm is preserved
assert!(result.check_unit_norm(0.1));§SIMD Batch Processing
For high-throughput applications, use SIMD batch processing:
use constraint_theory_core::PythagoreanManifold;
let manifold = PythagoreanManifold::new(200);
let vectors = vec![[0.6, 0.8], [0.8, 0.6], [0.1, 0.99]];
let results = manifold.snap_batch_simd(&vectors);
for (snapped, noise) in results {
println!("Snapped: {:?}, Noise: {}", snapped, noise);
}§Error Handling
For consensus-critical applications, validate inputs before snapping:
use constraint_theory_core::PythagoreanManifold;
let manifold = PythagoreanManifold::new(200);
// Validate input for consensus-critical code
if let Err(reason) = manifold.validate_input([f32::NAN, 0.0]) {
println!("Invalid input: {}", reason);
}§Feature Flags
simd: Enable SIMD optimizations (enabled automatically on supported platforms)
Re-exports§
pub use cache::CachedLattice;pub use cache::LatticeCache;pub use cache::global_cache;pub use cache::clear_global_cache;pub use curvature::ricci_flow_step;pub use curvature::RicciFlow;pub use hidden_dimensions::holographic_accuracy;pub use hidden_dimensions::project_to_visible;pub use hidden_dimensions::HiddenDimensionConfig;pub use holonomy::compute_holonomy;pub use holonomy::verify_holonomy;pub use holonomy::HolonomyChecker;pub use holonomy::HolonomyResult;pub use manifold::snap;pub use manifold::PythagoreanManifold;pub use manifold::PythagoreanTriple;pub use percolation::FastPercolation;pub use percolation::RigidityResult;pub use quantizer::PythagoreanQuantizer;pub use quantizer::QuantizationMode;pub use quantizer::QuantizationResult;pub use quantizer::Rational;pub use tile::ConstraintBlock;pub use tile::Origin;pub use tile::Tile;
Modules§
- ac3
- backtracking
- cache
- Lattice Cache for Pythagorean Coordinates
- cdcl
- cohomology
- Sheaf Cohomology Computation
- csp
- curvature
- Ricci Flow and Curvature Computation
- gauge
- Gauge Connection and Parallel Transport
- hidden_
dimensions - Hidden Dimension Encoding for Exact Constraint Satisfaction
- holonomy
- Holonomy Verification for Constraint Consistency
- kdtree
- KD-tree spatial index for fast constraint state lookup
- manifold
- Pythagorean Manifold - The Rigidity Matroid
- percolation
- Rigidity Percolation using Laman’s Theorem
- puzzle
- quantizer
- Pythagorean Quantizer - Unified Quantization with Constraint Preservation
- simd
- SIMD-optimized operations for constraint theory
- sudoku
- tile
- Core data structures for the Constraint Theory engine
Enums§
- CTErr
- Core error type for constraint theory operations
Constants§
- VERSION
- Version information string
- VERSION_
MAJOR - Crate version as semver components Major version component Major version component
- VERSION_
MINOR - Minor version component Minor version component
- VERSION_
PATCH - Patch version component Patch version component
Functions§
- hidden_
dimensions - Hidden dimensions required for target precision
- max_
angular_ error_ for_ states - Compute maximum angular error for a manifold
Type Aliases§
- CTResult
- Result type for constraint theory operations