Lockpick

Lockpick finds integer relations: small whole-number coefficients that express a number known to a hundred or more digits, or a function sampled to that precision at several points, in terms of candidate constants or functions. It returns the relation with its numerical evidence, or a definite "no relation": none below the coefficient bound at the working precision, with the checks passed. The single-number search is PSLQthe Ferguson–Bailey integer-relation algorithm: from real numbers given to high precision it returns small integers combining them to zero, or reports none below a coefficient bound (Ferguson and Bailey), called through the Python library mpmath; the function fit is the lattice method of Barrera, Dersy, Husain, Schwartz and Zhang (arXiv:2507.17815).

What it does

An integer relation among real numbers $v,b_1,\dots,b_n$ is a set of integers $(c_0,\dots,c_n)$, not all zero, with $c_0v+c_1b_1+\dots+c_nb_n=0$. Suppose $v$ is an integral known to 200 digits and the $b_i$ are constants such as $\pi^2$, $\zeta(3)$ or $\log2$. A relation with small coefficients that holds to that precision is then strong evidence for an exact formula for $v$.

The two standard algorithms are PSLQ and lattice reductionLLL (Lenstra–Lenstra–Lovász) and its block version BKZ turn long, nearly parallel integer vectors into short, nearly orthogonal ones; an integer relation appears as the shortest vector of a suitably built lattice. Lockpick runs both under checks that catch the cases in which a search reports "no relation" for the wrong reason.

Lockpick has five parts: the checked PSLQ search pslq_gate, the multi-point lattice fitter mplll, a sample-point selector, the constant library ring15, and the script sets sealrun and bilmine for searches fixed in advance.

One number against a list of constants. pslq_gate takes the target and the named candidates as decimal strings of 200 digits or more, and a coefficient bound $H$ (default $10^6$). It stops with a message in three cases that would otherwise give a silent, false "no relation":

A relation counts only if runs at 120 and at 200 digits give the same vector up to a common factor and sign. Before a "no relation" result is reported, a synthetic target $(3b_1-7b_2)/5$ must be recovered from the same list with the same settings. The command-line program re-verifies every hit at 210 digits.

A function against a basis of functions. In the multi-point version the target $I$ and $K$ basis functions $F_i$ are known numerically at the same $N$ points, and one integer vector must work at all of them:

$$c_0\,I(x_j)-\sum_{i=1}^{K}c_i\,F_i(x_j)=0,\qquad j=1,\dots,N .$$

mplll builds one integer lattice from the whole data matrix and reduces it. The relation then appears as a single short vector, where a least-squares fit gives $K$ real coefficients that each need their own PSLQ.

MethodWhat it does
qrbkz (default)Orthogonalizes the data matrix before BKZ reduction, which removes the ill-conditioning that many sample points cause
rawlllEmbeds the raw data as in arXiv:2507.17815; works with fewer points
rawbkzReduces the same raw lattice with BKZ
gradedTreats a basis graded by transcendental weight one weight at a time; reports the weights at which a relation was found (locked)
cvpRounds a least-squares solution to the nearest lattice point for a given denominator

In the transcendental weight used by graded, $\mathrm{Li}_2$ has weight 2 and $\zeta(3)$ weight 3; the report by weight shows where a fit fails. Batch mode fits many targets against one basis, and a precision sweep finds the fewest digits at which the relation is stable.

Every fit is judged the same way. Some points are withheld, the last two by default.

Choosing sample points. Basis functions are cheap to evaluate and the target usually is not. mplll_points selects, from candidate points and the basis values there, the $n$ points that maximize the determinant of the fit matrix. This is a greedy D-optimal design, which keeps the fit well conditioned. Run it before computing any target values.

