Holonomic

The content on this page was written by AI under human supervision.

Holonomic takes a function that satisfies a linear differential equation with polynomial coefficients, plus its value and derivatives at one point, and computes its value at another point as an interval proven to contain the true answer. The computation is done by ore_algebra, public SageMath software by Manuel Kauers, Maximilian Jaroschek and Fredrik Johansson whose certified numerical module, ore_algebra.analytic, is by Marc Mezzarobba. BootLoops uses it unmodified as a rigorous check on its own differential-equation solvers, one that shares no code with them. What BootLoops adds is 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.

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. Given $L$, a list of exact points $x_0, \dots, x_n$ (rationals or Gaussian rationals) and a tolerance, ore_algebra's numerical_transition_matrix 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, which is how the coefficient of, say, $x^{3/2}$ around a threshold is read off.

The guarantee covers 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 an independent evaluation first. A ball can also be correct and useless: at high order, on a path passing close to a singular point, the radius can dwarf the midpoint by many orders of magnitude. Give the path more clearance or end exactly on the singular point, and 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 driver holonomic_transport.py wraps the engine call. Its certified_transport first 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}$; the driver probes this on every run instead of assuming it. If a real root of $p_r$ lies on the segment it routes through the complex midpoint $(x_0+x_1)/2 + i/8$. It then calls the engine, applies the matrix to the data, and flags a result whose radius exceeds $10^{-6}$ of its midpoint. The value is returned as a real ball when its imaginary part is exactly zero and as a complex ball otherwise: a continuation that detoured around a real singular point is genuinely complex, and the imaginary part is kept. Two environment facts 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 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, which are much faster and share no code with Holonomic, so their agreement with it at a few points is an independent confirmation.

Examples

The self-test. From the repository root:

python3 tools/holonomic/battery.py

The first test needs no SageMath: it recomputes $\ln(3/2)$ in pure Python integer arithmetic with a rigorous error bound and checks that the recorded enclosures of the worked example (reference/ln32_reference.json) contain it and are internally consistent. The second runs smoke_test.py under sage -python; it is skipped, with the reason printed, when SageMath or ore_algebra is not found (HOLONOMIC_SAGE names the sage executable if it is not on PATH). --full adds the order-6 rung of the cost benchmark with its round-trip and known-solution checks. Each test prints PASS, FAIL or SKIP with its time, a holonomic_SUMMARY.json is written to the working directory, and the exit status is 0 when no test failed. To run 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, the elapsed time and the record path. S3 is the worked example below: $(1+x)\partial_x^2+\partial_x$ annihilates $\ln(1+x)$, the data at $0$ is $(0,1)$, and the ball at $x=1/2$ must contain $\ln(3/2)$ with radius below $10^{-38}$. S4 checks the detour rule and S5 records that the default algorithm raises the TypeError (or reports ENV-FACT-CHANGED if it now works). S6 transports $\ln(1+x)$ from $0$ to $-3/2$: the singular point $x=-1$ lies on the segment, so the path detours through the upper half-plane and the result must be a complex ball containing $\ln(1/2)+i\pi$ with radius below $10^{-38}$. A JSON record is also written, to the file named by the optional first argument; exit status is 0 on a pass.

One transport from Python. The same computation through the driver, in a script run with $SE/bin/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 real ball (a complex ball when a detoured continuation is genuinely complex) and res["vector"] holds all transported entries; path, detoured and roots_on_path record the points used and any detour, conv the convention found, and enclosure_ok is False when the radius swamps the midpoint. 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 transports $\cos x$ under $\partial_x^2+1$ from $0$ to $1$ and checks that the ball contains $\cos 1$. It then transports $x^{1/2}$ under $x\partial_x - \tfrac12$ onto the singular point $0$ and checks that its coefficient on the local basis element $x^{1/2}$ is $1$; 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 in $s=-1/z$ and seeds the period at $s=80$ from its exact series (a proven bound on the dropped tail goes into the radius). It then transports along $80 \to 80+10i \to \tfrac14+10i \to \tfrac14 \to 0$ at eps $=10^{-100}$, reads the coefficient of $s^{3/2}$ at the threshold, and compares it 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 digits of agreement on the midpoint, the radius in digits, and the certified agreement (the smaller of the two), 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

Driver (holonomic_transport.py, imported under SageMath's Python)

Scripts

Used on this site

Requirements and source

SageMath with ore_algebra installed into it (sage -pip install ore_algebra). BootLoops runs SageMath 10.7, ore_algebra 0.5 and Python 3.11; the smoke test records a different build rather than failing, while the spec-driven script and the relocation check refuse one. There is no plain-Python route to the engine: every script imports sage.all before ore_algebra. The comparison script also needs mpmath (included with SageMath) and compare_amflow_json.py from tools/amflow-kit/ in BootLoops' bootloops-dev repository under the GitHub organization BootLoops-ai (see AMFlow), looked for in that sibling folder by default or given with --compare-tool or COMPARE_AMFLOW_JSON. No script installs anything into the SageMath environment. Self-tests: python3 tools/holonomic/battery.py from the repository root (--full for the benchmark rung). Source: tools/holonomic/ in the bootloops-dev repository, released under the MIT license. ore_algebra: github.com/mkauers/ore_algebra, GNU GPL; M. Kauers, M. Jaroschek, F. Johansson, Ore Polynomials in Sage, arXiv:1306.4263; M. Mezzarobba, Rigorous Multiple-Precision Evaluation of D-Finite Functions in SageMath, arXiv:1607.01967.

← back to the tools index