Your floating-point drift ends here. Snap vectors to exact Pythagorean triples.
📦 pip install constraint-theory | 🌐 Live Demo | 📚 Full Docs
>>>importnumpyasnp>>>v=np.array([3, 4]) /5>>>v[0] **2+v[1] **20.9999999999999999# "Close enough" for science?Your physics simulation gives different results on laptop vs. cluster. Your tests flake. Your Monte Carlo won't reproduce.
>>>fromconstraint_theoryimportPythagoreanManifold>>>manifold=PythagoreanManifold(200)
>>>manifold.snap(0.6, 0.8)
(0.6, 0.8, 0.0) # Exact. 3/5, 4/5. Zero noise.┌─────────────────────────────────────────────────────────────┐
│ │
│ Input: (0.577, 0.816) ← noisy float │
│ ↓ │
│ KD-Tree: O(log n) lookup in Rust │
│ ↓ │
│ Output: (0.6, 0.8) ← exact Pythagorean triple │
│ = (3/5, 4/5) ← stored as exact rationals │
│ │
│ Same result on EVERY machine. Cross-platform guaranteed. │
│ │
└─────────────────────────────────────────────────────────────┘
Prerequisites: Python 3.8+
pip install constraint-theoryTry it now (30 seconds):
pip install constraint-theory
python -c "from constraint_theory import PythagoreanManifold; m = PythagoreanManifold(200); x, y, _ = m.snap(0.577, 0.816); print(f'Exact: ({x}, {y})')"# Output: Exact: (0.6, 0.8)fromconstraint_theoryimportPythagoreanManifold, generate_triples# Create manifold (~1000 exact states)manifold=PythagoreanManifold(density=200)
print(f"Manifold has {manifold.state_count} exact states")
# Output: Manifold has 1013 exact states# Snap to nearest Pythagorean triplex, y, noise=manifold.snap(0.577, 0.816)
print(f"Snapped: ({x:.4f}, {y:.4f}), noise: {noise:.6f}")
# Output: Snapped: (0.6000, 0.8000), noise: 0.0236| Approach | Code | Reproducible | Speed |
|---|---|---|---|
| NumPy (normalize) | 156 chars | Platform-dependent | Fast |
| Constraint Theory | 58 chars | Exact everywhere | ~100ns |
# 156 characters - manual normalizationimportnumpyasnpdefnormalize(v):
mag=np.linalg.norm(v)
returnv/magv=np.array([0.6, 0.8])
normalized=normalize(v) # Still floats, still drifts# 58 characters - exact by constructionfromconstraint_theoryimportPythagoreanManifoldmanifold=PythagoreanManifold(200)
x, y, noise=manifold.snap(0.577, 0.816) # (0.6, 0.8, 0.0236)Works seamlessly with your existing NumPy code. Replace v / np.linalg.norm(v) with exact snapping:
importnumpyasnpfromconstraint_theoryimportPythagoreanManifoldmanifold=PythagoreanManifold(200)
# Your old way: v / np.linalg.norm(v) → floating-point drift# Your new way: manifold.snap(x, y) → exact everywherevector=np.array([0.577, 0.816])
sx, sy, noise=manifold.snap(vector[0], vector[1])
# Batch snap 10,000 vectors (SIMD optimized in Rust)angles=np.random.uniform(0, 2*np.pi, 10000)
vectors=np.column_stack([np.cos(angles), np.sin(angles)])
results=manifold.snap_batch(vectors)
# Convert results to NumPy arrays for analysissnapped=np.array([[sx, sy] forsx, sy, _inresults])
noises=np.array([noisefor_, _, noiseinresults])
print(f"Mean snapping noise: {noises.mean():.6f}")
print(f"Max snapping noise: {noises.max():.6f}")
# Verify exact unit normnorms=np.linalg.norm(snapped, axis=1)
print(f"Max norm deviation from 1.0: {np.max(np.abs(norms-1.0)):.2e}")
# Output: 0.00e+00 (exact!)| Operation | Constraint Theory | scipy.spatial.KDTree | Speedup |
|---|---|---|---|
| Single snap | ~100 ns | ~2 μs | 20x |
| Batch 1,000 | ~74 μs | ~1.5 ms | 20x |
| Batch 10,000 | ~740 μs | ~15 ms | 20x |
| Metric | NumPy Normalize | Constraint Theory |
|---|---|---|
| Precision | Platform-dependent | Exact everywhere |
| Reproducibility | Requires seeding | Deterministic |
| Memory per vector | 16 bytes (2 floats) | 16 bytes (2 floats) |
| Cross-platform | May vary | Identical |
┌─────────────────────────────────┐
│ Do you use NumPy vectors? │
└─────────────┬───────────────────┘
│
┌─────────────▼─────────────┐
│ YES │
└─────────────┬─────────────┘
│
┌───────────────────▼───────────────────┐
│ Need reproducible results across │
│ laptop / server / cluster? │
└─────────────┬─────────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ YES │ │ NO │ │ MAYBE │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌──────────┐
│ ✓ USE │ │ ✗ Maybe │ │ ? Try │
│ THIS! │ │ overkill │ │ demos │
└─────────┘ └──────────┘ └──────────┘
fromconstraint_theoryimportPythagoreanManifoldimportnumpyasnpmanifold=PythagoreanManifold(500)
defaugment_direction(dx, dy):
"""Deterministic data augmentation."""sx, sy, _=manifold.snap(dx, dy)
returnsx, sy# Same augmentation, any machine, any run# Paper reviewers can reproduce your exact training runsmanifold=PythagoreanManifold(150)
defprocess_player_input(vx, vy):
dx, dy, _=manifold.snap(vx, vy)
returndx, dy# All clients see identical physics# No "rubber banding" from FP reconciliationimportnumpyasnpfromconstraint_theoryimportPythagoreanManifoldmanifold=PythagoreanManifold(300)
# Snap 10,000 random directions to exact statesnp.random.seed(42) # Seed for reproducibilityangles=np.random.uniform(0, 2*np.pi, 10000)
directions=np.column_stack([np.cos(angles), np.sin(angles)])
results=manifold.snap_batch(directions)
snapped=np.array([[sx, sy] forsx, sy, _inresults])
# Reproducible on any HPC cluster# Identical results on laptop, server, or cloudCreate a manifold with specified density. Higher density = more exact states = finer resolution.
| Density | Approx States | Resolution |
|---|---|---|
| 50 | ~250 | 0.02 |
| 100 | ~500 | 0.01 |
| 200 | ~1000 | 0.005 |
| 500 | ~2500 | 0.002 |
| 1000 | ~5000 | 0.001 |
| Method | Returns | Description |
|---|---|---|
snap(x, y) | (float, float, float) | Snap single vector, returns (x, y, noise) |
snap_batch(vectors) | List[(float, float, float)] | Batch snap (SIMD optimized) |
state_count | int | Number of valid Pythagorean states |
fromconstraint_theoryimportgenerate_triplestriples=generate_triples(50)
fora, b, cintriples[:5]:
print(f"{a}² + {b}² = {c}²")
# 3² + 4² = 5²# 5² + 12² = 13²# 8² + 15² = 17²| Use Case | Recommended Density | Reasoning |
|---|---|---|
| Game physics | 100-200 | Fast lookups, sufficient precision |
| ML augmentation | 200-500 | Balance precision and speed |
| Scientific computing | 500-1000 | Maximum precision needed |
Exact. The result is always a perfect Pythagorean triple where x² + y² = 1 exactly.
x, y, noise=manifold.snap(0.577, 0.816)
# x, y are EXACT - x² + y² = 1.0 perfectly# noise = distance from input to snapped pointYes! The Rust core uses immutable data structures.
fromconcurrent.futuresimportThreadPoolExecutormanifold=PythagoreanManifold(200)
defsnap_many(vectors):
return [manifold.snap(x, y) forx, yinvectors]
# Safe for parallel usewithThreadPoolExecutor(max_workers=8) asexecutor:
results=list(executor.map(snap_many, chunks))ImportError: cannot import name 'PythagoreanManifold'
The Rust extension wasn't built or loaded correctly.
# Solution 1: Reinstall from PyPI
pip install --upgrade constraint-theory
# Solution 2: Build from source
git clone https://github.com/SuperInstance/constraint-theory-python
cd constraint-theory-python
pip install maturin
maturin develop --releaseTypeError: PythagoreanManifold() takes no keyword arguments
You're using the wrong parameter name.
# WRONG - 'dimensions' doesn't existmanifold=PythagoreanManifold(dimensions=2)
# CORRECT - use 'density' parametermanifold=PythagoreanManifold(density=200)ValueError: density must be positive
Density must be a positive integer.
# WRONGmanifold=PythagoreanManifold(0)
manifold=PythagoreanManifold(-100)
# CORRECTmanifold=PythagoreanManifold(200)snap_batch() returns unexpected results
Ensure your input is the correct shape.
# WRONG - 1D arrayvectors=np.array([0.6, 0.8, 0.707, 0.707])
results=manifold.snap_batch(vectors) # Error!# CORRECT - Nx2 arrayvectors=np.array([[0.6, 0.8], [0.707, 0.707]])
results=manifold.snap_batch(vectors) # Works!Slow performance on first call
The first manifold creation is slower due to KD-tree construction.
# Solution: Create manifold once and reusemanifold=PythagoreanManifold(200) # ~10-50ms# Subsequent calls are fastfor_inrange(100000):
manifold.snap(0.577, 0.816) # ~100ns eachGetting Help
| Repo | What It Does | Key Features |
|---|---|---|
| constraint-theory-core | 🦀 Rust crate | ~100ns snap, SIMD batch, 82 tests |
| constraint-theory-python | 🐍 This repo | NumPy integration, PyTorch compatible |
| constraint-theory-web | 🌐 Interactive demos | 50 visualizations, zero setup |
| constraint-theory-research | 📚 Mathematical foundations | arXiv paper, proofs, open problems |
| constraint-ranch | 🎮 Gamified learning | Puzzle games, agent breeding |
| constraint-flow | 💼 Business automation | Exact financial calculations, workflow orchestration |
| constraint-theory-agent | 🤖 Implementation agent | Code audit, refactoring, expert explanations |
The Python bindings are powered by a Rust core that provides:
- O(log n) KD-tree lookup for nearest-neighbor search
- SIMD optimization for batch processing
- Zero-copy where possible for Python interop
- Thread-safe immutable data structures
See constraint-theory-core for the Rust API.
Explore the manifold interactively at constraint-theory-web.pages.dev:
- Visualize Pythagorean triple distribution on the unit circle
- Interactive snapping demonstrations
- Performance comparisons
- Real-time density adjustment
This library implements the mathematical framework described in:
- "Deterministic Geometric Snapping via Pythagorean Manifolds" — core algorithm
- "Cross-Platform Reproducibility in Scientific Computing" — applications
- See constraint-theory-research for papers
git clone https://github.com/SuperInstance/constraint-theory-python
cd constraint-theory-python
pip install maturin
maturin develop --releaseGood First Issues · CONTRIBUTING.md
MIT — see LICENSE.
Stop debugging floating-point drift. Your competitors already did.