Holonomic
Holonomic is a short Python driver for ore_algebra, public SageMath software by Manuel Kauers, Maximilian Jaroschek and Fredrik Johansson, whose certified numerical module, ore_algebra.analytic, is by Marc Mezzarobba. Given a linear differential equation with polynomial coefficients and the value and derivatives of a solution at one point, ore_algebra computes the solution at another point as an interval proven to contain the true answer. BootLoops uses it unmodified to check its own differential-equation solvers against a rigorous program by other authors.
What it does
A function $f(x)$ is holonomicalso called D-finite: it satisfies a linear ordinary differential equation whose coefficients are polynomials in x; logarithms, hypergeometric functions, and Feynman integrals as functions of a kinematic variable are all holonomic when an operator $L = p_r(x)\,\partial_x^{\,r} + \dots + p_0(x)$ with polynomial coefficients gives $Lf=0$. Such a function is fixed by $L$ and the $r$ numbers $f(x_0), \dots, f^{(r-1)}(x_0)$ at a base point.
The computation is ore_algebra's numerical_transition_matrix. Its input is $L$, a list of exact points $x_0, \dots, x_n$ (rationals or Gaussian rationals) and a tolerance. It returns the $r\times r$ matrix that carries the data at $x_0$ to $x_n$ along the segments through those points. Every entry is a balla midpoint and a radius such that the exact value is guaranteed to lie within the radius of the midpoint; computed here in Arb interval arithmetic (Arb).
The endpoint may be a regular singular point of $L$, a zero of $p_r$ where solutions behave like fractional powers and logarithms. The matrix then gives coordinates in ore_algebra's local basis of series solutions there. This is how the coefficient of, say, $x^{3/2}$ around a threshold is read off.
BootLoops adds a short Python driver, a self-test, a script that runs a transport described in a JSON file against reference values, and scripts that copy the SageMath environment to another machine. The driver holonomic_transport.py wraps the call to ore_algebra (the engine, below) in one function, certified_transport, which works in these steps:
- Convention. It finds out whether the matrix expects plain derivatives $(f, f', f'')$ or Taylor coefficients $(f, f', f''/2!)$, by transporting $u^2$ under $\partial_u^{\,3}$. It probes this on every call that does not pass
conv, instead of assuming it. - Path. If a real root of $p_r$ lies on the segment, it routes through the complex midpoint $(x_0+x_1)/2 + i/8$.
- Transport. It calls the engine, applies the matrix to the data, and flags a result whose radius exceeds $10^{-6}$ of its midpoint.
- Value. It returns a real ball when the imaginary part is exactly zero and a complex ball otherwise. A continuation that detoured around a real singular point is genuinely complex, and the imaginary part is kept.
Two facts about the environment are built in: ore_algebra is imported after sage.all (the other order fails), and the engine is always called with algorithm='naive', its pure-Python summation. In the SageMath 10.7 / ore_algebra 0.5 build BootLoops runs, the compiled extension does not load and the default algorithm stops with a TypeError. The naive path prints a "Cython extensions not found" warning and returns correct certified results.
The tool has these limits:
- The guarantee is for the continuation only. A wrong operator or wrong data at $x_0$ gives a tight ball around the wrong number, so check the data at $x_0$ against a separate evaluation first.
- A ball can be correct and useless. At high order, on a path passing close to a singular point, the radius can exceed the midpoint by many orders of magnitude. Give the path more clearance or end exactly on the singular point.
- Always read the radius that comes back. At the singular endpoints in the examples below it came back 10 to 24 digits wider than the tolerance.
- The naive path is slow at high order. On an ordinary path at tolerance $10^{-40}$ on one core, test operators of order 6, 24, 48 and 72 took 0.02 s, 2.5 s, 96 s and about 22 minutes, all under 400 MB.
Use this tool to certify a handful of values. To transport a system to thousands of points use Wayfinder or Baller, and compare a few of their values with Holonomic.
Examples
The self-test. The package directory is tools/holonomic/, and the SageMath setup is under Requirements. From the repository root:
python3 tools/holonomic/battery.py
The first test needs no SageMath: it checks the recorded enclosures of the worked example (reference/ln32_reference.json) against $\ln(3/2)$ recomputed in Python integer arithmetic. The second runs smoke_test.py under sage -python, and is skipped, with the reason printed, when SageMath or ore_algebra is not found. Each test prints PASS, FAIL or SKIP.
The smoke test alone. With SE set to the root of a SageMath environment that has ore_algebra installed, from tools/holonomic/:
$SE/bin/sage -python smoke_test.py
Six checks print one line each; a passing run includes
[S1] sage 10.7 / ore_algebra 0.5 [S2] IC convention (determined, this session): taylor [S3] transport(ln(1+x), [0,1/2]) = [0.40546510810816438197801311546434913657199 +/- 3.93e-42] contains ln(3/2)=True rad=2.87e-42 PASS [S4] root-on-segment detour: roots=[0.500000000000000] path_len=3 PASS
then SMOKE PASS and the record path. S3 is the worked example below. S5 records that the default algorithm raises the TypeError, or reports ENV-FACT-CHANGED if it now works. S6 continues $\ln(1+x)$ from $0$ to $-3/2$ past the singular point $x=-1$, and the result must be a complex ball containing $\ln(1/2)+i\pi$.
One transport from Python. The operator $(1+x)\partial_x^2+\partial_x$ annihilates $\ln(1+x)$, and the data at $0$ is $(0,1)$. In a script run under sage -python:
from sage.all import QQ, PolynomialRing, RealBallField from ore_algebra import OreAlgebra import holonomic_transport as H Rx = PolynomialRing(QQ, "x"); x = Rx.gen() A = OreAlgebra(Rx, "Dx"); Dx = A.gen() RBF = RealBallField(430) L = (1 + x)*Dx**2 + Dx # annihilates ln(1+x) res = H.certified_transport(L, QQ(0), QQ(1)/2, [RBF(0), RBF(1)], eps=1e-40) res["value"] # ball containing ln(3/2), certified radius ~3e-42
res["value"] is $f(1/2)$ as a ball, and res["vector"] holds all transported entries. path, detoured and roots_on_path record the points used and any detour, and conv the convention found. enclosure_ok is False when the result was flagged as too wide. Pass exact rationals (QQ) for the endpoints and balls (RBF) for the data.
A transport described in a spec file. Under the environment's own Python:
$SE/bin/python3.11 ore_transport_oracle.py --smoke-toy $SE/bin/python3.11 ore_transport_oracle.py --spec specs/spec2_k3_row31_path_of_record.json --out k3.json
--smoke-toy runs two small transports with known answers: $\cos x$ from $0$ to $1$, and $x^{1/2}$ under $x\partial_x - \tfrac12$ onto the singular point $0$. OVERALL: PASS prints within seconds.
The second call reads the included spec for the three-loop banana integral with masses squared $(1,1,1,9)$. It builds the order-4 Picard–Fuchs operator (the differential operator that annihilates the period of the integral) in $s=-1/z$. It seeds the period at $s=80$ from its exact series, with a proven bound on the dropped tail in the radius. It transports along $80 \to 80+10i \to \tfrac14+10i \to \tfrac14 \to 0$ at eps $=10^{-100}$ and reads the coefficient of $s^{3/2}$ at the threshold.
The script compares that coefficient with the 195-digit reference value of $c_{3/2} = -\sqrt{3}/(36\pi)$ stored in the spec. For each reference value it prints the certified agreement, the smaller of the digits of agreement on the midpoint and the radius in digits, then PASS or FAIL against min_digits. k3.json gets the full record and must not already exist.
Expect about 7 s and 90 certified digits here, about 35 s and 76 digits for the order-6 Calabi–Yau spec. Adding --planted-target 3/2 corrupts the 25th digit of the stored reference; the run must then fail and name that value.
Routines
The scripts are in tools/holonomic/.
| Command | What it does |
|---|---|
battery.py [--full] [--legs reference,smoke,ladder6] [--receipts DIR] | The self-test, under plain python3. Writes holonomic_SUMMARY.json; --receipts sets where the smoke record goes |
smoke_test.py [FILE] | The six-check smoke test, under sage -python. Writes a JSON record to FILE (default smoke_receipt.json) |
ore_transport_oracle.py --spec SPEC.json [--out FILE], or --smoke-toy | Runs the transport described in the spec and compares it with the reference values |
relocate_sageenv.sh SRC_ENV DEST_DIR HOLONOMIC_DIR [OUT] | Copies the environment to DEST_DIR/sageenv, tests the copy and prints RELOCATION_VERDICT PASS only if both tests succeed |
smoke_relocated_env.py, verify_bit_identity.py | The two tests of the copy: versions and one small matrix (SMOKE_OK), and a fixed transport whose VERIFY_SHA256 must match the original |
ladder/rank_ladder.py | The cost benchmark, under sage -python, one order per process, set by RL_RANK, RL_STAGES and RL_OUT in the environment |
ladder/fit_ladder.py | A power-law fit of the benchmark's ladder_R*.json outputs, with extrapolation to the orders given by --extrapolate |
ore_transport_oracle.py also accepts --eps, --prec, --min-digits, --planted-target, --holonomic-dir and --compare-tool. The spec keys are operator (coefficient lists in $\theta_z = z\partial_z$ or plain $\partial_s$), variable, seed (explicit or bfkns_multinomial), path, landing (regular_point or local_basis), targets, eps, prec and min_digits. Each key and each exit status is documented in the script's header. specs/ holds two examples: the K3 banana $(1,1,1,9)$ of the spec example above, and the Calabi–Yau threefold banana $(1,1,1,1,16)$, which is the four-loop banana.
HOLONOMIC_DIR is the directory holding holonomic_transport.py, and OUT an optional output JSON. relocate_sageenv.sh fixes the interpreter lines inside the copy and runs the two tests with the copy's own versioned bin/python3.X (SAGEENV_PYBIN overrides the name). Run alone, the two test scripts read HOLONOMIC_DIR from the environment, and smoke_relocated_env.py also reads HOLONOMIC_SAGEENV.
The driver holonomic_transport.py is imported under SageMath's Python.
| Function | What it returns |
|---|---|
certified_transport(L, u0, u1, ics_der, eps, prec, conv) | All four steps in one call; returns the dictionary described in the Python example |
determine_ic_convention(eps, prec) | "taylor" or "derivatives" for the running engine; raises if neither fits |
plan_path(L, u0, u1, clearance, detour_imag) | (path, roots_on_path), with the complex detour when a real root of the leading coefficient lies within clearance of the segment |
enclosure_too_wide(ball, rel) | True when the radius exceeds rel times $\max(\lvert\mathrm{mid}\rvert, 1)$ |
dyadic_point(x, bits) | The nearest $k/2^n$, $n$ = bits, as an exact rational; exact in double precision too |
engine_versions() | The running SageMath and ore_algebra versions, to record with every result |
The lower-level functions ic_vector, transition_matrix and mat_vec are in holonomic_transport.py.
Requirements
- Runs on: SageMath with ore_algebra installed into it. BootLoops runs SageMath 10.7, ore_algebra 0.5 and Python 3.11.
- Install:
sage -pip install ore_algebra. No script installs anything into the SageMath environment. - Other builds: the smoke test records a different build rather than failing, while the spec-driven script and the test of a copied environment refuse one.
- Python: the engine has no plain-Python route. Every script that calls it imports
sage.allbeforeore_algebra. - Self-test:
python3 tools/holonomic/battery.pyfrom the repository root. The exit status is 0 when no test failed.--fulladds the order-6 case of the cost benchmark with its round-trip and known-solution checks.HOLONOMIC_SAGEnames thesageexecutable if it is not onPATH. - Spec-driven script: it also needs mpmath (included with SageMath) and
compare_amflow_json.pyfromtools/amflow-kit/(see AMFlow). That file is looked for in the sibling folder by default, or given with--compare-toolorCOMPARE_AMFLOW_JSON.
Source and references
The code is tools/holonomic/ in the BootLoops repository, released under the MIT license. Please cite the papers of the ore_algebra authors, listed below, when you use it.
| Reference | What it supplies |
|---|---|
| M. Kauers, M. Jaroschek and F. Johansson, Ore Polynomials in Sage, arXiv:1306.4263; code: github.com/mkauers/ore_algebra | ore_algebra, the engine |
| M. Mezzarobba, Rigorous Multiple-Precision Evaluation of D-Finite Functions in SageMath, arXiv:1607.01967 | ore_algebra.analytic, the certified continuation behind numerical_transition_matrix |
| F. Johansson, Arb, IEEE Trans. Comput. 66 (2017) 1281, arXiv:1611.02831 | The ball arithmetic under the engine (see Arb) |
| The Sage Developers, SageMath | The computer algebra system the engine runs in |