The conductor-15 constants. ring15 is a ready-made candidate list. It evaluates, at any mpmath precision, the constants expected when an integral's curve or surface has complex multiplicationan extra arithmetic symmetry of an elliptic curve or K3 surface present only at special parameter values; by the Chowla–Selberg formula its periods are then products of gamma-function values at rational arguments by $\mathbb{Q}(\sqrt{-15})$, as for the K3 surface of the equal-mass three-loop banana. The table holds:

Each module has its own consistency checks, among them ring15_core.disc4_controls() and ring15_hecke.run_validation(). The rebuild command builds the table at 210 and at 120 digits and records their agreement.

Fixed-protocol searches. Once the targets are defined, a protocol frozen in advance replaces exploratory searching. sealrun tests one constant of at least 150 digits (300 is typical) against a frozen list of 24 constants. The list holds powers of $\pi$ and $\log 2$, zeta values, Catalan's constant, Dirichlet $L$-values, and the periods and $L$-values of a weight-3 newform. The answer is either "a relation was found and confirmed" or "no relation with coefficients up to the printed bound".

bilmine applies the same discipline to exact bilinear relations $C^{T}S_{\rm loc}\,C=S$ among numerically known period matrices $C$, with the integer entries of the constant matrices $S_{\rm loc}$ and $S$ unknown.

Lockpick has these limits:

Examples

Run the self-test. With Python and mpmath installed (see Requirements), run from the repository root, where the package directory is tools/lockpick/:

python3 tools/pslq_gate.py --selftest

The PSLQ module writes its own test targets in the AMFlow result-file format, with known answers, and must recover them. Each of the sixteen checks prints one line, and the run ends with a tally. Four of the lines are shown here:

PASS refind planted M0[1111]eps0 = [11,-3,-7,5] over [1,pi^2,zeta3] (gamma normalization exercised across two orders)
PASS capacity() rejects impossible scan (30d leg, height 1e8)
PASS members_audit finds the height-12 MT internal relation (pi^2-12log2^2+12log2log3-6log3^2-12Li2(1/3)-6Li2(1/4)=0)
PASS degenerate basket raises DegeneratePoolError (not silent NULL)
SELFTEST PASS (16/16)

The third line is the dependent-list check at work. The constants $\{\pi^2,\ \log^2 2,\ \log 2\log 3,\ \log^2 3,\ \mathrm{Li}_2(\tfrac13),\ \mathrm{Li}_2(\tfrac14)\}$ satisfy a dilogarithm identity, so a search against that list would return a false null. The fourth line confirms that the search refuses instead. The same run verifies the ring15 source files against their recorded checksums.

Identify one constant. From Python, run inside tools/, with pool a dictionary of decimal strings and target_str the number to identify:

from pslq_gate import two_prec_stable, controls, reverify
pool = {'1': '1.000...', 'pi^2': '9.8696...'}        # >=200-digit strings
vec = two_prec_stable(target_str, ['1','pi^2'], pool, dps_pair=(120,200),
                      maxcoeff=10**6)

vec is the tuple $(c_0,c_1,c_2)$ with $c_0\,\text{target}+c_1+c_2\pi^2=0$, common factor removed and first nonzero entry positive. It is None if no relation below maxcoeff holds at both precisions. Too few digits raises DigitsError, an over-ambitious maxcoeff raises CapacityError, and a dependent pool raises DegeneratePoolError, which has .relation and .members. Call members_audit(pool, names) first and reverify(...) on any hit.

The command-line form reads the target from a file and searches subsets of the pool:

pslq_gate.py --target out.json:'M0[1111]eps0' \
             --pool pool.json --protocol default

The command audits the pool, runs the synthetic control, and tries single constants, pairs and triples of total weight at most --max-weight. It prints one JSON object whose status is HIT (with members, vector and the 210-digit residual), NULL, CONTROLS_FAILED or DEGENERATE_POOL. The exit codes are 0, 1, 2 and 3 in that order.

Fit a sampled function against a basis. The mplll command line, run from the repository root through its flat entry point:

