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 port | Source | Authors |
|---|---|---|
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.wl | Giroux, Mizera and Salvatori |
Translated routines: the reducibility screen (src/lr_refine.jl) and its test | HyperInt.mpl, with two routines of SubTropica.wl | Erik 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_quadruple | SubTropica.wl | Giroux, 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 sources | Giroux, 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 only | The authors' repository | The 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-test | Formulas of arXiv:2604.20954 for the fibration scripts | Code 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.
- Classify. It builds the Newton polytopethe convex hull of the exponent vectors of the monomials of a polynomial; for a product of polynomials, the sum of their polytopes of the polynomials and classifies every raya direction along which the integration variables scale to zero or to infinity together of its normal fan as convergent, logarithmically divergent or power divergent.
- Order. The method needs the integrand to be linearly reduciblethere is an order of the integration variables in which, after each integration, all new singularities are again linear in the next variable. The driver has the engine search for such an order, saves it under a run directory and replays it on later calls.
- Integrate. It expands in $\varepsilon$ and integrates each order of the expansion one variable at a time, keeping every intermediate result as a hyperlogarithman iterated integral whose kernels are dx/(x − letter) for rational "letters"; logarithms and polylogarithms are the simplest cases.
- Reduce. After the last variable the remaining constants are reduced to a fixed basis of multiple zeta valuesthe nested sums ζ(s₁,…,s_k) that appear as the constants of multiloop integrals; ζ(2) = π²/6 and ζ(3) are the first two.
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:
- Convergent. The integrand goes straight to the engine with its divergence check on.
- Logarithmic. The driver subtracts exact counterterms read off the divergent facets and integrates the finite remainders, so pole coefficients come out exactly.
- Power, or a ray that needs a second regulator. The driver stops with a specific exception (
PowerDivergentRefusal,GeometricPropertyViolated) whose message says what to change. Calling again withallow_continuation=truerewrites the integral by Nilsson–Passare analytic continuation into pieces that are at most logarithmically divergent. Each piece is sent back through the same entry point.
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:
- Numerators, physical-region kinematics and integrands with no admissible order are refused with a message; those cases belong to a numerical method.
- When no linearly reducible order exists the driver raises
NoLROrderError. A built-in retry admits quadratic letters, and a coefficient that would depend on the resulting algebraic constants is refused unless you passstrict_periods=false. - With its divergence check off, the engine returns zero on a divergent input. The driver keeps the check on and decides from the response fields instead of the exit code, which is 0 even on failure.
- On an input that is not linearly reducible the engine can return a clean-looking result that drops algebraic branches, and nothing in the response flags this. The package's rule is therefore to run the
lr_refinescreen first and to check every new result to at least 30 digits against a separate numerical evaluation (verify.jlcompares at an exact rational point).
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.
- R checks the authors' reference files included under
reference/against their recorded checksums. - F runs
scripts/fibrate/fibrate.py --selfcheck, the control checks of the fibration script. - E runs the Julia suite only if
SUBTROPICA_HF_BINpoints at a built engine, and otherwise prints a SKIP line naming what is missing.
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
| Command | What it does |
|---|---|
scripts/env.sh | Environment 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 --selfcheck | Rewrites 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.
| Function | What 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
- Runs on: Julia 1.11 with Nemo, Oscar and JSON (pinned in
Project.toml), and Python 3 with mpmath and sympy for the scripts. - Engine: HyperFLINT is not included. Obtain SubTropica and HyperFLINT from the authors' repository, github.com/SubTropica/SubTropica. Build the stand-alone command-line engine (C++17, FLINT 3.4 or newer, OpenMP) following the HyperFLINT README, a copy of which is in
reference/. - Install: instantiate the Julia project in
tools/subtropica/once; the first instantiate compiles Oscar. Then setSUBTROPICA_HF_BINto the engine wrapper andSUBTROPICA_MZV_DATAto its zeta-value reduction table. - Memory: every engine call runs under
ulimit -v 32505856(about 31 GB). Parallel work uses one process per worker, since threads sharing an engine handle crash. - Numerical checks:
eval_symbolicand the zeta-value table check (SubTropica.mzv_provenance_gate, which stops if the table's checksum differs fromSUBTROPICA_MZV_SHA256) evaluate constants and polylogarithms with theginac_gplprogram oftools/gpl-eval/(GPLEval). That program needs g++ and the GiNaC/CLN libraries and is compiled from source there; setSUBTROPICA_GINAC_GPLif it lives elsewhere. - Self-test:
python3 selftest.pyinsidetools/subtropica/ends with a line beginningsubtropica selftest: PASS. - Full suite:
ulimit -v 32505856; julia --project=tools/subtropica tools/subtropica/test/runtests.jl. A few tests needSUBTROPICA_PROBES_DIRorSUBTROPICA_RAYCHECK_DIRand say so when unset. Severaltest/test_*.jlfiles also run stand-alone. - Optional:
deps/build_cabi.shanddeps/verify_cabi.jlbuild and check an in-process engine library (transport=:cabi). It must be built from an engine source tree carrying a patch that is not distributed with the package (seedeps/BUILD.md). The build script stops with a message unlessHF_CABI_WORKandHF_FLINT_PKGCONFIGare set. The command-line transport is the default and the supported route.
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.
| Reference | What it supplies |
|---|---|
| M. Giroux, S. Mizera and G. Salvatori, "SubTropica", arXiv:2604.20954; code: github.com/SubTropica/SubTropica | The method, SubTropica.wl and the HyperFLINT engine |
| E. Panzer, HyperInt, Comput. Phys. Commun. 188 (2015) 148, arXiv:1403.3385; code: HyperInt | The integration algorithms that HyperFLINT reimplements; the compatibility-graph reduction procedures of the screen; Example 4.2 |
| F. Brown, arXiv:0804.1660, arXiv:0910.0114 | The theory of hyperlogarithm integration and linear reducibility |