Vopclose

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

Vopclose solves the differential equations of a family of Feynman integrals along a one-dimensional path and returns explicit functions of the path variable, order by order in the dimensional regulator $\epsilon$, rather than numbers at one point. You give it the exact connection matrices (rational functions of the path variable $t$), the block structure of the system, the numerical values of the integrals at $t=0$ and the range of orders you want. For every integral and order it returns a closed form built from constants, square roots of polynomials, rational functions and iterated integrals, together with an exact symbolic check that the closed form satisfies its equation. A built-in evaluator computes the closed forms to high precision at the endpoint $t=1$, or at any other point of its integration contour, for comparison with independent reference values.

What it does

Write the master integrals of a family, expanded as $y_i=\sum_k y_{i,k}\,\epsilon^k$, along a path $t\in[0,1]$ in the kinematic variables. Their differential equation takes the graded form

$$y'_{i,k}(t)=\sum_{j,m}A^{(m)}_{ij}(t)\,y_{j,k-m}(t),$$

with every $A^{(m)}_{ij}$ an exact rational function of $t$ and $m\ge 0$ the number of orders a coupling reaches down. Order $k$ of an integral is driven only by lower orders, already known when it is reached, and by the $m=0$ couplings inside its own diagonal block. The system is therefore solved one order at a time and, within an order, block by block in dependency order. Two common shortcuts may both be unavailable. A basis change that makes the matrix proportional to $\epsilon$ (see Canonify) does not exist globally when a block's homogeneous solutions contain square roots, that is, when the local exponentsthe powers $(t-t_0)^\lambda$ with which solutions start at a singular point $t_0$; a half-integer $\lambda$ means a square-root branch at some singular point are half-integers. Recognizing endpoint numbers as combinations of known constants with PSLQ fails when one order mixes functions of different transcendental weight. Vopclose is meant for that situation. It solves each block by variation of parameterssolve the homogeneous equation $M'=A_0M$ first; the solution with source $S$ is then $Y=M\,(Y(0)+\int_0^t M^{-1}S)$, finding the homogeneous basis exactly and doing the integral exactly in a closed algebra of functions.

Every function in that algebra is a finite sum of terms $C\cdot\sqrt{\ell_1\cdots\ell_r}\cdot R(t)\cdot G_w(t)$: a named constant, the square root of a product of polynomial "letters", a rational function with exact rational coefficients, and an iterated integral from $0$ to $t$. The kernels of the iterated integrals are $\mathrm{d}\log$ of a letter, a rational function with an irreducible denominator, or such a function times a square root. The set is closed under addition, multiplication by rational functions and square roots, differentiation, and integration from $0$. Integrating a rational factor uses Hermite reductionan exact algorithm that splits a rational function into the derivative of another rational function plus terms with simple poles only; whatever remains after the rational part and the $\mathrm{d}\log$ terms is registered as a new kernel, so nothing is approximated. Homogeneous solutions are found as rational vectors, or as $\sqrt{\ell}$ times a rational vector for letters with half-integer exponents, and every column is verified exactly before use. A block with a complete basis is solved directly (strategy FULL); otherwise it is conjugated by the square root (CONJ) or triangularized with the verified columns (TRI), and the remaining smaller block is treated the same way. Afterwards certify() differentiates each closed form symbolically, subtracts the right-hand side and confirms that every coefficient of the difference is identically zero. That part of the output is exact.

Two parts are numerical. The boundary values at $t=0$ enter as numbers; each is recognized as a rational number if possible, then as a small-coefficient combination of $1$, $\log p$ over a short prime list and $i\pi$, and otherwise kept as a named constant carrying its value. Only small numerators and denominators are accepted, because searches over many primes at around a hundred input digits produce false matches. For evaluation, the Engine class places Chebyshev nodes on a contour from $0$ to $1$, accumulates the iterated integrals in ball arithmetic (Arb through python-flint) and continues the square roots along the same contour. The contour lifts into the upper half plane around the real poles you list and around the zeros of $\det M$ inside $(0,1)$, where $M^{-1}S$ has a pole that cancels only in the product $M\int M^{-1}S$. Integrating straight through such a point gives wrong numbers although the solution is finite there, so engine() finds these zeros and adds the detours itself. The values are high-precision numbers without a proven error bound. The intended final check compares them at the endpoint with reference values from an independent method (for example AMFlow) that played no part in the construction, and reports digits of agreement per integral and order.

Limits. One path variable, one path per run. Connection entries must be exact; from exact samples at rational points exact_entry_from_samples reconstructs an entry through Ratfit, and an entry that cannot be reconstructed exactly is outside the method. With symbolic boundary constants (boundary_mode='tag') the number of terms grows by roughly a factor of ten per order, so for deep ranges set scope_rows to the integrals you need; the last order is then solved only on the blocks they depend on.

Examples

Run the self-test. From the repository root:

python3 tools/vopclose/vopclose.py --test

Fourteen checks run in about a second at 60 working digits: exact differentiate-after-integrate round trips, Hermite reduction with repeated and irreducible factors, square roots of linear and quartic letters, an algebraic kernel, a branch continued through a detour, and detection of a $\det M$ zero at $t=1/2$. Checks 9 to 13 solve the small system of the next example, and check 14 is the reconstruction shown in the third. The run ends with

  [PASS] T11 exact DE certification 6/6 zero-remainder
  [PASS] T12 held-out endpoint gate 6/6 >=40d (worst 60.1d)
  [PASS] T13 boundary PSLQ closed all 3 boundaries rational
  [PASS] T14 ratfit delegation (blind + known-Q) exact
