Coalescer

Coalescer computes connection coefficientsthe numbers that express a solution known at one point in the basis of local solutions at another point of a linear differential equation with polynomial coefficients. It takes the operator and the exact Taylor series of one solution, continues that solution to a singular point with fractional local exponentsthe powers of the local coordinate with which the solutions begin at a singular point, and returns the coefficient $c_\alpha$ of each branch $t^{\alpha}(1+\dots)$ there. The worked example in the package is the banana Feynman integralthe Feynman integral in which every propagator joins the same two vertices at its threshold, built from the masses alone with the all-loop period series of Bönisch, Fischbach, Klemm, Nega and Safari (arXiv:2008.10574).

What it does

A Fuchsian operatora linear differential operator with polynomial coefficients whose solutions, near each singular point, behave like a power of the local coordinate times a polynomial in its logarithm $L=\sum_{j} P_j(z)\,\theta_z^{\,j}$, with $\theta_z=z\,d/dz$, has a set of local exponents at each singular point. Where they are all integers the local solutions form a tower of integer powers and logarithms. Where some are fractions the local basis also contains branches $\Phi_\alpha(t)=t^{\alpha}\,(1+O(t))$, which return multiplied by $e^{2\pi i\alpha}\neq 1$ when $t$ is carried once around the point. A solution $f(z)=\sum_n a_n z^n$ holomorphic at $z=0$, continued to such a point, is the integer-and-logarithm tower plus $\sum_\alpha c_\alpha\Phi_\alpha(t)$. Coalescer computes one $c_\alpha$ for every fractional exponent of the operator at that point.

These coefficients are wanted at the threshold or pseudo-threshold of a Feynman-integral family whose Picard–Fuchs operatorthe minimal differential operator in one kinematic variable that annihilates the integral is known, and at conifold-type points of Calabi–Yau operators. They also fix the constant in the large-$n$ asymptotics of a P-recursive sequencea sequence that satisfies a linear recurrence with polynomial coefficients whose generating function has an algebraic branch point.

Solving for $f$ against the full local basis loses most of the precision, because the fractional piece can be far smaller than the logarithmic tower. In the package's three-loop banana example it is about ten thousand times smaller. Coalescer avoids the subtraction. It integrates the equation once around the singular point to obtain the monodromy matrixthe matrix by which a basis of solutions transforms when the variable is carried once around a singular point and back $M_0$. The eigenvalue $1$ of $M_0$ belongs to the logarithmic ("unipotent") tower, and each eigenvalue $\lambda=e^{2\pi i\alpha}\neq1$ belongs to one fractional branch.

The projector onto one $\lambda$ is a polynomial in $M_0$,

$$P_\lambda=\frac{(M_0-\mathbb{1})^{n}\,\prod_{\mu\neq 1,\lambda}(M_0-\mu\mathbb{1})}{(\lambda-1)^{n}\,\prod_{\mu\neq 1,\lambda}(\lambda-\mu)}\,,$$

with $n$ the size of the unipotent block and $\mu$ running over the other fractional eigenvalues. The factor $(M_0-\mathbb{1})^{n}$ annihilates the logarithmic tower exactly, and the remaining factors annihilate the other branches. The projector builds on the monodromy analysis of Bönisch, Duhr, Fischbach, Klemm and Nega (arXiv:2108.05310).

A run has four steps:

Coalescer has two modes:

The output is a value for each $c_\alpha$ to many digits, computed in Python with mpmath (Route A), with three self-consistency figures. For banana mass tuples the package has a second implementation, Route B, in Julia with ball arithmeticinterval arithmetic in which every number carries a rigorous error radius, here the Arb library on the transport engine of Eichler. It differs from Route A in coordinate ($z=1/p^2$ rather than $s=-p^2$), contour direction and seed, and returns a value with a rigorous error radius. Agreement between the routes is the acceptance test, after which an integer-relation searchgiven a list of high-precision numbers, find small integers that combine them to zero, turning a decimal into an exact expression in known constants (PSLQ) runs on the agreed digits.

Coalescer has these limits:

Annihilator finds the Picard–Fuchs operator of a series, Lockpick runs the integer-relation search, and Arb is the ball arithmetic of Route B. For the general task of continuing the solutions of a differential operator from one point to another, the established public tool is ore_algebra.analytic by Marc Mezzarobba, which gives rigorous error bounds; Holonomic drives it.

On this site Coalescer has been used on the three-loop and four-loop bananas at the mass threshold.

Examples

Self-test. With the package set up (see Requirements), run the self-test from the root of the repository; the package directory is tools/coalescer/:

python3 tools/coalescer/coalescer.py --test

The test takes about 35 seconds and needs no Julia. It runs three extractions at reduced settings (30-digit arithmetic):

