CI validation (temporary) by roed-math · Pull Request #1 · roed-math/DiophantineClassifier

roed-math · 2026-08-08T15:38:15Z

Scratch PR to validate the Sage-container CI workflow before rolling it into the split series. Will be closed.

Packaging and documentation skeleton plus the bibliography layer. - `pyproject.toml`, `Makefile`, `.gitignore`: the project runs under Sage's Python (`make test`, `make doctest`, `make coverage`, `make references`). - `.github/workflows/ci.yml`: those same four checks on every pull request, inside the official `sagemath/sagemath` container (that image has no `make`, so the steps spell the commands out and name the target they mirror). - `README.md`, `CLAUDE.md`, `docs/DESIGN.md`: what the classifier does and how it is put together. They describe the finished system, i.e. the state at the end of this series. - `references.py` and `data/references.bib`: the annotated bibliography and the BibTeX parser/formatter that renders entries for display. Every family in this series cites into that file by key. Reviewing the bibliography: entries are checked mechanically (required fields, DOI/arXiv/URL syntax) by the tool that arrives in `03-registry`; `url` fields point at legally free copies only. What each reference is *for* is recorded per family, in the family's own PR. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

The parser: equation string to `ParsedEquation`. Recognizes the term model the rest of the classifier works with: polynomial terms, `2^n`-style exponential terms and `y^q` power terms, with parameters living in the coefficient ring. Denominators are cleared and the resulting nonvanishing conditions are recorded in `conditions`, so the original problem is never silently replaced by a cleared one. No family data is involved: the parser is exercised entirely by its own doctests (`make doctest`). Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

The family registry: `data/families/<slug>.yaml`, one file per family. - `registry.py` loads the directory, validates it (parents resolve, priorities and statuses come from fixed vocabularies, the DAG is acyclic, every reference key resolves in `references.bib` with a nonempty `why`), and exposes `depth`/`ancestors` — the specificity order used to rank matches. - `tools/check_references.py` plus `references/`: the reference pipeline and its monotone verification ledger. `make references` regenerates `references/REPORT.md`; that generated file is committed by the last PR of the series, when the registry is complete. - `docs/FAMILIES.md`: the prose enumeration. Its section headings are all here; the per-family entries arrive with their families. Three seed families are included so that the layers that follow have something to classify: `general-polynomial` (the root of the DAG), `linear` and `univariate`. Every other family gets its own PR later in the series. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

The shape matchers: `matchers.run(parsed)` returns `Match(slug, data)` records. This is the file where a human eye is most useful on the mathematics: the degree/genus tests, the reductions to standard forms, and the data each match extracts (`D` for Pell, a-invariants for Weierstrass, the regime of a generalized Fermat equation, ...). Matchers never mutate the parsed equation; any normalization is described in `Match.transform`. The recognizers cover 44 families, most of which are not registered yet. That is deliberate and safe: a recognizer whose family has not landed is inert, because the classifier (next PR) ranks matches through the registry and drops slugs it does not know. `tests/test_registry.py` checks the flags of the registered ones; `99-polish` tightens that to *every* emitted slug once the registry is complete. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

The classification pipeline. `classify()` parses, splits reducible equations into components, runs the matchers, and ranks the results by depth in the family DAG, so the most specific family wins. `Classification.explain()` is the human report and `as_dict()` is the JSON contract for the future website backend. `tests/test_classify.py` starts the classification corpus (famous equation to expected family); each family PR adds its own rows. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

The solver layer. `SolutionSet` is the result type: a finite complete list, an empty set with a reason, or an infinite family that streams (`iter(S)`, `S.first(n)`). When no solver is wired up, `SolverUnavailable` carries the registry's software pointers and filled code templates, so an equation page can always offer runnable code. `solve()` dispatches on the primary family and then walks up the lineage. The two seed solvers (linear, univariate) are here; every other solver arrives with its family, which is what makes those PRs independent. The module-level enumeration bounds and the Sage imports are the union used by those solvers. `cli.py` (`dioclassify 'x^2 - 61*y^2 = 1' --solve`) also lands here, since it needs both halves: classification for `--json`, solving for `--solve`. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

