Vopclose

Vopclose solves the differential equations of a family of Feynman integrals along a one-dimensional path. It returns explicit functions of the path variable, order by order in the dimensional regulator $\epsilon$, instead of numbers at one point. Each function comes with an exact symbolic check that it satisfies its equation, and a built-in evaluator computes it to high precision for comparison with reference values from another method.

What it does

You give Vopclose the exact connection matrices, the block structure of the system, the numerical values of the integrals at $t=0$ and the range of orders you want. The connection matrices are the matrices of the differential equation, with entries rational in the path variable $t$. Vopclose returns a closed form for every integral and order.

Write the master integralsthe finite basis to which every integral of the family reduces 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.

Vopclose is meant for systems where two common shortcuts are both unavailable:

Vopclose 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).$$

Here $C$ is a named constant, the $\ell_a$ are polynomials called letters, $R$ is a rational function with exact rational coefficients, and $G_w$ is an iterated integrala repeated integral along the path; the ordered list of its integrands, the kernels, is called the word from $0$ to $t$. The kernels 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$.

The solution proceeds in four steps:

Two parts are numerical:

The contour passes into the upper half plane around the real poles you list (the field poles) and around the zeros of $\det M$ inside $(0,1)$. Here $M$ is the matrix of homogeneous solutions of a block and $S$ is the source of its equation. At such a zero $M^{-1}S$ has a pole that cancels only in the product $M\int M^{-1}S$. Integrating straight through it 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 is a comparison at the endpoint with reference values from another method (for example AMFlow) that played no part in the construction. The result is the number of digits of agreement per integral and order.

Vopclose has these limits:

Examples

Run the self-test. With mpmath and python-flint installed (see Requirements), run it from the repository root. The package directory is tools/vopclose/.

python3 tools/vopclose/vopclose.py --test

Fourteen checks run at 60 working digits. 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. The system has three integrals and 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}$. The block also has 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 square-root 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.

The reference values at $t=1$ for the comparison are five expressions written by hand and one 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 to be at least 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

The command line has one form, python3 vopclose.py --test, the self-test of the first example. Everything else is called from Python with tools/vopclose/ on the path.

FunctionWhat it returns
VopConfig(RatA, blocks, boundary_vals, kmin, kmax)The description of one system: connection {(i,j,m): Rat}, blocks {id: [rows]}, values at $t=0$ {(i,k): mpc}, range of orders
VopClosure(cfg)The solver for that system
VopClosure.close(){(i,k): closed form} after solving all orders and blocks; log=print gives one line per order
VopClosure.certify(){(i,k): (passed, nonzero remainder terms)} from the exact symbolic check; rows and layers restrict it
VopClosure.engine()The evaluator on a contour that detours the configured poles and the $\det M$ zeros
VopClosure.gate(refs)Digits of agreement with the reference values {(i,k): mpc} at the endpoint, or at z if given
VopClosure.block_strategy(s)The strategy for block s, which starts with 'FULL', 'CONJ' or 'TRI'
VopClosure.boundary_recordPer (i,k): exact <fraction>, logring {...} or tagged <value>
exact_entry_from_samples(xs, ys, Qknown=None, n_loo=6)(Rat, ok, degree): one connection entry as an exact Rat from exact samples, through Ratfit
solve_rat_solutions(Ain, extra_rad=None)All exact rational solution vectors of $Y'=AY$; with extra_rad, the rational $v$ such that $\sqrt{\prod\ell}\,v$ solves it
Rat(n, d=None), fq(x), fp(coeffs)An exact rational function of $t$; an exact rational number; an exact polynomial
reset_registries()Nothing; it clears the registered letters, kernels and constants, and is called between separate solves

VopConfig also takes the optional fields L, closed_sources, top_rows, scope_rows, poles, NC, boundary_mode and log_primes. Its docstring in vopclose.py describes each one.

solve_rat_solutions can be used on its own, and it also finds logarithmic solutions. Applied to the enlarged matrix $[[A,\;G\,\mathrm{d}\log f],[0,\;0]]$ with $G$ a known rational solution, it finds the solutions of $Y'=AY$ of the form $Q+u\,G\log f$.

The lower-level functions are defined in the same file. They are the closed-form algebra (the cf_ functions and hermite), the block strategies (find_solutions, certify_generic, strategy_for, solve_lin, det_roots_of_strategies) and the registries (the reg_ functions). The file also defines the Engine class, try_rational, try_logring, and three more methods of VopClosure: topo_order, upward_closure and detour_roots.

Used on this site

Requirements

Source and references

The code is tools/vopclose/ in the BootLoops repository: 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.

ReferenceWhat it supplies
W. Hart, F. Johansson, A. Ahlbäck and the FLINT team, FLINTThe exact rational polynomials and matrices
F. Johansson, Arb, IEEE Trans. Comput. 66 (2017) 1281, arXiv:1611.02831The ball arithmetic of the evaluator
F. Johansson, O. Benjamin and contributors, python-flintThe Python bindings to FLINT and Arb
F. Johansson and the mpmath contributors, mpmathThe multiprecision numbers, and the PSLQ routine that recognizes the boundary values
RatfitThe exact reconstruction behind exact_entry_from_samples

← back to the tools index