Registry backbone: the depth-2 families

diophantine_classifier/data/families/binary-form.yaml

@@ -0,0 +1,22 @@
+# Family: Binary form equation
+# Schema: see data/families/README.md; prose documentation in docs/FAMILIES.md.
+# References are keys into data/references.bib, each with a 'why' annotation.
+slug: binary-form
+name: Binary form equation
+priority: 1
+status: algorithmic
+class: curve
+form: F(x, y) = m, F homogeneous of degree >= 3
+parents:
+- general-curve
+- decomposable-form
+matcher: true
+methods:
+- GL_2(ZZ) reduction (Julia
+- Cremona-Stoll)
+- then Thue/divisor methods
+references:
+- key: CremonaStoll2003
+  why: 'GL_2(ZZ)-reduction theory: the normal form the classifier targets'
+- key: EvertseGyory2015
+  why: finiteness theory for binary form equations via unit equations

diophantine_classifier/data/families/binary-quadratic.yaml

@@ -0,0 +1,27 @@
+# Family: General binary quadratic equation
+# Schema: see data/families/README.md; prose documentation in docs/FAMILIES.md.
+# References are keys into data/references.bib, each with a 'why' annotation.
+slug: binary-quadratic
+name: General binary quadratic equation
+priority: 1
+status: algorithmic
+class: quadratic
+form: a*x^2 + b*x*y + c*y^2 + d*x + e*y + f = 0
+parents:
+- quadric
+matcher: true
+methods:
+- completing the square
+- reduction of binary forms
+- Pell theory
+software:
+  sage: solve_diophantine (sympy)
+  pari: qfbsolve after reduction
+examples:
+- 2*x^2 + 3*x*y - 5*y^2 + x - 7 = 0
+references:
+- key: Matthews2002
+  why: explicit algorithm for the general binary quadratic equation with positive
+    discriminant
+- key: Dickson1920
+  why: history of the classical Lagrange/Gauss theory

diophantine_classifier/data/families/equal-sums-like-powers.yaml

@@ -0,0 +1,21 @@
+# Family: Equal sums of like powers
+# Schema: see data/families/README.md; prose documentation in docs/FAMILIES.md.
+# References are keys into data/references.bib, each with a 'why' annotation.
+slug: equal-sums-like-powers
+name: Equal sums of like powers
+priority: 3
+status: partial
+class: surface
+form: x_1^k + ... + x_s^k = y_1^k + ... + y_t^k
+parents:
+- diagonal-form
+matcher: true
+notes: Euler's conjecture false for k = 4 (Elkies 1988) and k = 5 (Lander-Parkin
+  1966).
+examples:
+- x^4 + y^4 + z^4 = w^4
+references:
+- key: LanderParkin1966
+  why: counterexample to Euler's conjecture for fifth powers
+- key: Elkies1988
+  why: counterexample for fourth powers via elliptic fibrations

diophantine_classifier/data/families/genus-one-curve.yaml

@@ -0,0 +1,24 @@
+# Family: Genus 1 curve (general model)
+# Schema: see data/families/README.md; prose documentation in docs/FAMILIES.md.
+# References are keys into data/references.bib, each with a 'why' annotation.
+slug: genus-one-curve
+name: Genus 1 curve (general model)
+priority: 1
+status: algorithmic
+class: curve
+form: C(x, y) = 0 irreducible of genus 1
+parents:
+- general-curve
+matcher: true
+methods:
+- point search
+- Nagell/Riemann-Roch reduction to Weierstrass
+- descent
+software:
+  magma: EllipticCurve(C, pt)
+  pari: hyperellratpoints (hyperelliptic models)
+references:
+- key: Poonen2002
+  why: survey of point-search and descent strategies on curves
+- key: Nagell1928
+  why: reduction to Weierstrass form once a rational point is found

diophantine_classifier/data/families/quadratic-form-representation.yaml

@@ -0,0 +1,25 @@
+# Family: Representation by a quadratic form (k >= 3)
+# Schema: see data/families/README.md; prose documentation in docs/FAMILIES.md.
+# References are keys into data/references.bib, each with a 'why' annotation.
+slug: quadratic-form-representation
+name: Representation by a quadratic form (k >= 3)
+priority: 1
+status: algorithmic
+class: quadratic
+form: Q(x_1,...,x_k) = n
+parents:
+- quadric
+matcher: true
+methods:
+- spinor genus
+- reduction to isotropy in k+1 variables
+software:
+  sage: QuadraticForm; qfsolve on Q + <-n>
+  pari: qfminim, qfsolve
+references:
+- key: Bhargava2000
+  why: the 15-theorem for universal positive forms
+- key: BhargavaHanke2005
+  why: 'the 290-theorem: representation of all positive integers'
+- key: Cassels1978
+  why: spinor genus theory governing representation in three variables