vopclose selftest: 14/14 PASS (0.7s)

and exit status 0; a failed check gives exit status 1. Without --test the script prints its documentation string.

Solve a small graded system from start to finish. Three integrals, orders $k=0,1$. Integral 0 is a block by itself with $A_{00}=1/(t+2)$ at $m=0$ and $m=1$. Integrals 1 and 2 form a block with $1/(2(t+3))$ on the diagonal, so their homogeneous solutions carry $\sqrt{t+3}$, plus an off-diagonal $1/(t+1)$ and a coupling of integral 2 to integral 0 one order down. These are the self-test's own lines, with tools/vopclose/ on the Python path; fp takes coefficients from low to high degree, so [2, 1] is $2+t$, and the keys of RatA are (i, j, m).

import mpmath as mp
from vopclose import Rat, fp, ONE_P, R_ONE, VopConfig, VopClosure, reset_registries

mp.mp.dps = 60
reset_registries()
Rr = lambda n, d=None: Rat(fp(n), fp(d) if d is not None else ONE_P)
RatA = {(0, 0, 0): Rr([1], [2, 1]),          # 1/(t+2)
        (0, 0, 1): Rr([1], [2, 1]),
        (1, 1, 0): Rr([1], [6, 2]),          # 1/(2(t+3)) — indicial 1/2
        (1, 2, 0): Rr([1], [1, 1]),          # 1/(t+1)
        (2, 2, 0): Rr([1], [6, 2]),
        (2, 0, 1): R_ONE}
cfg = VopConfig(RatA=RatA, blocks={0: [0], 1: [1, 2]},
                boundary_vals={(0, 0): mp.mpc(1), (1, 0): mp.mpc(1), (2, 0): mp.mpc(2)},
                kmin=0, kmax=1, top_rows=(0, 1, 2), NC=96)
vc = VopClosure(cfg)
NCF = vc.close()
st1 = vc.block_strategy(1)
cert = vc.certify()

NCF maps each (integral, order) to its closed form, a dictionary from (constant tag, letters under the root, kernel word) to the exact rational prefactor; six entries are nonzero here. st1[0] is 'CONJ' and st1[2][0] is 'TRI': the radical block was conjugated by $\sqrt{t+3}$ and the rest triangularized. cert[(i, k)] is (True, 0) for all six (no nonzero remainder term), and vc.boundary_record shows all three boundary values recognized as exact rationals. To compare with independent values at $t=1$, written by hand and one by direct quadrature:

w1 = mp.sqrt(mp.mpf(4) / 3)
refs = {(0, 0): mp.mpc(3) / 2,
        (0, 1): mp.mpc(3) / 2 * mp.log(mp.mpf(3) / 2),
        (1, 0): w1 * (1 + 2 * mp.log(2)),
        (2, 0): 2 * w1,
        (2, 1): mp.mpc(4) / 3}
refs[(1, 1)] = w1 * mp.quad(
    lambda s: mp.sqrt(3 / (s + 3)) * ((s + 3) ** 2 / 3 - (s + 3)) / (s + 1), [0, 1])
g = vc.gate(refs)
worst = min(g.values())

g[(i, k)] is the number of digits to which the evaluated closed form agrees with the reference, relative to its size (75.0 stands for exact agreement); the self-test requires the worst of the six above 40, and the run above gave 60.1. vc.engine().eval_cf(NCF[(0, 1)], z) evaluates one closed form at a point z on the contour, eval_cf_end at $t=1$.

Reconstruct an exact connection entry from samples. The self-test recovers $(1+3t)/(2+t^2)$ from its exact values at $t=k/37$, once blind and once with the denominator supplied (continuing the session above):

from fractions import Fraction
from vopclose import exact_entry_from_samples, fq

tgt = Rr([1, 3], [2, 0, 1])                  # (1+3t)/(2+t^2)
xs = [Fraction(k, 37) for k in range(1, 25)]
ys = [Fraction(int(tgt.n(fq(x)).p), int(tgt.n(fq(x)).q))
      / Fraction(int(tgt.d(fq(x)).p), int(tgt.d(fq(x)).q)) for x in xs]
Rb, okb, _ = exact_entry_from_samples(xs, ys)
Rk, okk, _ = exact_entry_from_samples(xs, ys, Qknown=fp([2, 0, 1]))

Each call returns (Rat, ok, degree); ok is True only when the n_loo samples kept out of the fit were reproduced exactly, and both Rb and Rk compare equal to tgt.

Routines

Command line

Driving a solve

Homogeneous solutions and block strategies

Exact function algebra

Evaluation and constants

Used on this site

Requirements and source

Python 3 with mpmath and python-flint. exact_entry_from_samples and the last self-test check import Ratfit from the neighboring tools/ratfit/ directory, found automatically when the two sit side by side as in the repository; there is no install step. Self-test: python3 tools/vopclose/vopclose.py --test. Source: tools/vopclose/ in BootLoops' bootloops-dev repository (GitHub organization BootLoops-ai), released under the MIT license (one file, vopclose.py, plus GUIDE.md); the scripts that applied it to particular integral families are not part of the package, and the two result pages above host their own evaluators. Related pages: Ratfit, Canonify, Arb and mpmath, PSLQ and LLL.

← back to the tools index