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":
- Too few digits. The target carries fewer digits than the working precision.
- Too large a search. The search needs more digits than the 120-digit run provides, about $(n+1)\log_{10}H+20$ for $n$ candidates.
- Dependent candidates. The candidates themselves satisfy an integer relation. PSLQ would return that relation with a zero coefficient on the target, so the module names the dependent constants and stops.
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.
| Method | What it does |
|---|---|
qrbkz (default) | Orthogonalizes the data matrix before BKZ reduction, which removes the ill-conditioning that many sample points cause |
rawlll | Embeds the raw data as in arXiv:2507.17815; works with fewer points |
rawbkz | Reduces the same raw lattice with BKZ |
graded | Treats a basis graded by transcendental weight one weight at a time; reports the weights at which a relation was found (locked) |
cvp | Rounds 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.
- Status.
HITrequires that the relation reproduce the target at the withheld points to at least 30 digits and reappear unchanged when the fit is repeated at $d-20$ digits. Otherwise the status isPARTIAL.NULLmeans no vector under the coefficient bound. - Capacity. The
capacityentry says whether $N_{\rm fit}\cdot d$ digits can support the relation found. - Controls. A synthetic target that must be found and a random one that must not be are fitted first (exit code 2 on failure).
- Span. Read
span_residual_dto tell two kinds of failure apart. A value above $d$ means the target lies in the span of the basis at the working precision, so a missing relation is a matter of coefficient size. A value below $d$ is the number of digits to which this basis can reproduce the target at all: a function is missing, and more digits will not help. - Dependent basis. A
basis_relationsentry means the basis is itself dependent; prune it first.
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:
- Dirichlet $L$-values for the quadratic characters of discriminant $-15$, $-3$, $-4$ and $5$ (
ring15_core.dirichlet_L(s, D)). - The Chowla–Selberg period $\Omega_D$, a fixed power of the product $\prod_a\Gamma(a/|D|)^{\chi_D(a)}$ divided by $\sqrt{2\pi|D|}$ (
ring15_core.Omega(D)). - The Dedekind-eta periods $\sqrt{\operatorname{Im}\tau}\,|\eta(\tau)|^2$ at the two CM points of discriminant $-15$ (
ring15_core.cm_period_eta(a, b, c)for the quadratic form $[a,b,c]$). - The exact integer Fourier coefficients (
ring15_hecke.a_n_list(N, s), with signs = ±1) and the $L$-values at $s=1,2,3$ (ring15_lfun.L_values()) of the two CM newforms of weight 3 and level 15.
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".
- Checks. Every run repeats the dependence audit and the two controls (a synthetic target that must be found, a pseudo-random one that must not).
- Bounds. The run then raises the coefficient bound in steps from $10^4$ to $10^{12}$ and refuses the steps that the digits cannot support.
- Withheld digits. The fits use at most the target's digits minus 40, and a hit is re-verified on digits no fit used.
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.
- Search. One homogeneous lattice reduction finds the entries.
- Two precisions. The span found is compared between two precisions through its Hermite normal form.
- Withheld entries. Entries of $S$ withheld from the fit must come out as integers afterwards.
- Exact stage. Integer linear algebra confirms the result.
- Second stage. A second search allows coefficients of the form $a+b\sqrt{15}$.
Lockpick has these limits:
- An accepted relation is evidence, never a proof. Confirm it against an independent evaluation (Gatekeeper, PSLQ and LLL).
- A null result of
sealrunexcludes only its list of constants up to the printed bound. qrbkzneeds at least $K+1$ fit points.- From weight 11 on, the products of odd zeta values in
odd_zeta_poolno longer span the single-valued multiple zeta values. sealruntakes real targets. A complex value must be split into real and imaginary parts, one run each.
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.
| Command | What 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.py | The 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.py | Rebuilds 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.
| Option | Meaning |
|---|---|
--basis B | JSON file {"names": [...], "values": {name: [v_1, ..., v_N]}}, with the values at the $N$ sample points as decimal strings |
--target T | JSON list of the target's $N$ values; complex values written (re+imj) are split and fitted jointly |
--dps D | The number of digits the data support (default 100) |
--height H | The weight $W$ on the coefficient block of the rawlll lattice; the largest accepted coefficient for graded and batch fits (default $10^8$) |
--backend | Forces one reduction backend: fpylll, fplll-cli, nemo or pure |
--held-out, --fit-points | Comma-separated point indices |
--weights FILE.json | Each basis function's integer weight, for graded |
--denom D, --ls-coeffs FILE.json | For cvp: the denominator and, optionally, the least-squares coefficients |
--dmin-sweep | Runs the precision sweep |
--no-controls | Skips 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 code | Meaning |
|---|---|
| 0 | A relation was found and confirmed |
| 1 | None up to the printed bound |
| 2 | The controls failed (no result) |
| 3 | The list is dependent (a null would be void) |
| 4 | Input 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.
| Function | What it returns |
|---|---|
pslq_gate.two_prec_stable | The 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.reverify | The 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
- Three-loop light-by-light: the lattice fits of $\Delta$ (a combination of two top-sector master integrals and $3\zeta_3$) to weight-four polylogarithms over the admissible letters, whose residual is the iterated integral of the K3 period.
- Non-planar hexa-box: the integer-relation searches on the boundary constants. Apart from the six constants with closed forms, the search finds no combination of the expected transcendental constants.
Requirements
- Runs on: Python 3 with mpmath.
ring15needs only mpmath; pytest is needed for the regression tests. - Install: A clone is the installation. Run
git clone https://github.com/BootLoops-ai/bootloops, thenpip install mpmath sympy numpy python-flint, the repository's common Python dependencies. - Lattice reduction: BKZ needs the
fpylllmodule or thefplllexecutable (FPLLLoverrides its path). Without them the fitter falls back to LLL through Julia with the Nemo and JSON packages (JULIAnames the executable). The last fallback is a pure-Python routine imported fromtools/gatekeeper/, which must sit besidetools/lockpick/. - Time limit:
MPLLL_FPLLL_TIMEOUTsets an optional time limit in seconds for one reduction; unset or 0 means none. A reduction that it ends raisesMplllTimeoutExpired. - Optional:
bilminealso needs sympy and python-flint for its exact stage. - Self-test:
python3 tools/pslq_gate.py --selftest, run from the repository root, ends withSELFTEST PASS (16/16). - Regression tests:
python3 -m pytest tools/lockpick/tests. bilmineself-test:python3 tools/lockpick/bilmine/selftest.pytakes seconds and ends withbilmine selftest: PASS.sealrunself-test:python3 tools/lockpick/sealrun/t6_close.py --target-string-file tools/lockpick/sealrun/selftest_planted_target.txt --label plantedmust exit 0. The same command withselftest_null_target.txt --label nullmust exit 1. The pair takes minutes and writes itsCLOSE_*.jsonrecords into the current directory unless--out DIRis given.
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.
| Reference | What it supplies |
|---|---|
| O. Barrera, A. Dersy, R. Husain, M. D. Schwartz and X. Zhang, JHEP 01 (2026) 014, arXiv:2507.17815 | The 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) 351 | PSLQ, called through mpmath |
| A. K. Lenstra, H. W. Lenstra Jr. and L. Lovász, Math. Ann. 261 (1982) 515 | LLL lattice reduction |
| F. Johansson and the mpmath contributors, mpmath | The arbitrary-precision arithmetic and the PSLQ routine |
The FPLLL development team, fplll, also through its Python binding fpylll | LLL and BKZ |
| C. Fieker, W. Hart, T. Hofmann and F. Johansson, Nemo, arXiv:1705.06134 | LLL through Julia when fplll is not installed |
| F. Johansson, O. Benjamin and contributors, python-flint | The integer linear algebra of the bilmine exact stage |
| The PARI Group, PARI/GP | The reference coefficients in the ring15 newform check |