SubTropica (external)

SubTropica and its integration engine HyperFLINT are public software by Sebastian Mizera, Mathieu Giroux and Giulio Salvatori (arXiv:2604.20954) for computing Feynman-type parametric integrals symbolically. For an integrand that is a product of powers of polynomials over positive variables, they return the exact coefficients of the expansion in the dimensional regulator $\varepsilon$. BootLoops runs HyperFLINT through an unofficial Julia port of the authors' front end SubTropica.wl; the port needs no Mathematica.

Where it comes from

SubTropica is a Wolfram Language (Mathematica) package by Giroux, Mizera and Salvatori, and HyperFLINT is their C++ reimplementation of Erik Panzer's HyperInt. The BootLoops package of the same name is a Julia translation of their front end SubTropica.wl, with a reducibility screen transliterated from HyperInt. The port was written by Claude, and each translated file cites the lines it follows. The engine is not in the package: the user builds it from the authors' repository.

Part of the portSourceAuthors
Translated routines: the tropical analysis (src/tropical.jl), the subtraction terms (src/subtract.jl), the continuation (src/continue.jl) and the dictionary of engine output tokens (src/hlogexpr.jl)SubTropica.wlGiroux, Mizera and Salvatori
Translated routines: the reducibility screen (src/lr_refine.jl) and its testHyperInt.mpl, with two routines of SubTropica.wlErik Panzer; Giroux, Mizera and Salvatori
Code that follows theirs: the polytope layer, the $\varepsilon$-expansion, the assembly, the driver for divergent integrals and the conventions of graph_to_quadrupleSubTropica.wlGiroux, Mizera and Salvatori
Code that follows theirs: two fixture integrands, and the engine interface (request format, error classes, saved integration order)SubTropica.wl, PaperChecks.wl, and the HyperFLINT test files and command-line sourcesGiroux, Mizera and Salvatori; Mizera and SubTropica contributors (HyperFLINT sources)
Included under reference/: SubTropica.wl, the HyperFLINT README, and two HyperFLINT source files changed in comments onlyThe authors' repositoryThe same authors
New code: the builder of $\mathcal U$ and $\mathcal F$ from a graph, the fibration scripts, the verification module, the tests and the self-testFormulas of arXiv:2604.20954 for the fibration scriptsCode by Claude

Please cite the authors' papers when you use it. The port is unofficial and is not affiliated with or endorsed by the SubTropica and HyperFLINT authors.

What it does

After Feynman parametrization a loop integral becomes an integral over $[0,\infty)^n$ of a product of polynomial powers; for a graph the polynomials are the Symanzik polynomials $\mathcal U$ and $\mathcal F$. SubTropica's input is this "Euler integrand",

$$ I(\varepsilon)= c(\varepsilon)\int_0^\infty d^n x\,\prod_i x_i^{\nu_i(\varepsilon)}\prod_j P_j(x,s)^{a_j+b_j\varepsilon}, $$

with exponents linear in $\varepsilon$ and every polynomial coefficient positive, which restricts the kinematic invariants $s$ to the Euclidean region.

The driver subtropica_integrate works in four steps.

The result is a Laurent series in $\varepsilon$ with exact symbolic coefficients, plus a record of the integration order used and the engine version. The coefficients are rational combinations of multiple zeta values and, when kinematic variables are present, logarithms and polylogarithms of them, with nothing fitted numerically.

The three ray classes of the first step are handled as follows:

A separate screen, lr_refine (the functions refine_letters and blocking_certificate), uses exact polynomial algebra and makes no engine calls. It takes the polynomials and a "blocking" letter from a failed search. It decides whether that letter is certified spurious (an artifact of the search path) or survives the sharper compatibility-graph bound of Brown and Panzer.

The port has these limits:

Examples

Run the self-tests. With the package set up (see Requirements), run from the package directory tools/subtropica/ in the BootLoops repository:

python3 selftest.py

The self-test has three stages.

Exit code 0 means R and F passed and E passed or was skipped for that reason.

A five-variable integral. The package includes a convergent five-variable example of Smirnov's as fixtures/smirnov_tst2_5var.json (the integrand only; fixture files hold no result values). With scripts/env.sh sourced and the Julia project active:

using SubTropica
E = euler_integrand("fixtures/smirnov_tst2_5var.json")
L = subtropica_integrate(E; order=0)
SubTropica.canonical_text(L.coeffs[1])

All rays are convergent here, and the integration order is saved under ./subtropica_runs/. L is a LaurentSeries{HlogExpr} with L.minorder == 0, and L.evidence["lr_order"] holds the order used. Its first coefficient is $1-\tfrac45\zeta(2)^2+\zeta(3)=1-2\zeta(4)+\zeta(3)$, printed with the engine's names mzv_2, mzv_3 for $\zeta(2)$, $\zeta(3)$. order=2 also returns the $\varepsilon^1$ and $\varepsilon^2$ coefficients.

A single integration step can also be called directly, as test/test_bridge.jl does with cfg = SubTropica.HFConfig(). The call SubTropica.hf_integrate("Log[1+x]/(x*(1+x))", [:x], [:x]; cfg=cfg) followed by SubTropica.resolve_periods(terms; cfg=cfg) gives mzv_2, and the integrand "1/((1+x)*(2+x))" gives Log2.

