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.
- Order. Griffiths–Dwork reduction (the reduction of the derivatives of $1/G$ modulo exact forms) is run modulo a prime below $2^{29}$, with the other kinematic variables set to random values. The run is repeated at a second prime and the two orders must agree (fields
pf_order_2p,stable). - Nonlinear case. A $G$ nonlinear in $s$ is detected and handled by an exact recursion for the derivatives.
- Rank. The rank is a count of the Euler characteristichere, the number of isolated solutions of the regulated critical-point equations of G, done by Leviathan.
- Reducibility.
reducibleis true when the order is below the rank: the maximal cut (all propagators on shell) does not generate the whole family.
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.
- Recount.
dipstick auditrecounts the critical points of a two-variable system without msolve. It eliminates one variable with an exact resultant modulo a large prime and subtracts the spurious roots at the points where lines cross.--fastselects an evaluate-and-interpolate variant for about twenty lines or more. - Characteristic polynomial.
dipstick flatchicomputes $\chi_A(q)$ of a hyperplane arrangement exactly, from its lattice of intersections and the Möbius function, in any dimension $k$. It prints the number of bounded regions $|\chi_A(1)|$ and the number of regions $(-1)^k\chi_A(-1)$ (Zaslavsky's theorem).
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.
- Enumerate. Each monomial of $G=U+F$ gets one extra coordinate, the power of the small parameter it carries. The regions are the lower facets of the Newton polytope (the convex hull of the exponent vectors) in that higher dimension. Oscar enumerates them.
- Read off. The normal of a facet gives the scaling vector $v_R$ of the region: the power of the small parameter by which each integration variable scales (components may be negative). The monomials on the facet form the region's polynomial $G_R$.
- Volume sum. The normalized volumes $n!\,\mathrm{Vol}$ of the projected facets must add up to that of the Newton polytope of $G$ without its extra coordinate, an exact tiling identity.
- Count sum. The master-integral counts $\chi(G_R)$, computed by Leviathan, must add up to $\chi(G)$.
- Compare. A list of regions in the input file, given as scaling vectors, is compared with the enumeration. On a failure the report names each missing region by its scaling vector.
Dipstick has these limits:
orderis meant for up to four integration variables. Integrals known only as a series belong to Annihilator.- An order equal to
Lmax+1, whereLmaxis the highest derivative tried, means the search stopped at its ceiling and is not an answer. RaiseLmax, or usepf_probe_esc, which does so automatically. - The operator is never factored.
countis a rank probe and does not solve the system. Its built-in generator covers $X(3,n)$.- The output of
cycletypeis evidence, valid when the reduction at each prime is squarefree. Discard a prime that shows a repeated factor. - The certificate of
nonresholds at the tested $\beta$ only. - msolve 0.6.5 does not range-check the coefficients of an input file in characteristic $p$, and coefficients outside $[0,p)$ have given wrong counts with no error. Always cross-check a two-variable count with
audit. regionscertifies that a list is complete. It does not build or resum the series.- Hidden regions (of Glauber type) need not show up as facets of $G$ alone. For such families a failed $\chi$ sum is the only sign, so do not rely on the volume sum by itself.
- A failed $\chi$ sum together with a complete list means that some $G_R$ is degenerate: it factors, or sits on a Landau singularity (a kinematic point where the integral can become singular). That is a property of the region and not a missing region. The included large-mass example is such a case: it passes the volume test while its $\chi$ values sum to 4 against 5.
DIPSTICK_SKIP_CHI=1skips the $\chi$ computation for large families, leaving the volume certificate and printingNAfor every $\chi$. Treat a skipped or mismatched $\chi$ as unverified, and check the expanded result against a numerical value before using it.
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
- Count. The first command prints
X(3,6): 14 factors, 18 vars, 18 eqs, max deg 3and writescrit36.ms. - Solve. The second runs msolve on 8 threads under a 30 GB cap. The degree that opens the parametrization block of
crit36.out([1, [[26, ...) is 26, the rank. - Cycle types. The third prints lines such as
p=1073741833: cycle type [1, 1, 2, 5, 17]andp=1073741789: cycle type [5, 21], thenrational-factor candidate degrees: NONE (irreducible/transitive), the parities (three of six odd) and the Jordan line withn = 26. A transitive group on 26 points containing a 17-cycle and an odd element is the full symmetric group $S_{26}$. - Resonance. The last prints
43 exact-verified distinct facetsandRESONANT facets at the physical point: 10 of 43: the exponents inw5_seed_base.jsonare a special point. The guide records that at generic rational exponents none of the 43 facets is resonant, which certifies the module irreducible with 26 solutions.
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
| Command | What 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 nonres | Facet 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 ...].
| Function | What 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
- Runs on: Python 3 with sympy and numpy, which is enough for
count,auditandflatchi.nonresalso needs scipy andcycletypeneeds python-flint. - Julia:
orderneeds Julia with Oscar and Leviathan.regionsneeds Julia 1.10 or newer with the Oscar and JSON packages and Leviathan. - msolve:
countandcycletypeneed the msolve binary of Berthomieu, Eder and Safey El Din (msolve.lip6.fr). - Install: Oscar is not part of the package; you install it yourself. From a clone of the repository,
julia --project=upgrades/leviathan -e 'import Pkg; Pkg.instantiate()'installs the whole Julia stack once (a large download). Then setDIPSTICK_JULIA_PROJECTto that project, or to another that provides Oscar;orderandregionsuse the default Julia environment when it is unset. - Optional: the environment variables
DIPSTICK_JULIA(the Julia command, for examplejulia +1.10),DIPSTICK_SKIP_CHI(regionsonly),DIPSTICK_MSOLVE(a wrapper to use in place ofrun_msolve_capped.sh) andMSOLVE_BIN(the path of the msolve binary). - Leviathan:
DIPSTICK_LEVIATHANis the path toLeviathan.jl. Without it, Dipstick looks in a siblingleviathan/folder undertools/and then inupgrades/leviathanin the repository. - Self-test: run the three commands below from the package directory.
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.
| Reference | What it supplies |
|---|---|
| V. Chestnov, G. Crisanti and M. Giroux, "Landau's Leviathans", arXiv:2606.29612 | The method of the master-integral count that order and regions take from Leviathan |
| G. Crisanti, L. Lippstreu, A. J. McLeod and M. Polackova, DiscKosky | euler_characteristic.m, from which routines of Leviathan are translated |
| Pak and Smirnov, arXiv:1011.4863 | The Newton-polytope construction of the regions, implemented by regions |
| Jantzen, Smirnov and Smirnov, arXiv:1206.0546 | The regions that are not facets of $G$ alone (the Glauber-type limit above) |
| Beneke and Smirnov | The expansion by regions |
| P. A. Griffiths, doi:10.2307/1970746; P. Lairez, arXiv:1404.5069 | Griffiths–Dwork reduction, used by order |
| R. N. Lee and A. A. Pomeransky, arXiv:1308.6676 | The 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.08967 | The 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. 154 | Hyperplane 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.08904 | The $X(3,6)$ integrals used as test cases |
| J. Berthomieu, C. Eder and M. Safey El Din, msolve, arXiv:2104.03572 | The polynomial-system solver behind count and cycletype |
| The OSCAR team, OSCAR, doi:10.1007/978-3-031-62127-7 | The computer algebra system that order and regions run on |