It prints the structure it finds before each number:

  threshold exponents: {3/2: 1, 1: 3}  fractional=[3/2]  nilp_rank=3
  semisimple eigenvalues: {3/2: -1}
  ...
[selftest] c_3/2 = (-0.01531469153949422359753685 - 4.112978363705437420542903e-28j)
[selftest] ref   = -0.01531469153949422359753685
  ...
[selftest] gauss c_{1/4}: ref = (0.8346268416740731862814297 + 0.8346268416740731862814297j)   match = 25.41 d over s_dec in ['0.15', '0.3']

The banana operator has order four with one exponent $3/2$ (eigenvalue $-1$) above a rank-three integer block, so here $P_{-1}=-\tfrac18(M_0-\mathbb{1})^3$. The Gauss operator has order two with exponents $\tfrac14,\tfrac34$ (eigenvalues $\pm i$) and no logarithmic block. Each part must match its closed form to at least 20 digits (about 25 at these settings). The $10^{-28}$ imaginary part is round-off and marks the noise floor.

Your own operator. The file examples/gauss_2f1.json, Gauss's hypergeometric function ${}_2F_1(\tfrac14,\tfrac34;1;z)$, shows the layout and is the template for your own. Its operator is $\theta^2-z(\theta+\tfrac14)(\theta+\tfrac34)$, so $P_0=-\tfrac{3}{16}z$, $P_1=-z$, $P_2=1-z$, each listed lowest power of $z$ first. The seed is $a_n=(\tfrac14)_n(\tfrac34)_n/n!^2$ with radius of convergence 1. Coefficients are integers, "p/q" strings or [p, q] pairs. Abridged (the file has 161 seed coefficients):

{
 "label": "Gauss 2F1(1/4,3/4;1;z)",
 "order": 2,
 "theta_coeffs": [["0", "-3/16"], ["0", "-1"], ["1", "-1"]],
 "seed_radius": 1,
 "alpha": "1/4",
 "sdec": ["0.15", "0.3"],
 "seed": ["1", "3/16", "105/1024", "1155/16384", "225225/4194304", ...]
}

Run it at 30 digits:

python3 tools/coalescer/coalescer.py --op tools/coalescer/examples/gauss_2f1.json \
    --dps 30 --out gauss_out.json

The run prints, in order:

Here the floor is 1: the only root of the leading polynomial $1-z$, which coincides with one over the declared "seed_radius". The result is $c_{1/4}=0.83462684167407318628\ldots\,(1+i)$, that is $|c_{1/4}|=\sqrt\pi/\Gamma(\tfrac34)^2$ with argument $\pi/4$, good to about 25 digits at --dps 30. A trustworthy run shows all three figures near the working precision. A drop means that the digits requested need more seed terms, a larger --nthr or more precision.

The banana worked example by both routes. Take the four-loop banana $(1,1,1,1,16)$, whose period geometry is a Calabi–Yau threefold and whose threshold exponents are $\tfrac54$ and $\tfrac74$. Run Route A at 200 digits, then Route B on the data file that comes with the package:

python3 tools/coalescer/coalescer.py --masses 1,1,1,1,16 --dps 200 --route A --out ROUTEA_CY3.json
PFDATA=pf_cy3_data.jl julia tools/coalescer/routeB_monoproj.jl

Route A places its seed points at 2.2 and 4.2 times the threshold scale $(\sum_i\sqrt{m_i^2})^2=64$, runs the extraction at two circle radii (0.15 and 0.25) and writes the record. The Julia script prints the seed point it chose from the operator's singularities, the accuracy in bits after transport, and each component of $c_\alpha$ as a ball (midpoint and radius). It then writes ROUTEB.json beside itself. PREC sets its precision in bits (about 0.3 digits per bit) and SDEC the circle radius.

The comparison script then reads both outputs, shown here with the names of the recorded files in tests/fixtures/ (run it there, or prefix the paths):

python3 tools/coalescer/gate_compare.py --family CY3 --routeA ROUTEA_CY3.json \
    --routeB ROUTEB_CY3_sdec025.json,ROUTEB_CY3_sdec0175.json \
    --k3-routeA ROUTEA_K3.json --k3-routeB ROUTEB_K3_ctrl.json --out compare_cy3.json

The comparison reports four things:

Its JSON summary has a targets block (the best Route B midpoint trimmed to its certified digits) for the integer-relation script. Exit status 0 means every comparison cleared the bar; 1 means one did not or a route is missing. In the reference summary beside the code the routes agree to roughly 70 digits and Route B matches the closed forms to about 260.

Routines

coalescer.py --help prints its options, the input layout and the rule for the seed points.

