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:

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:

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/.

CommandWhat 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-toyRuns 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.pyThe 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.pyThe cost benchmark, under sage -python, one order per process, set by RL_RANK, RL_STAGES and RL_OUT in the environment
ladder/fit_ladder.pyA 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.

FunctionWhat 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

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.

ReferenceWhat it supplies
M. Kauers, M. Jaroschek and F. Johansson, Ore Polynomials in Sage, arXiv:1306.4263; code: github.com/mkauers/ore_algebraore_algebra, the engine
M. Mezzarobba, Rigorous Multiple-Precision Evaluation of D-Finite Functions in SageMath, arXiv:1607.01967ore_algebra.analytic, the certified continuation behind numerical_transition_matrix
F. Johansson, Arb, IEEE Trans. Comput. 66 (2017) 1281, arXiv:1611.02831The ball arithmetic under the engine (see Arb)
The Sage Developers, SageMathThe computer algebra system the engine runs in

← back to the tools index