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:
- Canonical form. 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. This is the case 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.
- Constant recognition. Recognizing endpoint numbers as combinations of known constants with PSLQ, an integer-relation search, fails when one order mixes functions of different transcendental weight (number of nested integrations).
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:
- Homogeneous solutions. The solutions of a block are found as rational vectors, or as $\sqrt{\ell}$ times a rational vector for letters with half-integer exponents. Every column is verified exactly before use.
- Strategy. 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. - Integration. A rational factor is integrated by 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.
- Check. 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:
- Boundary values. Each value at $t=0$ 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$. Otherwise it is 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.
- Evaluation. The
Engineclass places Chebyshev nodes (sample points clustered toward the ends of each segment) on a contour from $0$ to $1$. It accumulates the iterated integrals in ball arithmetic (Arb through python-flint; a number is a midpoint with a radius) and continues the square roots along the contour.
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:
- It handles one path variable, and one path per run.
- Connection entries must be exact. From exact samples at rational points,
exact_entry_from_samplesreconstructs an entry through Ratfit. 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. For deep ranges setscope_rowsto the integrals you need. The last order is then solved only on the blocks they depend on.
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.
| Function | What 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_record | Per (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
- Non-planar hexa-box: the variation-of-parameters solution of the top sector, order by order in $\epsilon$, and the transport of the subsector orbits. The three top-sector masters are in closed form through the finite part, with the square root of a quartic $Q_4$ as prefactor and exponents $(\tfrac12,\tfrac12,0)$ at its zeros.
- Non-planar $q\bar q\to W^+W^-$: the variation-of-parameters solution of the blocks, order by order in $\epsilon$. The evaluation script of that page imports
vopclose.py.
Requirements
- Runs on: Python 3 with mpmath and python-flint.
- Install: the package has no install step. Both libraries are in the command that the repository's
INSTALL.mdgives for the common Python dependencies,pip install mpmath sympy numpy python-flint. - Self-test:
python3 tools/vopclose/vopclose.py --testfrom the repository root ends with a line beginningvopclose selftest: 14/14 PASS. - Ratfit:
exact_entry_from_samplesand the last self-test check import Ratfit from the neighboringtools/ratfit/directory. It is found automatically when the two sit side by side as in the repository.
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.
| Reference | What it supplies |
|---|---|
| W. Hart, F. Johansson, A. Ahlbäck and the FLINT team, FLINT | The exact rational polynomials and matrices |
| F. Johansson, Arb, IEEE Trans. Comput. 66 (2017) 1281, arXiv:1611.02831 | The ball arithmetic of the evaluator |
| F. Johansson, O. Benjamin and contributors, python-flint | The Python bindings to FLINT and Arb |
| F. Johansson and the mpmath contributors, mpmath | The multiprecision numbers, and the PSLQ routine that recognizes the boundary values |
| Ratfit | The exact reconstruction behind exact_entry_from_samples |