The first layer of the family DAG: the root families and their immediate specializations. These are the parents that the individual family PRs hang off, so they land first as a group. Each entry is a YAML file, its `docs/FAMILIES.md` section, its classification-corpus rows and, where standard software is definitive, its solver. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

The second layer of the family DAG. Same shape as the previous PR: parent families only, so that the 38 one-family PRs at the end of the series can be reviewed and merged in any order. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

The last layer of parent families: the deepest interior nodes of the DAG. After this PR every remaining family is a leaf, and each one gets its own PR that touches nothing but its own data, prose, tests and (where applicable) solver. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Apollonian circle packings** (`apollonian`) — P3, partial. - Standard form: `(a+b+c+d)^2 = 2*(a^2+b^2+c^2+d^2), thin-orbit structure` - Parent: `quadratic-form-zero` Contents: the registry entry and its `docs/FAMILIES.md` section. References cited (the claim each one supports): - `Graham2003` — number-theoretic foundations of Apollonian curvature sets - `BourgainKontorovich2014` — positive density of admissible curvatures - `Haag2024` — disproof of the local-global conjecture Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Reducible binary form equation** (`binary-form-reducible`) — P1, solved. - Standard form: `F(x, y) = m, F reducible over QQ` - Parent: `binary-form` - Examples: `x^3 + y^3 = 1729` Contents: the registry entry, its `docs/FAMILIES.md` section and its rows in the classification corpus. References cited (the claim each one supports): - `Cohen2007` — elementary divisor-enumeration methods Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Brocard-Ramanujan equation** (`brocard`) — P3, open. - Standard form: `n! + 1 = m^2` - Parents: — Contents: the registry entry and its `docs/FAMILIES.md` section. References cited (the claim each one supports): - `Overholt1993` — finiteness under the abc conjecture - `BerndtGalway2000` — computational verification Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Figurate = perfect power equations** (`cannonball`) — P3, solved. - Standard form: `e.g. 1^2 + ... + x^2 = y^2` - Parent: `elliptic-weierstrass` Contents: the registry entry and its `docs/FAMILIES.md` section. References cited (the claim each one supports): - `Watson1918` — the complete solution of the square-pyramid problem - `Anglin1990` — a modern elementary proof Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Catalan equation** (`catalan`) — P1, solved. - Standard form: `x^p - y^q = 1, x, y, p, q >= 2` - Parent: `exponential-diophantine` - Examples: `x^p - y^q = 1` Contents: the registry entry, its `docs/FAMILIES.md` section, its rows in the classification corpus, its solver and solver-layer tests. References cited (the claim each one supports): - `Mihailescu2004` — the complete solution of Catalan's conjecture - `Tijdeman1976` — the earlier effective finiteness via Baker's method - `BiluBugeaudMignotte2014` — book exposition of the proof Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Congruent number problem** (`congruent-number`) — P2, partial. - Standard form: `x^2 + y^2 = z^2, x*y = 2*n` - Parents: — Contents: the registry entry and its `docs/FAMILIES.md` section. References cited (the claim each one supports): - `Tunnell1983` — the BSD-conditional criterion deciding congruent numbers - `Koblitz1993` — book-length exposition of the congruent-number/elliptic-curve link Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Genus-one quartic** (`elliptic-quartic`) — P1, algorithmic. - Standard form: `y^2 = q(x), deg q = 4` - Parent: `genus-one-curve` - Examples: `y^2 = x^4 + 3*x + 1` Contents: the registry entry, its `docs/FAMILIES.md` section and its rows in the classification corpus. References cited (the claim each one supports): - `Tzanakis2013` — solving quartic elliptic equations via elliptic logarithms - `CremonaStoll2002` — minimization and reduction of 2-covering quartic models Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Erdos-Straus equation** (`erdos-straus`) — P1, open. - Standard form: `4/n = 1/x + 1/y + 1/z` - Parent: `egyptian-fractions` - Examples: `4/n = 1/x + 1/y + 1/z` Contents: the registry entry, its `docs/FAMILIES.md` section, its rows in the classification corpus, its solver and solver-layer tests. References cited (the claim each one supports): - `ElsholtzTao2013` — counting and average results for 4/n = 1/x + 1/y + 1/z - `Salez2014` — verification up to 10^17 Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Fermat equation** (`fermat`) — P1, solved. - Standard form: `x^n + y^n = z^n, n >= 3` - Parent: `generalized-fermat` - Examples: `x^4 + y^4 = z^4`, `x^n + y^n = z^n` Contents: the registry entry, its `docs/FAMILIES.md` section, its rows in the classification corpus, its solver and solver-layer tests. References cited (the claim each one supports): - `Wiles1995` — the proof of Fermat's Last Theorem (semistable case) - `TaylorWiles1995` — the companion paper completing the proof Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Frobenius / numerical semigroup membership** (`frobenius`) — P2, algorithmic. - Standard form: `a_1*x_1 + ... + a_k*x_k = b, x_i >= 0` - Parent: `linear` Contents: the registry entry and its `docs/FAMILIES.md` section. References cited (the claim each one supports): - `RamirezAlfonsin2005` — the reference monograph on the Frobenius problem - `Kannan1992` — polynomial-time algorithm for the Frobenius number in fixed dimension Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Genus 2 curve** (`genus-two`) — P1, effective. - Standard form: `y^2 = f(x), deg f in {5, 6}` - Parent: `hyperelliptic` - Examples: `y^2 = x^5 - x + 1` Contents: the registry entry, its `docs/FAMILIES.md` section and its rows in the classification corpus. References cited (the claim each one supports): - `Igusa1960` — the invariants identifying a genus-2 curve up to isomorphism (the classifier's genus-2 handle) - `CasselsFlynn1996` — explicit arithmetic of genus-2 Jacobians Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Genus 0 curve** (`genus-zero-curve`) — P1, algorithmic. - Standard form: `C(x, y) = 0 irreducible of genus 0` - Parent: `general-curve` Contents: the registry entry, its `docs/FAMILIES.md` section and its rows in the classification corpus. References cited (the claim each one supports): - `PoulakisVoskos2000` — practical algorithms for genus-zero equations Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Goormaghtigh equation** (`goormaghtigh`) — P3, open. - Standard form: `(x^m - 1)/(x - 1) = (y^n - 1)/(y - 1)` - Parent: `exponential-diophantine` Contents: the registry entry and its `docs/FAMILIES.md` section. References cited (the claim each one supports): - `BalasubramanianShorey1980` — effective finiteness for fixed bases Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Index form equation** (`index-form`) — P3, partial. - Standard form: `I(x_2,...,x_k) = m` - Parent: `decomposable-form` Contents: the registry entry and its `docs/FAMILIES.md` section. References cited (the claim each one supports): - `Gyory1976` — effective finiteness for index form equations - `Gaal2019` — algorithms by degree, with implementations Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Lebesgue-Nagell equation** (`lebesgue-nagell`) — P1, partial. - Standard form: `x^2 + d = y^n` - Parent: `power-values` - Examples: `x^2 + 2 = y^n` Contents: the registry entry, its `docs/FAMILIES.md` section and its rows in the classification corpus. References cited (the claim each one supports): - `Lebesgue1850` — the case d = 1 - `Cohn1993` — resolution for 77 values of d by algebraic methods - `BugeaudMignotteSiksek2006b` — complete resolution for 1 <= d <= 100 (Baker + modular methods) Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **System of linear equations over ZZ** (`linear-system`) — P1, solved. - Standard form: `A*x = b` - Parent: `general-polynomial` Contents: the registry entry and its `docs/FAMILIES.md` section. References cited (the claim each one supports): - `Cohen1993` — Hermite and Smith normal form algorithms used to solve integer linear systems Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Markov / Hurwitz equation** (`markov-hurwitz`) — P2, partial. - Standard form: `x_1^2 + ... + x_k^2 = a * x_1 * ... * x_k` - Parent: `general-polynomial` - Examples: `x^2 + y^2 + z^2 = 3*x*y*z` Contents: the registry entry, its `docs/FAMILIES.md` section, its rows in the classification corpus, its solver and solver-layer tests. References cited (the claim each one supports): - `Markov1879` — the original equation and its role in the theory of binary quadratic forms - `Hurwitz1907` — the general x_1^2 + ... + x_n^2 = a x_1 ... x_n analysis - `Aigner2013` — the uniqueness conjecture and a century of progress - `Zagier1982` — growth of the Markov numbers Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Mordell equation** (`mordell`) — P1, algorithmic. - Standard form: `y^2 = x^3 + k` - Parent: `elliptic-weierstrass` - Examples: `y^2 = x^3 - 2` Contents: the registry entry, its `docs/FAMILIES.md` section, its rows in the classification corpus, its solver and solver-layer tests. References cited (the claim each one supports): - `GebelPethoZimmer1998` — the method, with tables for |k| <= 10^4 - `BennettGhadermarzi2015` — complete tables for |k| <= 10^7 Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Nagell-Ljunggren equation** (`nagell-ljunggren`) — P2, open. - Standard form: `(x^n - 1)/(x - 1) = y^q` - Parent: `exponential-diophantine` Contents: the registry entry and its `docs/FAMILIES.md` section. References cited (the claim each one supports): - `Ljunggren1943` — the classical partial results - `BugeaudMignotte2002` — survey of the state of the art Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Sums of three cubes** (`sum-of-three-cubes`) — P1, open. - Standard form: `x^3 + y^3 + z^3 = n` - Parents: `diagonal-form`, `cubic-surface` - Examples: `x^3 + y^3 + z^3 = 42` Contents: the registry entry, its `docs/FAMILIES.md` section and its rows in the classification corpus. References cited (the claim each one supports): - `HeathBrown1992` — the density conjecture predicting solvability for all n != +-4 mod 9 - `Booker2019` — the solution for n = 33 and the search algorithm behind it - `BookerSutherland2021` — solutions for n = 42 and the third representation of 3 Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Sum of three squares** (`sum-of-three-squares`) — P1, solved. - Standard form: `x^2 + y^2 + z^2 = n` - Parent: `quadratic-form-representation` Contents: the registry entry, its `docs/FAMILIES.md` section, its rows in the classification corpus, its solver and solver-layer tests. References cited (the claim each one supports): - `RabinShallit1986` — randomized polynomial-time three-squares algorithm Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Sum of two squares** (`sum-of-two-squares`) — P1, solved. - Standard form: `x^2 + y^2 = n` - Parent: `binary-qf-representation` - Examples: `x^2 + y^2 = 610` Contents: the registry entry, its `docs/FAMILIES.md` section, its rows in the classification corpus, its solver and solver-layer tests. References cited (the claim each one supports): - `RabinShallit1986` — randomized polynomial-time algorithms for sums of two squares Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Equal sums of two cubes** (`taxicab`) — P3, partial. - Standard form: `x^3 + y^3 = z^3 + w^3` - Parent: `equal-sums-like-powers` Contents: the registry entry and its `docs/FAMILIES.md` section. References cited (the claim each one supports): - `Silverman1993` — the geometry of x^3 + y^3 = k and its rational points Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Thue-Mahler equation** (`thue-mahler`) — P1, algorithmic. - Standard form: `F(x, y) = m * p_1^N_1 * ... * p_s^N_s` - Parent: `thue` - Examples: `x^3 + 2*y^3 = 5^a * 11^b` Contents: the registry entry, its `docs/FAMILIES.md` section and its rows in the classification corpus. References cited (the claim each one supports): - `Mahler1933` — origin of the problem: finiteness with prime-power right-hand sides (p-adic method) - `TzanakisDeWeger1992` — the classical practical algorithm - `GhergaSiksek2022` — the modern efficient implementation (Magma code) Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Hilbert's tenth problem exhibits** (`universal-diophantine`) — P3, undecidable. - Standard form: `universal/undecidable polynomial families` - Parent: `general-polynomial` Contents: the registry entry and its `docs/FAMILIES.md` section. References cited (the claim each one supports): - `Jones1982` — explicit universal equations; unknowns/degree tradeoffs for undecidability - `Sun2021` — current record: 11 unknowns over ZZ suffice for undecidability - `KoymansPagano2024` — resolution of Hilbert's tenth problem over rings of integers of number fields - `Poonen2008` — survey of the decidability landscape, including the open case over QQ Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

