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:

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:

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:

CommandWhat it does
--alphabet A.jsonThe table of counts for one alphabet; required
--connection C.jsonAdds the coproduct condition and the residual for each master
--wmaxThe highest weight counted
--methodThe back end: auto, exact_Q or modp
--no-steinmannSkips the Steinmann condition
--timeoutLimit in seconds on integrability at each weight
--outWrites the report as JSON
--compare B.jsonPrints a second alphabet's table beside the first
--per-orbitThe 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.

FunctionWhat 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

Requirements

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.

ReferenceWhat 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.4461Symbols and the integrability condition
D. Gaiotto, J. Maldacena, A. Sever and P. Vieira, arXiv:1102.0062The first-entry condition
S. Caron-Huot, L. J. Dixon, A. McLeod and M. von Hippel, arXiv:1609.00669The 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.07116The extended form of the Steinmann relations
C. Duhr, arXiv:1203.0454; A. B. Goncharov, math/0103059The 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.13747The sequential-discontinuity constraints
H. S. Hannesdottir, A. J. McLeod, M. D. Schwartz and C. Vergu, arXiv:2211.07633 and arXiv:2410.02424The sequential-discontinuity constraints in the Landau bootstrap
V. Mitev and Y. Zhang, SymBuild, arXiv:1809.05101An earlier public program that builds integrable symbols
T. Peraro, the Symbols package of FiniteFlow MathTools, arXiv:1905.08019An earlier public program that builds integrable symbols
Abreu, Chicherin, Sotnikov and Zoia, arXiv:2408.05201The 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

← back to the tools index