Dipstick

Dipstick is a set of cheap probes to run on an integral before committing to an expensive calculation. From the polynomial that defines a Feynman integral or a more general Euler-type integralan integral of a product of powers of polynomials, it reports the order of the integral's differential equation in a chosen variable and the number of master integralsthe finite basis to which every integral of the family reduces. The count is done by Leviathan, a partial port of the program of Chestnov, Crisanti and Giroux, and the regions of an expansion by regionsthe expansion of a Feynman integral in a small parameter as a sum of simpler integrals, one per region are enumerated by the Newton-polytope construction of Pak and Smirnov.

What it does

A Feynman integral, as a function of one kinematic variable $s$, satisfies a linear differential equation called its Picard–Fuchs equation. The order of that equation gives the geometry, and so the class of functions, of the answer: order 2 means an elliptic curve, 3 a K3 surface, 4 a Calabi–Yau threefold. The holonomic rankthe dimension of the solution space of the full system of differential equations in all variables; for a Feynman family, the number of master integrals is the size of the full system of differential equations. Both are available before any reduction has run.

Order and rank. dipstick order computes both from the Lee–Pomeransky polynomialthe single polynomial G = U + F built from the two Symanzik graph polynomials of the diagram $G$, given as a string.

Rank in many variables. For an Euler integral $\int \prod_i p_i(x)^{s_i}\,dx$ in many variables the linear algebra of order is too large. dipstick count uses another fact: at generic exponents the holonomic rank equals the number of critical points of $\sum_i s_i \log p_i$ (the maximum-likelihood degree of algebraic statistics). It writes the sparse Lagrange system

$$\lambda_i\, p_i(x) = u_i \ \ (\text{one per factor}), \qquad \sum_i \lambda_i\, \partial p_i/\partial x_j = 0 \ \ (\text{one per variable}),$$

with random integer $u_i$, as an input file for the polynomial-system solver msolve. You run msolve through run_msolve_capped.sh and read off the number of solutions, which is the rank. The wrapper refuses to start without a memory cap, because msolve's matrix allocation has no internal limit. The built-in generator covers $X(3,n)$: $n$ points in the projective plane, with the non-constant $3\times3$ minors as factors.

Galois evidence. dipstick cycletype re-solves such a system modulo six primes and factors the eliminating polynomial at each with FLINT. The factor degrees at a prime form the cycle type of a Frobenius element in the Galois group that permutes the critical points. The script prints them with a transitivity test, the parity of each permutation and Jordan's criterion for the full symmetric group.

Resonance. dipstick nonres checks the GKZ (Gelfand–Kapranov–Zelevinsky) hypergeometric system of the $X(3,6)$ integral stored in GKZ36.json. It enumerates the facets of the cone over the columns of the $A$-matrix with qhull in floating point. Each normal is made integral and verified exactly, and unverifiable facets are dropped. The parameter vector $\beta$, built from the exponents in w5_seed_base.json, is paired exactly with every facet normal. An integer pairing is a resonance; with none, the GKZ module is irreducible at $\beta$.

Arrangements. Two subcommands serve arrangements of lines or hyperplanes, where every factor $p_i$ is linear.