Deciding whether a blocking letter is real. Panzer's HyperInt paper (arXiv:1403.3385, Example 4.2) reduces the pair $\{(1+x)^2+y,\;y+z^2\}$ with $z$ a parameter. test/test_lr_refine.jl reproduces it without the engine (the test reaches the functions through a module alias; with using SubTropica they are exported):

using SubTropica, Nemo
R, (x, y, z) = polynomial_ring(QQ, [:x, :y, :z])
polys = [(1 + x)^2 + y, y + z^2]
vars = [:x, :y]                                    # z = kinematic
cert, removed, log = refine_letters(polys, vars, [:y, :x])
c = blocking_certificate(polys, vars, x + 1 + z)

log["order_walkable"] is true. log["stages"] lists the letters $\{x+1,\,x+1+z,\,x+1-z\}$ after integrating $y$ and $\{1+z,\,z-1\}$ after both variables, as published. removed is empty because the naive and refined bounds agree here. With the order [:x, :y] instead, order_walkable is false, since the starting set is not linear in $x$.

c["status"] is "SURVIVES" and c["real"] is true: the letter lies in the refined bound and cannot be certified spurious. A letter present in the naive bound but absent from every refined stage comes back "SPURIOUS_REMOVED", a proof that it cannot block the integration. is_blocking_real(polys, vars, letter) returns only the boolean.

Routines

CommandWhat it does
scripts/env.shEnvironment template (SUBTROPICA_HF_BIN, SUBTROPICA_MZV_DATA, SUBTROPICA_RUNS, the optional table checksum SUBTROPICA_MZV_SHA256, HF_PERIOD_TUPLES=0); edit the paths for your install
scripts/make_fixtures.py [--synthetic-only] [--dps N] [--oracle FIXTURE_JSON --out DIR]Regenerates the fixtures, or writes a quadrature reference evaluation
scripts/fibrate/fibrate.py WORDLIST.json [--out OUT.json] [--dps 130] [--validation-points 2/5 3/8], or --selfcheckRewrites regularized words with parameter-dependent letters as $G(\ldots;z)$ times constants; every word is validated numerically at two points

fibrate.py exits with code 2 on any failure; its Python interface is described in scripts/fibrate/README.md. The Julia module is loaded with using SubTropica.

FunctionWhat it returns
subtropica_integrate(E; order, allow_continuation, strict_periods, run_dir)A LaurentSeries{HlogExpr}, by the four steps above; a second method takes a two-regulator Euler2Integrand with aux_order
euler_integrand(prefactor, polys, nu, vars; kinvars), euler_integrand(path)The input, built from polynomials or from a subtropica-euler-quad-v1 JSON file
graph_to_quadruple(edges, nodes, masses, kinematics; nu, D)The EulerIntegrand of a graph with its $\Gamma$-function prefactor in D − 2ε dimensions; nu[e]=0 pinches an edge; numerators are refused
symanzik_UF(edges, nodes, masses, kinematics)$\mathcal U,\mathcal F$ by spanning trees and 2-forests, cross-checked against a Laplacian determinant
HFConfig(; bin, mzv_data_path, timeout_s, transport, cabi_lib)Engine location and limits; defaults read SUBTROPICA_HF_BIN, SUBTROPICA_MZV_DATA, SUBTROPICA_HF_TRANSPORT, SUBTROPICA_HF_CABI_LIB
refine_letters(polys, vars, order)The refined letter bound along an order: certified letters, letters removed as spurious, and a log for each stage
blocking_certificate(polys, vars, letter), is_blocking_real(polys, vars, letter)The verdict for one letter (SURVIVES, SPURIOUS_REMOVED, NOT_IN_BOUND), or only the boolean; square-root letters raise LRRefineRefusal
eval_symbolic(L, point; dps)The value of a symbolic series at an exact rational point, to dps digits
compare_laurent, verify_fixture, verify_laurent(L, artifact_path)The number of matching digits at each order against a stored reference evaluation, rounded down; divergent fixtures are refused

The other exports, among them the order search (find_lr_order, ensure_lr_order) and the JSON readers and writers, are listed in src/SubTropica.jl. Functions written with the module prefix, such as SubTropica.hf_integrate, are not exported.

Requirements

Source and references

The code is tools/subtropica/ in the BootLoops repository. The package NOTICE reproduces the authors' own notice, and the credits page lists the sources.

ReferenceWhat it supplies
M. Giroux, S. Mizera and G. Salvatori, "SubTropica", arXiv:2604.20954; code: github.com/SubTropica/SubTropicaThe method, SubTropica.wl and the HyperFLINT engine
E. Panzer, HyperInt, Comput. Phys. Commun. 188 (2015) 148, arXiv:1403.3385; code: HyperIntThe integration algorithms that HyperFLINT reimplements; the compatibility-graph reduction procedures of the screen; Example 4.2
F. Brown, arXiv:0804.1660, arXiv:0910.0114The theory of hyperlogarithm integration and linear reducibility

← back to the tools index