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:

Abacus has these limits:

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/.

CommandWhat it does
selftest.pyRuns run_s0.py and run_s3.py on a scratch copy; exit 0 only if both pass
run_s0.pyGenus-1 core checks on one curve at one prime; verdict S0-PASS
run_s3.pyThe 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.pyIntermediate-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.

FunctionWhat 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

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.

ReferenceWhat it supplies
J. Kieffer, arXiv:2203.02000; N. D. Elkies and J. Kieffer, arXiv:2505.22382acb_theta, the certified theta functions in FLINT
F. Johansson, Arb, arXiv:1611.02831; FLINTThe 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: hcperiodsThe published method for the genus-2 period integrals: integration between branch points
The PARI Group, Univ. Bordeaux, PARI/GP, through cypari2ellap, hyperellcharpoly and the periods of the genus-1 test curves
Cremona's tables and the LMFDBThe labels of the four elliptic test curves

← back to the tools index