python3 tools/mplll.py --basis B --target T --dps D --height H
  --method {qrbkz|rawlll|rawbkz|graded|cvp} [--backend ...] [--weights FILE.json]
  [--held-out ...] [--fit-points ...] [--dmin-sweep] [--no-controls]

The command prints a JSON record with status, relation, c0 and coeffs (so that $c_0I=\sum_i\texttt{coeffs}[F_i]\,F_i$), heldout_min_d, heldout_per_pt, insample_min_d, two_prec_stable, capacity, span_residual_d and the backend used. It exits 0 on HIT; batch and sweep runs always exit 0. The input files and the options are described under Routines.

Routines

Paths that begin with tools/ are relative to the repository root.

CommandWhat it does
tools/pslq_gate.py --target FILE:key --pool pool.json [--max-weight W]The single-number search of the second example
tools/mplll.py or tools/mplll_cli.pyThe multi-point fitter of the third example
tools/lockpick/mplll_points.py --from-json FILE --n-select N [--dps D] [--out FILE]The point selector
python3 -m lockpick.ring15.ring15, from inside tools/Rebuilds the conductor-15 table
tools/lockpick/sealrun/t6_close.py --target-string-file FILE [--label NAME] [--out DIR]The fixed-protocol search of one constant against the frozen list BASKET_T6.json
tools/lockpick/sealrun/t6_basket.pyRebuilds BASKET_T6.json from reference inputs in the directory named by SEALRUN_R1
tools/lockpick/bilmine/The bilinear-relation search, as a chain of scripts

pslq_gate.py. out.json is an AMFlow result file, whose $\varepsilon$-coefficients are loaded under names M<i>[<propagator indices>]eps<n>, or a flat JSON dictionary of value strings. pool.json is {"members": {name: value_string}, "weights": {name: int}} with the weights optional.

mplll.py. The package module uses relative imports, so run it through one of the two flat files, not by its path inside tools/lockpick/. From inside tools/, python3 -m lockpick.mplll_cli and python -m lockpick.mplll take the same options.

OptionMeaning
--basis BJSON file {"names": [...], "values": {name: [v_1, ..., v_N]}}, with the values at the $N$ sample points as decimal strings
--target TJSON list of the target's $N$ values; complex values written (re+imj) are split and fitted jointly
--dps DThe number of digits the data support (default 100)
--height HThe weight $W$ on the coefficient block of the rawlll lattice; the largest accepted coefficient for graded and batch fits (default $10^8$)
--backendForces one reduction backend: fpylll, fplll-cli, nemo or pure
--held-out, --fit-pointsComma-separated point indices
--weights FILE.jsonEach basis function's integer weight, for graded
--denom D, --ls-coeffs FILE.jsonFor cvp: the denominator and, optionally, the least-squares coefficients
--dmin-sweepRuns the precision sweep
--no-controlsSkips the two control fits

A target file {"targets": {label: [...]}} switches to batch mode.

mplll_points.py. FILE is {"candidates": [x...], "basis_values": {name: [B_i(x_j)...]}}. The command prints the chosen indices and points, $\log_{10}$ of the design determinant, the gain per step and the condition number of the chosen fit matrix.

ring15. The rebuild writes RING15_partial.json after each block and RING15.json at the end, in the directory named by the environment variable RING15_OUT (default: the current directory).

t6_close.py. --target-json FILE:key.path reads the target from a JSON file. The run writes CLOSE_<label>_<stamp>.json under --out (default: the current directory).

Exit codeMeaning
0A relation was found and confirmed
1None up to the printed bound
2The controls failed (no result)
3The list is dependent (a null would be void)
4Input or digit-count error

t6_basket.py. The reference inputs are not part of the repository, and the frozen file is used as is.

bilmine. The scripts run in the order seal_prereg.py, run_control.py, run_exact.py, run_mine.py, run_global.py, emit_verdict.py, close_leg.py, with remine_points.py beside them. f1/ holds the $a+b\sqrt{15}$ counterparts and resume_mine_f1.py.