One family: **Waring-type diagonal representation** (`waring`) — P2, partial. - Standard form: `x_1^k + ... + x_s^k = n` - Parent: `diagonal-form` - Examples: `x^4 + y^4 + z^4 + w^4 = n` Contents: the registry entry, its `docs/FAMILIES.md` section and its rows in the classification corpus. References cited (the claim each one supports): - `VaughanWooley2002` — survey of g(k) and G(k) - `Vaughan1997` — the circle-method machinery Independent of every other family PR: it needs only the registry backbone it is based on. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

roed-math · 2026-08-08T16:13:55Z

Validated: the Sage-container workflow is green; rolled into the split series.

Packaging and documentation skeleton plus the bibliography layer. - `pyproject.toml`, `Makefile`, `.gitignore`: the project runs under Sage's Python (`make test`, `make doctest`, `make coverage`, `make references`). - `.github/workflows/ci.yml`: those same four checks on every pull request, inside the official `sagemath/sagemath` container (that image has no `make`, so the steps spell the commands out and name the target they mirror). - `CLAUDE.md`, `docs/DESIGN.md`: how the classifier is put together. They describe the finished system, i.e. the state at the end of this series. `README.md` waits for `03-registry`, the PR that brings the files it links to. - `references.py` and `data/references.bib`: the annotated bibliography and the BibTeX parser/formatter that renders entries for display. Every family in this series cites into that file by key. Reviewing the bibliography: entries are checked mechanically (required fields, DOI/arXiv/URL syntax) by the tool that arrives in `03-registry`; `url` fields point at legally free copies only. What each reference is *for* is recorded per family, in the family's own PR. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