diophantine_classifier/data/families/quadratic-form-zero.yaml

@@ -0,0 +1,30 @@
+# Family: Isotropy of a quadratic form
+# Schema: see data/families/README.md; prose documentation in docs/FAMILIES.md.
+# References are keys into data/references.bib, each with a 'why' annotation.
+slug: quadratic-form-zero
+name: Isotropy of a quadratic form
+priority: 1
+status: algorithmic
+class: quadratic
+form: Q(x_1,...,x_k) = 0, k >= 3
+parents:
+- quadric
+matcher: true
+methods:
+- Hasse-Minkowski
+- lattice reduction (Simon)
+software:
+  sage: qfsolve(G)
+  pari: qfsolve
+  magma: IsotropicSubspace
+code:
+  sage: |
+    from sage.quadratic_forms.qfsolve import qfsolve
+    qfsolve(matrix(QQ, {gram}))
+examples:
+- x^2 - 3*y^2 + 5*z^2 - 7*w^2 = 0
+references:
+- key: Simon2005
+  why: the minimization+reduction algorithm behind PARI's qfsolve
+- key: Cassels1978
+  why: Hasse-Minkowski theory underlying the local-global test

diophantine_classifier/data/families/superelliptic.yaml

@@ -0,0 +1,21 @@
+# Family: Superelliptic curve
+# Schema: see data/families/README.md; prose documentation in docs/FAMILIES.md.
+# References are keys into data/references.bib, each with a 'why' annotation.
+slug: superelliptic
+name: Superelliptic curve
+priority: 1
+status: effective
+class: curve
+form: y^m = f(x), m >= 2
+parents:
+- general-curve
+matcher: true
+methods:
+- Baker's method via Thue equations over number fields
+examples:
+- y^3 = x^4 + 2
+references:
+- key: Baker1969
+  why: effective bounds for integral points
+- key: Bilu1995
+  why: effective analysis via reduction to unit equations

diophantine_classifier/solvers.py

@@ -772,6 +772,44 @@ def stream():
                        complete=True, stream=stream)
 
 
