Ansatzer
Ansatzer counts, before any expensive numerical work, the unknown coefficients left in the symbola sum of "words", ordered strings of letters drawn from a finite alphabet of functions of the kinematics, encoding the branch cuts ansatza trial sum of the allowed words with unknown coefficients of a polylogarithmic Feynman integral once the standard linear constraints are imposed. It reads the integral's letter alphabet from a small JSON file and reports the surviving dimension at each weightthe number of letters per word; it grows with the loop order and the number of numerical values a fit will need. The constraints are those of the symbol bootstrap: integrability after Goncharov, Spradlin, Vergu and Volovich, first entry after Gaiotto, Maldacena, Sever and Vieira, and Steinmann after Caron-Huot, Dixon, McLeod and von Hippel.
What it does
An alphabet of $n$ letters gives $n^w$ possible words at weight $w$. A bootstrap calculation writes the answer as an unknown combination of words and fixes the coefficients against high-precision numerical values of the integral, each expensive to compute. Whether the fit is affordable depends on how many unknowns survive the constraints.
Ansatzer imposes six families of linear conditions in order and reports the dimension after each:
- Integrability. Only combinations that are the symbol of an actual function are kept.
- First entry. The first letter must vanish at a physical threshold (an invariant or a mass).
- Last entry. The final letter must belong to a declared set.
- Steinmann. The alphabet file may tag letters with the scattering channel whose discontinuity they carry (an optional
channelblock). Two adjacent letters whose tag sets have nothing in common are forbidden. Untagged letters are unconstrained. - Parity. Only the requested sign under square-root sign flips is kept.
- Coproduct. This condition needs the connection matrix of the family's differential equation. For each master integralone of the finite basis of integrals the family reduces to, a final letter is allowed only if that letter's matrix has a non-zero entry in that master's row.
A condition whose input is missing is skipped and the rest still runs. The report header then says steinmann=vacuous (no channel tags) or coproduct=SKIPPED (no connection supplied), and steinmann=SKIPPED (disabled) under --no-steinmann. A skipped column repeats the count before it.
In the table, RESIDUAL is the number of unknowns and pts_needed is 1.3 times that, rounded up. A one-line verdict reads COLLAPSES (at most 12 at every weight), FULL (60 or more at some weight) or INTERMEDIATE.
By default (--method auto), when $n^w \le 500$ everything is solved exactly over the rationals and every column is a true subspace dimension. Otherwise the word list is first filtered by the cheaper conditions and integrability is solved modulo a large prime. For alphabets in more than three variables the equations are sampled at random kinematic points, added until the rank stops changing. Only RESIDUAL is then a dimension; the other columns are word counts. The back end is recorded per weight (rank_method), together with whether sampling converged.
The --per-orbit mode instead builds the integrable space recursively, one weight at a time, keeping only survivors, so it can be used when $n^w$ is far too large to list. It applies integrability and the two entry conditions only, with no Steinmann, parity or coproduct condition. It takes one alphabet at a time, typically that of a single subsector (the family with some propagators removed).
Ansatzer has these limits:
- Letters containing square roots must be given in variables that make every letter rational, for example $O_{A3}=((1+y)/(1-y))^2$ with $t=4/(1+y^2)$, as in
alphabets/p4_J25.json. Otherwise the counts are wrong. - A weight at which integrability exceeded
--timeoutis markedbound: ≥N. That number is an upper limit and is not to be used for planning. - Ansatzer only sizes the fit. It evaluates nothing.
The alphabet file usually comes from Landau Alphabet, and the point count is what a coefficient fit with Lockpick will consume.
V. Mitev and Y. Zhang wrote SymBuild (arXiv:1809.05101), and T. Peraro wrote the Symbols package of FiniteFlow MathTools (arXiv:1905.08019). Both are earlier public programs that build integrable symbols weight by weight over a finite field, with entry conditions, forbidden adjacent sequences and even or odd selection. The --per-orbit mode uses the same standard recursion as both programs.
Examples
Run the self-tests. The alphabets/ folder holds small example inputs with known counts, and the test script checks four of them. With the package set up (see Requirements), run from the package directory tools/ansatzer/:
python3 test_ansatzer.py
The run ends with ALL PASS. For the three-letter alphabet $\{s,\,t,\,s+t\}$ with first entries $\{s,\,s+t\}$ (alphabets/p4_J23.json) it prints this table (columns narrowed to fit):
=== P4_J23 (3 letters; rank=exact_Q; steinmann=vacuous (no channel tags); coproduct=SKIPPED (no connection supplied)) ===
weight | raw | integrability | first | last | steinmann | parity | coproduct | RESIDUAL | pts_needed
-----------------------------------------------------------------------------------------------
0 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 2
1 | 3 | 3 | 2 | 2 | 2 | 2 | 2 | 2 | 3
2 | 9 | 7 | 4 | 4 | 4 | 4 | 4 | 4 | 6
3 | 27 | 15 | 8 | 8 | 8 | 8 | 8 | 8 | 11
4 | 81 | 31 | 16 | 16 | 16 | 16 | 16 | 16 | 21
VERDICT: INTERMEDIATE (16/weight; ~21 pts) (max RESIDUAL = 16, pts_needed ≈ 21)
On the weight-four line, 31 independent combinations of the 81 words are integrable and the first-entry condition leaves 16. No later condition removes anything, because the file has no channel tags, no parity data and no connection. A weight-four fit would need about 21 numerical values. The tests make the same call from Python:
from ansatzer import predict_collapse, format_table
rep = predict_collapse("alphabets/p4_J23.json", weight_max=4, method="exact_Q")
print(format_table(rep))
Add a connection matrix for per-master counts. In the toy connection alphabets/p4_J23_conn.json, master m1 couples only through $s$ and $s+t$ and m2 only through $t$ and $s+t$.
python3 ansatzer.py --alphabet alphabets/p4_J23.json --connection alphabets/p4_J23_conn.json \
--wmax 4 --out report.json
The header now says coproduct=applied, the coproduct column drops from (2, 4, 8, 16) to (2, 3, 5, 9), and the verdict becomes COLLAPSES (≤9/weight; few-point fit). report.json holds the table under per_weight and the residual for each master under per_master (m1: 2, 3, 5, 9; m2: 1, 2, 4, 8). Under honesty it holds the back end and whether the Steinmann and coproduct conditions ran.
Count recursively. The per-orbit mode takes the same alphabet file.
python3 ansatzer.py --per-orbit --alphabet alphabets/p4_J23.json --wmax 4 --npts 96 --out r.json
The output JSON has Kw_LE, the count per weight with the last-entry condition (here 1, 2, 4, 8, 16, matching the table above), and Kw_full_noLE, the count before it, skipped at the top weight. Its converged entry records per weight whether the modular rank stabilized and at how many points, for example [true, 12]. A false means the --npts cap was hit first and the count is not yet final.
Routines
The command line is python3 ansatzer.py with these options:
| Command | What it does |
|---|---|
--alphabet A.json | The table of counts for one alphabet; required |
--connection C.json | Adds the coproduct condition and the residual for each master |
--wmax | The highest weight counted |
--method | The back end: auto, exact_Q or modp |
--no-steinmann | Skips the Steinmann condition |
--timeout | Limit in seconds on integrability at each weight |
--out | Writes the report as JSON |
--compare B.json | Prints a second alphabet's table beside the first |
--per-orbit | The recursive count; --npts caps the number of sample points |
The alphabet file holds name, vars, letters (letter name to expression) and the optional first_entry, last_entry, parity, parity_target and channel. The connection file holds masters and A, one matrix per letter, as sparse [[i,j,"q"],...] entries or dense rows. The alphabets/ folder holds six example inputs, and p4_J25_collapse.json is a sample output report. alphabets/synth_7letter.json shows the parity and channel blocks.
The Python functions are imported from ansatzer.
| Function | What it returns |
|---|---|
load_alphabet(path_or_dict) | An Alphabet object; Landau Alphabet output is adapted automatically |
load_connection(path_or_dict, letter_names) | A Connection object; only the non-zero pattern is kept |
predict_collapse(alphabet_json, *, connection, weight_max, masters, method, steinmann, timeout_s, verbose) | The report dictionary after all six conditions; arguments after the first are passed by keyword |
format_table(rep) | The report as the text table shown above |
compare(report_A, report_B) | Two reports side by side, as text |
recursive_Kw(alpha_json, wmax, npts_max) | The recursive count behind --per-orbit |
The raw count and each condition can also be called alone: symbol_space_dims, integrability_cut, entry_cut, steinmann_cut, parity_cut and coproduct_cut, all defined in ansatzer.py.
Used on this site
- Massless planar double box: imposed first entry, integrability and the absence of a $u$-channel cut on the word space.
- Outer-mass double box: built the weight-four words over the twelve letters and reduced them by integrability, first entries and square-root parity.
- Three-loop ladder: built the basis of 64 weight-six words in the two letters for the fit.
- One-loop massless pentagon: imposed the first-entry, integrability and parity conditions on the weight-two and weight-three words.
Requirements
- Runs on: Python 3 with
numpyandsympy. - Install: no build step. Run the scripts from the package directory
tools/ansatzer/. - Self-test:
python3 test_ansatzer.pyends withALL PASS. Test T5 checks the Landau Alphabet adapter and skips unlessCOLLAPSE_T5_ALPHABETpoints at such a file. - Optional: setting
COLLAPSE_NPTS_MAXabove its default of 12 lets the modular back end use more sample points when it reports that sampling did not converge.
Source and references
The code is tools/ansatzer/ in the BootLoops repository. The CREDIT entry of GUIDE.md there names the papers behind the conditions.
| Reference | What it supplies |
|---|---|
| A. B. Goncharov, M. Spradlin, C. Vergu and A. Volovich, arXiv:1006.5703; L. J. Dixon, J. M. Drummond and J. M. Henn, arXiv:1108.4461 | Symbols and the integrability condition |
| D. Gaiotto, J. Maldacena, A. Sever and P. Vieira, arXiv:1102.0062 | The first-entry condition |
| S. Caron-Huot, L. J. Dixon, A. McLeod and M. von Hippel, arXiv:1609.00669 | The Steinmann relations as used in the symbol bootstrap |
| S. Caron-Huot, L. J. Dixon, F. Dulat, M. von Hippel, A. J. McLeod and G. Papathanasiou, arXiv:1906.07116 | The extended form of the Steinmann relations |
| C. Duhr, arXiv:1203.0454; A. B. Goncharov, math/0103059 | The coproduct condition, in Duhr's formulation of Goncharov's coproduct |
| J. L. Bourjaily, H. Hannesdottir, A. J. McLeod, M. D. Schwartz and C. Vergu, arXiv:2007.13747 | The sequential-discontinuity constraints |
| H. S. Hannesdottir, A. J. McLeod, M. D. Schwartz and C. Vergu, arXiv:2211.07633 and arXiv:2410.02424 | The sequential-discontinuity constraints in the Landau bootstrap |
| V. Mitev and Y. Zhang, SymBuild, arXiv:1809.05101 | An earlier public program that builds integrable symbols |
| T. Peraro, the Symbols package of FiniteFlow MathTools, arXiv:1905.08019 | An earlier public program that builds integrable symbols |
| Abreu, Chicherin, Sotnikov and Zoia, arXiv:2408.05201 | The published two-mass planar five-point alphabet; 16 of the 19 letters of alphabets/5pt_2mass_nonplanar.json coincide with its letters after relabeling the legs |