Abacus
Abacus counts points on an abelian fourfolda four-dimensional complex torus, C^4 modulo a lattice, that admits a polarization; the four-dimensional analogue of an elliptic curve that is described by its period lattice rather than by equations. For each prime it returns the characteristic polynomial of Frobeniusthe map raising coordinates to the p-th power; its characteristic polynomial determines the number of points over F_p and every extension field as exact integers, the local L-factorthe factor that the prime p contributes to the L-function of the fourfold and the point count, or it stops with a message saying why it could not decide. It is a Python package built on the certified theta functions of Arb and FLINT (F. Johansson; J. Kieffer with N. D. Elkies), with genus-2 period integrals between branch points as in Molin and Neurohr.
What it does
The input is a 4-by-8 period matrix whose entries are certified intervals and an alternating integer form $E$, the polarization. An integer 8-by-8 matrix $\rho$ giving multiplication by $\sqrt{-5}$ is optional. Reduced modulo a prime $p$ of good reduction the fourfold has finitely many points, and that number is fixed by the characteristic polynomial of the Frobenius map:
$$P_p(T) = T^8 + a_1 T^7 + \dots + p^4, \qquad \#A(\mathbb{F}_p) = P_p(1), \qquad |a_k| \le \binom{8}{k}\, p^{k/2}, \quad a_{8-k} = p^{4-k} a_k .$$
Abacus works in three parts:
- Weil box. The Weil bound and the symmetry on the right confine the unknown coefficients to a finite box of integers. Abacus computes an enclosure of each coefficient (an interval guaranteed to contain it) and lists every integer tuple in the box that lies inside the enclosures. Exactly one survivor is the answer, returned as exact integers. No survivor stops the run with
FAIL-WEIL-BOX-EMPTY. Several stop it withUNDECIDED-PRECISIONand an estimate of the decimal digits the input would need. A coefficient is never rounded to the nearest integer. - Theta constants. The period matrix is reduced to a point $\tau$ in the genus-4 Siegel upper half-space (the symmetric complex 4-by-4 matrices with positive-definite imaginary part). The theta constantsvalues at z = 0 of the Riemann theta function with half-integer characteristics, 256 of them in genus 4; together they determine the polarized abelian variety are evaluated there by Arb's
acb_theta, which returns each value with a claimed error radius. Abacus recomputes them as a truncated lattice sum with a tail bound proved in the package manual. The proved bound must dominate the library's radius at the same truncation, and the two enclosures must overlap. Any violation stops the run. - Multiplication by $\sqrt{-5}$. If $\rho$ is supplied, Abacus checks exactly that $\rho^2 = -5$ and that $\rho$ is compatible with the polarization ($\rho^T E \rho = 5E$, $\rho^T E + E\rho = 0$). It then confirms from the periods that $\rho$ acts as the scalar $s\, i\sqrt{5}$ with the sign $s$ the input declares. A wrong sign stops the run with
FAIL-SIGN-PIN.
Abacus has these limits:
- It is not a general-purpose counter. Its command-line drivers run a fixed set of test inputs stored in the package's
SEEDS.jsonfile. A new fourfold means calling the library functions from Python. - For a single curve given by an equation, use PARI's
ellaporhyperellcharpolydirectly. - Replacing $\rho$ by $-\rho$ flips $s$ and every odd L-coefficient $b_P$ while leaving $a_P$ unchanged, so check $s$ before using $b_P$.
The valid test inputs are a product of four elliptic curves, the square of a genus-2 Jacobian, a genus-2 Jacobian with complex multiplication (CM) and two number-field cases. The number-field cases are the fourth power of a CM elliptic curve over $\mathbb{Q}(\sqrt{5})$ and the Weil restriction to $\mathbb{Q}$ of a genus-2 Jacobian over $\mathbb{Q}(\sqrt{-5})$. Five more are deliberately wrong inputs that the checks must reject.
Abacus reaches acb_theta through the Eichler Siegel-space wrapper. It uses PARI/GP only for the cross-checks in its tests and for the periods of the genus-1 test curves.
Examples
Run the self-test suite. With the package set up (see Requirements), run from the root of the BootLoops repository; the package directory is tools/abacus/:
python3 tools/abacus/selftest.py
A pass shows S0-PASS with 7/7 checks, then BATTERY-PASS(11/11, B5 RUNS+PASS) with 22/22 checks in under a minute and about 0.1 GB of memory, and exits 0. A missing dependency gives a message beginning ABACUS-REFUSAL and exit code 1. The repository tree is never modified.
The two theta enclosures from Python. The first calls run_s0.py makes, on the curve 11a1, with tools/abacus/ on sys.path:
from flint import ctx import abcount_s0 as ab ctx.dps = 60 w1, w2, _ = ab.pari_periods((0, -1, 1, -10, -20), 60) # period lattice of 11a1 as balls tau, _ = ab.tau_from_periods(w1, w2) # reduced tau, Im tau > 0 certified t2a, t3a, t4a = ab.theta_nulls_arb(tau) # Arb's theta constants t2d, t3d, t4d, _ = ab.theta_nulls_desk(tau, N=12) # truncated series + proved tail bound ab.balls_overlap(t3a, t3d)
The last line is True: the enclosure built from twelve terms of the $q$-series plus the proved tail bound overlaps Arb's. Abacus demands this overlap before it uses any theta value.
Degree-8 assembly and the Weil box. The integer route of test case B1 in run_s3.py, a product of four elliptic curves at $p = 13$:
from flint import acb import abcount_s0 as ab, abcount_s1 as s1 curves = [(0,-1,1,-10,-20), (1,0,1,4,-6), (1,1,1,-10,-10), (1,-1,1,-1,-14)] # 11a1, 14a1, 15a1, 17a1 p = 13 a = [ab.ap_naive(*c, p)[0] for c in curves] c2 = s1.assemble_lp_deg8(a, p) fe_ok, _ = s1.functional_equation_receipt(c2, p) verdict, tuples, box = s1.weil_box_isolate_deg8([acb(v) for v in c2[1:5]], p) cnt = s1.count_from_charpoly(c2)
The run log in the repository records a = [4, -4, -2, -2], c2 = [1, 4, 40, 92, 638, 1196, 6760, 8788, 28561], fe_ok = True and cnt = 46080. The count is the product $10\cdot18\cdot16\cdot16$ of the four curves' point counts. verdict is "OK", meaning exactly one tuple survived; the driver also requires that tuple to equal c2[1:5], here (4, 40, 92, 638).
Routines
The command-line drivers are in tools/abacus/.
| Command | What it does |
|---|---|
selftest.py | Runs run_s0.py and run_s3.py on a scratch copy; exit 0 only if both pass |
run_s0.py | Genus-1 core checks on one curve at one prime; verdict S0-PASS |
run_s3.py | The full suite: test cases B1 to B5 and B4s, and the must-fail inputs N1 to N5; verdict BATTERY-PASS |
run_s1.py, run_s2.py | Intermediate-stage drivers; by design they stop with an error against the shipped SEEDS.json, and run_s3.py replays their checks |
The library functions are imported with tools/abacus/ on sys.path. The module named at the start of a row holds every function in that row.
| Function | What it returns |
|---|---|
abcount_s0.convert_sign_convention(artifact) | The input in the other sign convention ($\tau \to -\bar\tau$, periods conjugated); the only place a conversion is made |
abcount_s1.julia_theta_all_g4(tau_entries, prec, workdir, tag) | One genus-4 acb_theta call through theta_g4_bridge.jl, exact dyadic values both ways |
abcount_s1.tail_bound_c7(g, N, lam_lb), desk_theta_g4_all(taus, N) | The proved tail bound as a certified upper bound, and truncated sums for all 256 characteristics of a block-diagonal $\tau$ |
abcount_s1.assemble_lp_deg8(a_list, p), functional_equation_receipt(c, p) | The exact degree-8 polynomial, and its symmetry check |
abcount_s1.weil_box_isolate_deg8(coeff_enclosures, p), count_from_charpoly(c) | The Weil box verdict with the surviving tuples, and $P_p(1)$ |
abcount_s2.periods_from_bridge, recover_tau(Pi) | Certified periods of $y^2 = f(x)$, $\deg f = 5$, through period_g2_bridge.jl, and $\tau$ with certified symmetry and positivity |
abcount_s3.ok_action_receipts(rho, E), polarization_type_check(E, declared) | The exact integer checks on $\rho$, the first failure named, and the polarization type from the Smith normal form |
abcount_s3.analytic_rep_receipts(Pi, M), sign_pin_receipt(s, declared_s1) | How $\rho$ acts on the tangent space and its sign $s$; agreement with the declared sign, or FAIL-SIGN-PIN |
The genus-1 and genus-2 routines, the point counters, the PARI cross-checks and the routines of the CM and number-field test cases are defined in abcount_s0.py to abcount_s3.py and hecke_desk.py under build/abcount/.
Requirements
- Runs on: Python 3 with
python-flintandcypari2(both on pip), the PARI/GP binarygponPATH, and ajuliaexecutable onPATH. - Install: the Julia side runs in the Eichler.jl project, included in the repository under
upgrades/Eichler.jl/. First use needsjulia --project=<project> -e 'import Pkg; Pkg.instantiate()'.selftest.pyruns that step itself, and the first run may precompile for a few minutes. - Environment:
ABACUS_EICHLER_PROJECTnames the Eichler.jl project;selftest.pydefaults to the copy in the repository. SetABACUS_JULIAto use a differentjulia.julia_theta_all_g4raises an error when the project is unset or nojuliaresolves. - Self-test:
python3 tools/abacus/selftest.pyends withabacus selftest PASS (S0 7/7 + S3 full battery). - Also used: Lockpick for the $j$-recognition check. The drivers locate it in the repository themselves.
Source and references
The code is tools/abacus/ in the BootLoops repository, released under the MIT license. The canonical body is in build/abcount/, with small forwarding files at the package root and the manual with the proofs at build/abcount/manuals/abcount.md. Do not rename the abcount_* files; the drivers verify checksums of the modules before running.
| Reference | What it supplies |
|---|---|
| J. Kieffer, arXiv:2203.02000; N. D. Elkies and J. Kieffer, arXiv:2505.22382 | acb_theta, the certified theta functions in FLINT |
| F. Johansson, Arb, arXiv:1611.02831; FLINT | The ball arithmetic of the enclosures, through python-flint in Python and Arblib in the Julia bridges |
| Molin and Neurohr, arXiv:1707.07249, doi:10.1090/mcom/3351; code: hcperiods | The published method for the genus-2 period integrals: integration between branch points |
The PARI Group, Univ. Bordeaux, PARI/GP, through cypari2 | ellap, hyperellcharpoly and the periods of the genus-1 test curves |
| Cremona's tables and the LMFDB | The labels of the four elliptic test curves |