The math behind the magic. Formal foundations for deterministic geometry.

Constraint Theory provides a mathematical framework for deterministic geometry through Pythagorean manifold snapping. Given any 2D unit vector, the system projects it to an exact Pythagorean triple (a/c, b/c) where a² + b² = c² is satisfied by construction — eliminating floating-point drift and enabling cross-platform reproducibility.

Key Results:

• O(log n) nearest-neighbor lookup via KD-tree
• Bounded geodesic noise: d_g(v, σ(v)) < π/(2n)
• Zero hallucination guarantee: all outputs satisfy constraints exactly

Using the library:

let (snapped, noise) = snap(&manifold, [x, y]);
// Works! But why?

Understanding the theory:

The Pythagorean manifold M ⊂ S¹ is a discrete submanifold. The snap operator σ: S¹ → M is a projection that minimizes geodesic distance:

σ(v) = argmin_{p ∈ M} d_g(v, p)

For all p ∈ M, the constraint C(p) = (a² + b² = c²) is satisfied by construction — no validation step needed.

Implementation is code. Research is confidence.

Prerequisites: A PDF reader or Markdown viewer

git clone https://github.com/SuperInstance/constraint-theory-research.git
cd constraint-theory-research

# Read the 45-page deep dive
open MATHEMATICAL_FOUNDATIONS_DEEP_DIVE.md

# Or start intuitive
open GEOMETRIC_INTERPRETATION.md

// Works but unexplained
let manifold = PythagoreanManifold::new(200);
let (snapped, noise) = snap(&manifold, [x, y]);
// Why does this give exact results?
// What are the error bounds?

Theorem (Exact Projection): Let M be the Pythagorean manifold
with density parameter n. For any v ∈ S¹, σ(v) returns:

  σ(v) = argmin_{p ∈ M} d_g(v, p)

Lemma (Bounded Noise): For manifold M with density n,
maximum geodesic distance:

  d_g(v, σ(v)) < π/(2n)

Proof: See MATHEMATICAL_FOUNDATIONS_DEEP_DIVE.md, §4.2

From "it works" to "here's why it works."

                    ┌─────────────────────────────────┐
                    │   Building on Constraint Theory?│
                    └─────────────┬───────────────────┘
                                  │
         ┌────────────────────────┼────────────────────────┐
         │                        │                        │
    ┌────▼────┐              ┌────▼────┐             ┌────▼────┐
    │ PAPER   │              │ PROD    │             │ CURIOUS │
    └────┬────┘              └────┬────┘             └────┬────┘
         │                        │                        │
         ▼                        ▼                        ▼
    ┌─────────┐             ┌──────────┐            ┌──────────┐
    │ ✓ Cite  │             │ ✓ Verify │            │ ✓ Learn  │
    │ this!   │             │ behavior │            │ the math │
    └─────────┘             └──────────┘            └──────────┘

If you're building on Constraint Theory for publications or production, you need formal foundations.

We actively seek collaborators on these challenges:

Definition: Integer solutions to a² + b² + c² = d²
Challenge: Manifold density grows O(d³) vs O(d²) for 2D
Direction: Hierarchical decomposition into coupled 2D manifolds

Challenge: KD-tree parallelization for batch operations
Direction: CUDA/WebGPU implementations
Impact: 100x speedup for real-time applications

Challenge: N-dimensional exact geometry
Direction: Spherical codes and lattice theory
Impact: ML embedding quantization, robotics

See all open problems →

@article{constraint_theory_2025,
  title={Constraint Theory: Deterministic Manifold Snapping
         via Pythagorean Geometry},
  author={SuperInstance},
  journal={arXiv preprint arXiv:2503.15847},
  year={2025},
  url={https://github.com/SuperInstance/constraint-theory-research}
}

SuperInstance. (2025). Constraint Theory: Deterministic Manifold Snapping via Pythagorean Geometry. arXiv preprint arXiv:2503.15847.

SuperInstance. "Constraint Theory: Deterministic Manifold Snapping via Pythagorean Geometry." arXiv preprint arXiv:2503.15847 (2025).

View complete paper index →

Rust (Core Library):

// From constraint-theory-core
use constraint_theory_core::{PythagoreanManifold, snap};

let manifold = PythagoreanManifold::new(200);
let (exact, noise) = snap(&manifold, [0.577, 0.816]);
// exact = [0.6, 0.8], noise = 0.0236

Python:

# From constraint-theory-python
from constraint_theory import PythagoreanManifold

manifold = PythagoreanManifold(200)
x, y, noise = manifold.snap(0.577, 0.816)  # (0.6, 0.8, 0.0236)

Interactive Visualization:

• Pythagorean Snapping Demo
• KD-Tree Visualization
• Rigidity Explorer

Research contributions welcome:

• 📐 Proof improvements — Found an error? Open an issue with [PROOF] prefix
• 🔬 Extensions — Want to extend to new domains? See OPEN_PROBLEMS.md
• 📚 Related work — Submit a PR to add citations
• 💬 Discussions — Join our GitHub Discussions

Good First Issues · CONTRIBUTING.md

@book{doCarmo2016differential,
  title={Differential Geometry of Curves and Surfaces},
  author={do Carmo, Manfredo P.},
  year={2016},
  publisher={Courier Dover Publications}
}

@article{bentley1975multidimensional,
  title={Multidimensional binary search trees used for associative searching},
  author={Bentley, Jon Louis},
  journal={Communications of the ACM},
  volume={18},
  number={9},
  pages={509--517},
  year={1975}
}

@book{hardy2008introduction,
  title={An Introduction to the Theory of Numbers},
  author={Hardy, G. H. and Wright, E. M.},
  year={2008},
  publisher={Oxford University Press}
}

MIT — see LICENSE.