+def _solve_qf_zero(cls, match, gram=None):
+    r"""
+    Nontrivial zero of a quadratic form, or the local obstruction.
+
+    EXAMPLES::
+
+        sage: from diophantine_classifier import solve
+        sage: S = solve("x^2 + y^2 = 2*z^2")
+        sage: S.solutions[0]
+        (1, 1, -1)
+        sage: solve("x^2 + y^2 = 3*z^2").kind
+        'empty'
+    """
+    if gram is None:
+        gram = sage_eval(str(match.data["gram"]))
+    G = matrix(QQ, gram)
+    try:
+        res = qfsolve(G)
+    except Exception as err:
+        raise SolverUnavailable(f"qfsolve failed: {err}") from None
+    if res in ZZ:
+        place = "the real place" if res == -1 else f"p = {res}"
+        return SolutionSet(_normalized(match), [], "empty",
+                           f"no nontrivial solutions: local obstruction at "
+                           f"{place}", complete=True)
+    vec = [QQ(t) for t in res]
+    den = lcm([t.denominator() for t in vec])
+    ivec = [ZZ(t * den) for t in vec]
+    g = gcd(ivec)
+    ivec = tuple(t // g for t in ivec)
+    if sum(1 for t in ivec if t < 0) > sum(1 for t in ivec if t > 0):
+        ivec = tuple(-t for t in ivec)
+    return SolutionSet(_normalized(match), [ivec], "parametrized",
+                       "one nontrivial solution; all others arise from it by "
+                       "the standard conic/quadric parametrization",
+                       complete=False)
+
+
 def _solve_egyptian(cls, match):
     r"""
     Unit fraction equations ``1/x_1 + ... + 1/x_k = a/n``, concrete case.
@@ -826,6 +864,7 @@ def rec(k_left, target, minimum, acc):
 SOLVERS = {
     "univariate": _solve_univariate,
     "linear": _solve_linear,
+    "quadratic-form-zero": _solve_qf_zero,
     "egyptian-fractions": _solve_egyptian,
 }
 

docs/FAMILIES.md

@@ -58,6 +58,38 @@ PARI: `matsolvemod`; every CAS.
 
 ## 2. Quadratic equations
 
+### `binary-quadratic` — General binary quadratic — P1, algorithmic
+**Form.** ax² + bxy + cy² + dx + ey + f = 0.
+**Status.** Completely algorithmic (Lagrange, Gauss). Behavior governed by
+D = b² − 4ac: D < 0 finite; D = 0 reduces to squares-and-linear; D > 0 nonsquare
+reduces to Pell-like (finitely many families of solutions from fundamental
+automorph); D > 0 square factors.
+**Transformations.** Completing the square: (2ax + by + d)² − D(y + t)² = s form;
+unimodular reduction of the quadratic part.
+**Software.** Sage: `solve_diophantine` (sympy), `BinaryQF`; PARI: `qfbsolve`,
+`qfbred`; Alperin's and Matthews' online solvers; Magma quadratic forms machinery.
+**References.** Gauss, *Disquisitiones*; Lagrange 1768; Matthews,
+"The Diophantine equation ax²+bxy+cy² = N" (J. Théor. Nombres Bordeaux 14, 2002).
+
+### `quadratic-form-zero` — Isotropy of a quadratic form — P1, algorithmic
+**Form.** Q(x₁,…,x_k) = 0, Q a nondegenerate integral quadratic form, k ≥ 3.
+**Status.** Hasse–Minkowski: solvable iff solvable over ℝ and all ℚ_p (finite
+check); k ≥ 5 indefinite always isotropic. Efficient point-finding via
+Simon's algorithm (lattice reduction + minimization).
+**Software.** Sage: `qfsolve(G)`; PARI: `qfsolve`; Magma: `IsotropicSubspace`.
+**References.** Hasse 1923; Cassels, *Rational Quadratic Forms*; Simon,
+"Solving quadratic equations using reduced unimodular quadratic forms" (Math. Comp. 74, 2005).
+
+### `quadratic-form-representation` — Representation by a quadratic form, k ≥ 3 — P1, algorithmic
+**Form.** Q(x₁,…,x_k) = n.
+**Status.** Local-global up to spinor genus (k = 3 subtleties: spinor exceptions;
+k ≥ 4: represented iff locally represented, for n large — effective); celebrated
+uniform results: 15-theorem (Conway–Schneeberger–Bhargava), 290-theorem
+(Bhargava–Hanke). Reduces to `quadratic-form-zero` in k+1 variables via Q(x) − n·t².
+**Software.** Sage: `QuadraticForm`, `qfsolve` on Q ⊥ ⟨−n⟩; PARI: `qfminim`,
+`qfsolve`; Magma: `RepresentationNumber`, ternary form machinery.
+**References.** Cassels; Bhargava 2000; Bhargava–Hanke 2005.
+
 ### `quadric` — General quadratic Diophantine equation — P2, algorithmic
 **Form.** Q(x₁,…,x_k) + L(x₁,…,x_k) + c = 0 (arbitrary quadratic, k ≥ 3).
 **Status.** Decidable in general — the deepest case of the quadratic theory
@@ -86,6 +118,23 @@ Brauer–Manin obstructions; decidability unknown. Research-level exhibits
 
 ## 4. Curves of higher genus and binary forms
 
+### `binary-form` — Binary form equation — P1, algorithmic
+**Form.** F(x, y) = m, F homogeneous of degree d ≥ 3.
+**Status.** Umbrella family; behavior splits on the factorization of F:
+irreducible → `thue`; repeated/linear factors → elementary (`binary-form-reducible`).
+GL₂(ℤ)-reduction (Julia, Cremona–Stoll) brings F to a canonical form — the model
+transformation step for this part of the classifier.
+**References.** Evertse–Győry, *Unit Equations in Diophantine Number Theory*;
+Cremona–Stoll, "On the reduction theory of binary forms" (J. reine angew. Math. 565, 2003).
+
+### `superelliptic` — Superelliptic curves — P1, effective (integral)
+**Form.** yᵐ = f(x), m ≥ 2, deg f ≥ 2 (genus ≥ 1 cases).
+**Status.** Integral points finite and effective (Baker); reduction to Thue
+equations over number fields; rational points as for general curves.
+**Software.** Magma/PARI scripts via Thue reduction; no single intrinsic.
+**References.** Baker 1969; Bilu, "Effective analysis of integral points on
+algebraic curves" (Israel J. Math 90, 1995).
+
 ### `general-curve` — Integral/rational points on a general curve — P1 (as fallback), ineffective
 **Form.** C(x, y) = 0 irreducible, genus g.
 **Status.** g = 0: reducible to conics/parametrization (integral points via
@@ -99,6 +148,16 @@ PARI `hyperellratpoints`, Magma `Chabauty`, `PointSearch`.
 **References.** Siegel 1929; Faltings 1983; Bombieri–Gubler, *Heights in Diophantine
 Geometry*; Stoll, "Rational points on curves" (survey, 2011).
 
+### `genus-one-curve` — Genus 1 curves (non-Weierstrass models) — P1, algorithmic*
+**Form.** C(x, y) = 0 irreducible of genus 1 (any plane model).
+**Status.** With a rational point: birational to an elliptic curve (Nagell/Riemann–Roch
+algorithms) and the Weierstrass machinery applies; without: torsor analysis, descent.
+Finding the initial point is the hard step (the classifier flags exactly this).
+Integral points on the given affine model: finite (Siegel), effective in principle
+(Baker via covers), delicate in practice.
+**Software.** Magma: `EllipticCurve(C, pt)`; Sage: `Jacobian`/genus-one model tools;
+point search: `ratpoints`, PARI `hyperellratpoints` for hyperelliptic models.
+**References.** Nagell 1928; Poonen, "Computing rational points on curves" (2002 survey).
 
 ---
 
@@ -180,6 +239,15 @@ Elkies 1988 — elliptic fibration method; minimal solution Frye);
 local solvability decidable, global behavior varies wildly with (k, s).
 **References.** Davenport–Lewis 1963; Elkies 1988.
 
+### `equal-sums-like-powers` — Equal sums of like powers — P3, partial
+**Form.** x₁^k + ⋯ + x_s^k = y₁^k + ⋯ + y_t^k.
+**Status.** Euler's conjecture (s = 1, t = k−1) false for k = 4 (Elkies) and k = 5
+(Lander–Parkin 1966: 27⁵+84⁵+110⁵+133⁵ = 144⁵); rich computational frontier
+(k = 6 open for s = 1, t < 6? no counterexample known); Prouhet–Tarry–Escott is
+the multi-degree system version.
+**References.** Lander–Parkin 1966; Elkies 1988; Borwein, *Computational Excursions
+in Analysis and Number Theory* (PTE chapters).
+
 
 ---
 

tests/test_classify.py

@@ -13,15 +13,23 @@
     ("3*x + 5*y = 1", "", "linear"),
     ("12*x - 21*y + 30*z = 9", "", "linear"),
     ("x^2 - 5*x + 6 = 0", "", "univariate"),
+    # quadratic, two variables
+    ("2*x^2 + 3*x*y - 5*y^2 + x - 7 = 0", "", "binary-quadratic"),
     # quadratic, more variables
+    ("x^2 - 3*y^2 + 5*z^2 - 7*w^2 = 0", "", "quadratic-form-zero"),
+    ("x^2 + x*y + y^2 + z^2 = 14", "", "quadratic-form-representation"),
     ("x^2 + y^2 - z^2 + 3*x - 7 = 0", "", "quadric"),
     # higher-genus curves and binary forms
+    ("y^3 = x^4 + 2", "", "superelliptic"),
     ("x^3*y + y^3*z + z^3*x = 0", "", "general-curve"),     # Klein quartic
+    ("x^2*y^2 = x^3 + 1", "", "genus-one-curve"),
     # Fermat-type
     ("x^2 + y^4 = z^3", "", "generalized-fermat"),
     ("2*x^3 + 3*y^3 = 5*z^3", "", "generalized-fermat"),
     ("3*x^3 + 4*y^3 + 5*z^3 = 0", "", "generalized-fermat"),  # Selmer
     ("x^p + y^q = z^r", "", "generalized-fermat"),            # Beal
+    # diagonal / surfaces
+    ("x^4 + y^4 + z^4 = w^4", "", "equal-sums-like-powers"),   # Elkies
     # polynomial-exponential
     ("x^3 - 4 = y^n", "", "power-values"),
     # unit fractions