The parser: equation string to `ParsedEquation`. Recognizes the term model the rest of the classifier works with: polynomial terms, `2^n`-style exponential terms and `y^q` power terms, with parameters living in the coefficient ring. Denominators are cleared and the resulting nonvanishing conditions are recorded in `conditions`, so the original problem is never silently replaced by a cleared one. No family data is involved: the parser is exercised entirely by its own doctests (`make doctest`). Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants

The family registry: `data/families/<slug>.yaml`, one file per family. - `registry.py` loads the directory, validates it (parents resolve, priorities and statuses come from fixed vocabularies, the DAG is acyclic, every reference key resolves in `references.bib` with a nonempty `why`), and exposes `depth`/`ancestors` — the specificity order used to rank matches. - `tools/check_references.py` plus `references/`: the reference pipeline and its monotone verification ledger. The committed `references/REPORT.md` is the output of `make references` against the registry as it stands here; the closing PR regenerates it once every family has landed (regenerating it in each family PR would collide in every one of them). - `README.md`, which links to the family enumeration, the registry directory and the reference report — all of them present as of this PR. - `docs/FAMILIES.md`: the prose enumeration. Its section headings are all here; the per-family entries arrive with their families. Three seed families are included so that the layers that follow have something to classify: `general-polynomial` (the root of the DAG), `linear` and `univariate`. Every other family gets its own PR later in the series. Part of the series that splits #1 into reviewable pieces: 1. `01-bibliography` — packaging, docs, annotated bibliography 2. `02-parsing` — equation strings to a term model 3. `03-registry` — the YAML family registry (3 seed families) 4. `04-matchers` — shape recognizers 5. `05-classify` — the classification pipeline 6. `06-solvers` — solver framework, two seed solvers, and the CLI 7. `07..09-backbone` — the 23 parent families of the DAG, by depth 8. one PR per remaining family (38 of them, mutually independent) 9. `99-polish` — restore the full doctests and tighten the invariants