Documentation

Research and development documentation for @jim/spandex.

Quick Links by Role

New to rectangle decomposition? Start with RECTANGLE-DECOMPOSITION-PRIMER - explains three strategies for handling overlapping rectangles.

Using the library?

• GETTING-STARTED - Quick tutorial with examples
• PRODUCTION-GUIDE - Algorithm selection and migration
• TROUBLESHOOTING - Common issues and solutions
• BENCHMARKS - Current performance data
• benchmark-statistics - Statistical methodology

Contributing?

• IMPLEMENTATION-LIFECYCLE - Add/archive implementations
• BENCHMARK-FRAMEWORK - Run and understand benchmarks
• TELEMETRY-GUIDE - Production instrumentation

Interested in the research?

• RESEARCH-SUMMARY - Key findings (5 min read)
• theoretical-foundation - Proofs and complexity analysis
• analyses/ - Individual experiment results

Structure

docs/
├── core/                            # Theory + validated findings
├── analyses/                        # Individual experiment results
├── diagrams/                        # Visual explanations (ASCII)
├── active/experiments/              # In-progress work (empty when idle)
│
├── RECTANGLE-DECOMPOSITION-PRIMER.md  # Educational introduction
├── IMPLEMENTATION-LIFECYCLE.md        # Add/archive/restore workflows
├── BENCHMARK-FRAMEWORK.md             # Performance testing guide
└── TELEMETRY-GUIDE.md                 # Production instrumentation

archive/docs/experiments/            # Rejected experiments (preserved)

Core Research

Executive summary: RESEARCH-SUMMARY provides overview of all findings (5 min read)

Theory: theoretical-foundation contains mathematical proofs and complexity analysis

Key Experiments

Each analysis document includes hypothesis, methodology, data, and conclusions:

• morton-vs-hilbert-analysis - Why Morton curve is 25% faster than Hilbert
• sparse-data-analysis - Why linear scan wins for n<100
• transition-zone-analysis - Crossover thresholds by workload (100 < n < 600)
• r-star-analysis - Split algorithm comparison (R* vs Midpoint vs Quadratic)
• adversarial-patterns - Worst-case fragmentation validation
• benchmark-statistics - Statistical methodology and confidence

Related work: alternatives-analysis (quadtrees, grids, etc.) • related-work (modern techniques)

Failed experiments: See archive/docs/experiments/ for rejected approaches and lessons learned