At generic weights the bounded-region count equals the number of critical points (Varchenko's theorem), which gives a second check on audit.

Expansion by regions. The small parameter can be a small mass, the distance to a threshold or the inverse of a heavy mass. A region is one way the integration variables can scale with it. If a region is left out, the series still converges, but to a wrong value, and the series itself gives no warning. dipstick regions checks the list of regions.

Dipstick has these limits:

The count in order and regions is the routine chi_regulated of Leviathan, which includes routines translated from the DiscKosky package of Crisanti, Lippstreu, McLeod and Polackova. The region enumeration implements the Newton-polytope construction of Pak and Smirnov (arXiv:1011.4863) for the expansion by regions of Beneke and Smirnov. Please cite their papers when you use order or regions.

GeoTriage infers the Picard–Fuchs order from the genus or the number of residual variables without constructing an operator; dipstick order is the check when the order matters.

Examples

Picard–Fuchs order of the sunrise. With the package set up (see Requirements), run from the package directory tools/dipstick/. The command dipstick is the script of that name in the directory: call it as ./dipstick, or put the directory on your PATH. The arguments are the polynomial, the kinematic variable names, the integration variables, the variable to differentiate in, and optionally Lmax (default 6):

dipstick order 'x1*x2+x1*x3+x2*x3 + s*x1*x2*x3 - (x1+x2+x3)*(x1*x2+x1*x3+x2*x3)' s x1,x2,x3 s 3

The command prints a named tuple with holonomic_rank = 7, pf_order = 2, pf_order_2p = (2, 2), stable = true, reducible = true and Lmax = 3. In Julia the same call is include("pf_rank.jl"); pf_probe(Gstr, kin, xvars, "s"; Lmax=6). For an Oscar polynomial, here the regression suite's Legendre family in $s^2$:

R3, (w,z,s3) = Oscar.polynomial_ring(Oscar.QQ, ["w","z","s"])
G3 = w^2 - z*(z-1)*(z-s3^2)
r3 = pf_probe_gen(G3, R3, ["w","z"], ["s"], "s"; Lmax=3)

r3.pf_order is 2 and r3.stable is true; pf_probe_gen does not compute the rank.

Rank, Galois evidence and resonance for $X(3,6)$.

dipstick count 6
MSOLVE_CAP_GB=30 ./run_msolve_capped.sh -f crit36.ms -o crit36.out -t 8
dipstick cycletype crit36.ms
dipstick nonres

A second count and the region numbers for a line arrangement. The package includes a toy system of four generic lines in the plane, fixtures/audit_toy.ms:

dipstick audit fixtures/audit_toy.ms
dipstick audit --fast fixtures/audit_toy.ms
dipstick flatchi fixtures/audit_toy.ms
dipstick flatchi --quick

Each audit call prints one Python dictionary per file. It holds a tally of intersection points by how many lines meet there (census), the resultant's degree (degR), the multiplicity removed at intersection points (arr_val), and the count crit, here 3. The exact and --fast routes must agree field for field. flatchi on the same file prints chi_A(q) = q**2 - 4*q + 6 and bounded (|chi(1)|): 3 regions: 11: three bounded regions, matching the three critical points, and eleven regions in all.

dipstick flatchi --quick runs the built-in projective example, the 15 lines through pairs of 6 generic points in the plane, and prints chi_top = 42 (expect 42). Without --quick it continues to the 35 planes through triples of 7 generic points in projective 3-space, which takes minutes.

Is this list of regions complete? Four input files come with the package under regions/tests/. The one-loop massive bubble at large momentum transfer, bubble_largeQ.json, has $Q^2=-1$ and the small parameter $t=m^2$, and lists the textbook three regions (hard and two collinear):

{
  "G": "x1+x2 + t*(x1+x2)^2 + x1*x2",
  "kin": ["t"],
  "x": ["x1","x2"],
  "kin_weight": {"t": 1},
  "regions": [[0,0],[-1,0],[0,-1]]
}

Here kin_weight gives t the first power of the small parameter. A heavy squared mass would get weight -1, as M2 does in the two large-mass files, and a fixed scale weight 0. Run the bubble together with the deliberately incomplete large-mass example:

dipstick regions regions/tests/bubble_largeQ.json regions/tests/largemass_toy_incomplete.json

The call loads Oscar once (about 45 seconds; extra files in the same call add seconds) and prints one report per file, each opening with == dipstick regions: <file> ==. A report lists every region found as R1, R2, ... with its scaling vector v, its n!Vol, its chi and its polynomial G_R; a region of zero volume is marked [scaleless]. The two sums follow, marked [TILES OK] and [CHI ADDITIVITY OK] when they agree.

For the bubble the three listed regions are the three facets and the report ends VERDICT: PASS (region list complete). The large-mass file, a one-loop triangle with one heavy internal line, lists the single region [0,0,1]. The enumeration finds a second, and the report ends VERDICT: FAIL (region list INCOMPLETE) with a MISSING facets line naming the scaling vector $(1,1,1)$, a volume deficit of 3 and a $\chi$ deficit of 2.

The companion file largemass_toy_complete.json lists both regions and passes. sunrise_threshold.json, the two-loop equal-mass sunrise near its threshold, has no regions entry and is enumerated only.

Routines

CommandWhat it does
dipstick order '<Gstr>' <kin_csv> <x_csv> <svar> [Lmax]Picard–Fuchs order in svar, checked at two primes, and the holonomic rank
dipstick count <npts>Writes the critical-point system of $X(3,n)$, $n$ = npts, to crit3<n>.ms in the current directory, for msolve
dipstick cycletype [file.ms]Re-solves at six primes (8 threads, 30 GB cap each) and prints the cycle types; default crit36.ms
dipstick nonresFacet enumeration and exact pairing check for the included $X(3,6)$ GKZ system
dipstick audit [--fast] <file.ms> [more files]Exact critical-point count of a two-variable line arrangement by resultant, one dictionary per file
dipstick flatchi <file.ms>Characteristic polynomial, bounded-region count and region count of the affine arrangement in the file
dipstick flatchi [--quick]The built-in projective examples; --quick stops after the first
dipstick regions <in.json> [more.json ...]Enumerates the regions of each file, tests the two sums and prints the verdict when the file lists regions
run_msolve_capped.sh <msolve args>msolve under a mandatory address-space cap of MSOLVE_CAP_GB gigabytes (a plain integer; 31G is rejected)

Exit code 2 from run_msolve_capped.sh means that it refused to start. Any other code is msolve's, and 139 usually means that the cap was hit and should be raised.

audit and flatchi read a .ms file. Its first line names the variables and its second line gives the field characteristic (0). The remaining rows, one for each line $i$ of the arrangement, are the expanded form of $m_i(a_i x_1+b_i x_2+c_i)-u_i$. flatchi treats the rows as affine hyperplanes.

regions reads a JSON file with "G" (the polynomial $U+F$ as a string), "kin" (kinematic symbol names), "x" (integration variable names) and "kin_weight". "kin_weight" maps a symbol to its integer power of the small parameter; symbols left out count as 0. Two keys are optional: "regions" (the scaling vectors to certify) and "seed" (for the random evaluation points of the $\chi$ count). The direct call is julia --project=<your Oscar project> regions/regions.jl <in.json> [more.json ...].

FunctionWhat it returns
pf_probe(Gstr, kinnames, xnames, svar; Lmax)From polynomial strings, a named tuple with holonomic_rank, pf_order, pf_order_2p, stable, reducible and Lmax
pf_probe_gen(GQ, R, xnames, kinnames, svar; Lmax)The order for an Oscar polynomial of any degree in svar; no rank
pf_probe_esc(GQ, R, xnames, kinnames, svar; Ls)pf_probe_gen repeated with increasing Lmax until the order is unsaturated and both primes agree; adds saturated

tools/pf_rank.jl is a one-line file that includes tools/dipstick/pf_rank.jl. The Python scripts can be imported as well: build in critcount.py, audit in resaudit2.py and resaudit_fast.py, affine_chi in flatchi_aff.py, and flats_and_chi and planes_from_points in flatchi.py. GUIDE.md in the package directory describes every subcommand.

Requirements

python3 battery.py
julia --project=<your Oscar project> regress_order.jl pf_rank.jl
python3 regions/selftest.py

The first command reruns each subcommand against the reference outputs in fixtures/. It prints PASS, FAIL, or SKIP with the reason when an engine is missing (Julia with Oscar, msolve, scipy, sympy); --legs count,cycletype,nonres,regions selects parts. The Julia line runs the seven order cases and ends RESULT: 7/7 PASS. It prints order=2 2p=(2, 2) hr=7 for the equal-mass sunrise and order=3 2p=(3, 3) hr=15 for the three-loop banana.

The third command runs the regions check on three of its included inputs in one Julia process (about 50 seconds). It must end dipstick regions selftest PASS (bubble + positive + negative control). Without Julia, or without the Oscar and JSON packages, it prints SKIP, names the missing package, gives the install command and exits 0.

Source and references

The code and its guide are tools/dipstick/ in the BootLoops repository, with the regions check in its regions/ subfolder.

ReferenceWhat it supplies
V. Chestnov, G. Crisanti and M. Giroux, "Landau's Leviathans", arXiv:2606.29612The method of the master-integral count that order and regions take from Leviathan
G. Crisanti, L. Lippstreu, A. J. McLeod and M. Polackova, DiscKoskyeuler_characteristic.m, from which routines of Leviathan are translated
Pak and Smirnov, arXiv:1011.4863The Newton-polytope construction of the regions, implemented by regions
Jantzen, Smirnov and Smirnov, arXiv:1206.0546The regions that are not facets of $G$ alone (the Glauber-type limit above)
Beneke and SmirnovThe expansion by regions
P. A. Griffiths, doi:10.2307/1970746; P. Lairez, arXiv:1404.5069Griffiths–Dwork reduction, used by order
R. N. Lee and A. A. Pomeransky, arXiv:1308.6676The polynomial $G$ and the count of master integrals as critical points
J. Huh, arXiv:1207.0553; Catanese, Hoşten, Khetan and Sturmfels, math/0406533; Bitoun, Bogner, Klausen and Panzer, arXiv:1712.09215; Agostini, Fevola, Sattelberger and Telen, arXiv:2208.08967The holonomic rank of an Euler integral as an Euler characteristic and a maximum-likelihood degree, used by count
P. Orlik and H. Terao, Invent. Math. 120 (1995) 1; T. Zaslavsky, Mem. Amer. Math. Soc. 1 (1975) no. 154Hyperplane arrangements, used by flatchi and audit
Gelfand, Kapranov and Zelevinsky (1994); Saito, Sturmfels and Takayama (2000)GKZ systems, used by nonres
F. Cachazo, N. Early, A. Guevara and S. Mizera, arXiv:1903.08904The $X(3,6)$ integrals used as test cases
J. Berthomieu, C. Eder and M. Safey El Din, msolve, arXiv:2104.03572The polynomial-system solver behind count and cycletype
The OSCAR team, OSCAR, doi:10.1007/978-3-031-62127-7The computer algebra system that order and regions run on

← back to the tools index