The inputs of bilmine are named by environment variables: BILMINE_LEG, BILMINE_T5, BILMINE_PFRAME, BILMINE_C1_PI, BILMINE_C1_N, BILMINE_F1_LEG and BILMINE_PARENT, with BILMINE_PRODUCER_LINT optional. No default paths are provided, and a script stops with a message when a variable is unset.

The modules below are submodules of the lockpick package, imported from inside tools/. The ring15 modules named above are in lockpick.ring15.

FunctionWhat it returns
pslq_gate.two_prec_stableThe canonical tuple from the checked two-precision PSLQ search, or None
pslq_gate.members_audit(members, names, dps, h)[] if the list is independent up to coefficient h, else the internal relations found; run it before every search
pslq_gate.controls(members, proto, known_hits)The synthetic control and any known relations you pass; warns when control coefficients are within a factor 10 of maxcoeff
pslq_gate.reverifyThe relative residual of {'target', 'members', 'vector'} at high precision
pslq_gate.odd_zeta_pool(max_weight)A ready-made list of products of odd zeta values, with their weights
pslq_gate.load_amflow_targets(fn), load_target("FILE:key")Targets read from an AMFlow result file or a flat JSON dictionary
mplll.mplll_fit(I, F, names, fit, ho, d, ...)The record of the third example for one fit; method is "qrbkz", "rawlll" or "rawbkz"
mplll.controls(I, F, names, fit, ho, d, W)The synthetic and random-target checks; the command line runs them before a fit, mplll_fit does not
mplll_batch.qrbkz_batch(I_dict, F, names, fit, ho, d)One record per target label plus _meta, from one factorization of the basis
mplll_batch.cvp_fit(I, F, names, fit, ho, d, denom)The nearest-lattice-point rounding with denominator denom
mplll_batch.dmin_sweep(I, F, names, fit, ho, dps)The smallest precision that reproduces the full-precision relation, as {d_min, reference, d_tested}
mplll_graded.graded_fit(I, F, names, weights, fit, ho, d)The weight-by-weight fit; per_weight records {K_w, locked, insample_d, floor_d}, with all_locked
mplll_points.select_points(basis_fn, candidate_xs, K, n_select), select_from_matrix(B_cols, n_select)The point selector from Python

I is the list of $N$ target values, F a list of $K$ such lists, and fit and ho are index lists. mplll_fit is safe at any ambient mp.dps. With weights=None, graded_fit guesses the weights from the names via infer_weight(name) and warns.

The remaining arguments and the lower-level names are in the module sources. tools/lockpick/__init__.py lists the submodules.

Used on this site

Requirements

Source and references

The code is tools/lockpick/ in the BootLoops repository, released under the MIT license. sealrun/ and bilmine/ sit inside it and are run as scripts, not imported.

ReferenceWhat it supplies
O. Barrera, A. Dersy, R. Husain, M. D. Schwartz and X. Zhang, JHEP 01 (2026) 014, arXiv:2507.17815The lattice fit of a sampled function; the rawlll construction follows it
H. R. P. Ferguson, D. H. Bailey and S. Arno, "Analysis of PSLQ", Math. Comp. 68 (1999) 351PSLQ, called through mpmath
A. K. Lenstra, H. W. Lenstra Jr. and L. Lovász, Math. Ann. 261 (1982) 515LLL lattice reduction
F. Johansson and the mpmath contributors, mpmathThe arbitrary-precision arithmetic and the PSLQ routine
The FPLLL development team, fplll, also through its Python binding fpylllLLL and BKZ
C. Fieker, W. Hart, T. Hofmann and F. Johansson, Nemo, arXiv:1705.06134LLL through Julia when fplll is not installed
F. Johansson, O. Benjamin and contributors, python-flintThe integer linear algebra of the bilmine exact stage
The PARI Group, PARI/GPThe reference coefficients in the ring15 newform check

← back to the tools index