GapTheo, a Visual Atlas of the Three-Gap Theorem
Place the first N multiples of an irrational number on a circle and the gaps between neighbours take at most three distinct lengths. GapTheo keeps that sorted finite orbit as the primary live calculation and synchronises it with eleven linked readings of the same object: Farey-cell geometry, continued fractions, return gaps, cyclic words, a lattice schematic, a two-interval exchange lens and a finite 0D Rips topology view. Twelve canonical cases, an exact finite direct oracle, generated certificates, a staged reference pipeline, a complete benchmark, the manuscript source and a deep wiki ship together. Seeded random placement, a farthest-point allocator and a two-frequency extension are explicit contrast regimes, never silently treated as inputs to the classical theorem. No new theorem or formal proof is claimed.
Business Context
GapTheo is a research and teaching instrument. Its value is that a claim about the orbit can be checked on the screen against a certificate rather than trusted from a figure, and that the eleven readings are one object rather than eleven drawings. That makes it usable in a lecture, in a reading group and as a reference implementation for anyone who needs the sorted orbit and its Farey certificate as data. No adoption or external user evidence is claimed; the value axis of the plan is recorded as unvalidated.
Strategic Value
The product is complete as a research application: twelve cases, eleven linked readings, the pipeline, the benchmark, the manuscript and the wiki are implemented and tested, and it makes no claim beyond them. Its most instructive release is v0.03.002, which corrected a visual-ownership failure in v0.03.000: a bespoke teal and green theme, decorative gradients, custom fonts, local copies of the shell and promotional headings had crept into the app, and they were removed so that the shared shell owns the visual layer again; CI now rejects app-owned theme, palette, font and shell-primitive styling. Production QA covers every route and top-level tab in both languages, the five plates in both themes, direct routes and a phone viewport, and verifies literal labels such as the circular gap partition and the Farey and continued-fraction certificate in both languages.
The Challenge
The three-gap theorem is one of the cleanest statements in Diophantine approximation, and one of the hardest to see: the same finite orbit is at once a set of points on a circle, a walk through the Farey tessellation, a truncated continued fraction, a cyclic word over two or three letters, an interval exchange and a lattice. Textbook figures show one of these at a time. A reader who wants to move N or the rotation number and watch every reading change together has no instrument for it, and a research application that tried to offer one would have to keep every view an exact, certified function of the same orbit rather than a decoration.
Our Approach
The sorted finite orbit is the primary live calculation, computed by an exact finite direct oracle, and every other view is derived from it and kept in sync: the circular gap partition, the Farey-cell geometry with its continued-fraction certificate, return gaps, cyclic words, the lattice schematic, the two-interval exchange lens and a finite 0D Rips topology view. Twelve canonical cases cover the rotation numbers a reader would reach for, each with generated certificates and validation scripts, and the staged reference pipeline bakes them for the artifact-backed benchmark. Three contrast regimes are offered on purpose and labelled as such: seeded random placement, a farthest-point allocator and a two-frequency extension, none of which is an input to the classical theorem. The CAOS shell owns palette, typography, themes, cards, buttons, tabs, page structure and callouts; six routes, 35 documentation tabs and five architecture plates render in English and Spanish, in both themes, down to a 390 pixel viewport with no document overflow. The manuscript source and a public deep research review ship in the repository.
Key Performance Indicators
| KPI | Baseline | Result | Impact |
|---|---|---|---|
| One orbit, eleven exact readings | One textbook figure at a time | The sorted finite orbit is the live primary calculation; Farey cells, continued fractions, return gaps, cyclic words, lattice, interval exchange and Rips topology are derived from it and stay in sync as N and the rotation number move | A claim is checked against a certificate, not a picture |
| Contrast regimes kept apart | Experiments that quietly become inputs to the theorem | Seeded random placement, a farthest-point allocator and a two-frequency extension are labelled as contrasts and never fed to the classical statement | The theorem stays the theorem |
| A visual regression, owned and reverted | v0.03.000 shipped a bespoke theme over the shared shell | v0.03.002 removed it; the shell owns the visual layer and CI rejects app-owned theming | The fleet standard is enforced, not assumed |
Architecture
gaptheo pipeline
Technology Stack
Application Screenshots