CommandWhat it does
coalescer.py --op FILE.jsonGeneral mode: every $c_\alpha$ of the operator in the file, by Route A
coalescer.py --masses a,b,...Banana mode; --route A or --route B selects the route
coalescer.py --testThe self-test of the first example
routeA_monoproj.pyRoute A for the two reference bananas; --target is K3, CY3 or both
routeB_monoproj.jlRoute B, set by PFDATA, PREC, SDEC, SB, OUT and EICHLER_PROJECT in the environment
dump_pf_data.py --msq a,b,... --out DIR/NAME.jlBuilds the banana operator; writes DIR/NAME.jl for Route B and DIR/NAME.json, which coalescer.py --op reads
gate_compare.pyThe two-route comparison of the third example
pslq_calpha.pyThe integer-relation search for the coefficients, through Lockpick
calpha_rings.pyThe mass tuples, exponents, constants and recorded closed forms read by the two scripts above

The --op file has the keys theta_form_Pj (aliases theta_coeffs, Pj) for the operator and bfkns_a (alias seed) for the series. Optional keys are order, alpha, label, seed_radius, sb, sb2, lift, sdec, nthr and nser. Command-line flags override the file.

--alpha p/q picks the coefficient to print; every fractional exponent is extracted either way. --sb and --sb2 set the seed points, --lift the imaginary offset of the path, --sdec the circle radii, --nthr the number of terms of the $\Phi_\alpha$ series, and --nser the number of seed terms.

With --route B the seed-point check runs first and an integer --sb reaches the Julia script as SB. coalescer.py does not pass the mass tuple to Julia: PFDATA must name the data file of that tuple. Route B looks for the PFDATA file beside the script. dump_pf_data.py writes it there when --out is a bare name such as NAME.jl; a path with a directory is used as given.

coalescer.py exits with status 0 on success, 1 for an error or a self-test below its bar, 2 for a usage error (including an unreadable --op file) and 3 for a refused seed point.

gate_compare.py takes --family (K3, CY3 or CY4), or --masses with --alphas. The recorded closed form for $(1,1,1,1,1,25)$ is $c_{3/2}=-\sqrt5/(40\pi^2)$. pslq_calpha.py takes its target from --c ALPHA=STRING, --from-routeB FILE or --from-gate FILE (the summary of the comparison script). Both scripts list their options and exit statuses at the top of the file.

FunctionWhat it returns
routeA_monoproj.run_operator(tag, Pj, order, seed_a, ...)A dictionary: the exponents and eigenvalues found, the values per radius (per_sdec) with their consistency figures, and c_alpha_best
routeA_monoproj.load_operator_json(path)The contents of an --op file, with the seed as exact fractions
routeA_monoproj.op_from_coeffs(table)(Pj, order) from coefficient lists, with a common integer normalization
routeA_monoproj.make_series_state(seed_a, order)A function that gives the vector $(f,\theta_z f,\dots)$ at a seed point from the series
routeA_monoproj.run(tag, msq, ...)The same dictionary for a banana mass tuple

The full argument list of the general routine is run_operator(tag, Pj, order, seed_a, dps, sb, sb2, lift, sdec_list, Nthr, frac, nloop, Nser=None, label=None), with Pj a dictionary of SymPy polynomials in z. The routine does not check the seed points; coalescer.py does that before it calls the routine.

The lower-level functions are in pf_engine.py: the banana operator (find_minimal_op), the exponents (indicial_threshold, indicial_mum), the exact series of a branch (frob_power_branch, phi_theta_state) and the integrator (build_ode_s, transport_adaptive). The recorded closed forms are returned by calpha_rings.closed_form(spec, alpha).

Used on this site

Requirements

Source and references

The code is tools/coalescer/ in the BootLoops repository, released under the MIT license. GUIDE.md there has the full option lists, the input layout and the defaults.

ReferenceWhat it supplies
K. Bönisch, F. Fischbach, A. Klemm, C. Nega and R. Safari, JHEP 05 (2021) 066, arXiv:2008.10574The all-loop series of the holomorphic banana period: the seed of banana mode, from which the operator is built
K. Bönisch, C. Duhr, F. Fischbach, A. Klemm and C. Nega, JHEP 09 (2022) 156, arXiv:2108.05310The monodromy analysis on which the projector builds
M. Mezzarobba, ore_algebra.analytic, arXiv:1607.01967; part of ore_algebra by M. Kauers, M. Jaroschek and F. Johansson, arXiv:1306.4263The established public tool for continuing solutions of a differential operator, with rigorous error bounds
F. Johansson, Arb, arXiv:1611.02831The ball arithmetic of Route B
F. Johansson and the mpmath contributors, mpmathThe arithmetic of Route A
H. R. P. Ferguson, D. H. Bailey and S. Arno, "Analysis of PSLQ", Math. Comp. 68 (1999) 351The integer-relation algorithm of the closed-form search

← back to the tools index