Coalescer

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

Coalescer computes connection coefficients of a linear differential equation with polynomial coefficients. You give it the operator and the exact Taylor series of one solution around a point where that solution is holomorphic, as one small JSON file, plus a working precision. It continues the solution to a singular point where some local exponents are fractions and returns, for each fractional exponent $\alpha$, the coefficient $c_\alpha$ of the branch $t^{\alpha}(1+\dots)$ there. Each coefficient comes to many digits with self-consistency figures, ready for an integer-relation search that turns the digits into a closed form. For the worked example that comes with the package, the banana Feynman integral at its threshold, the masses alone are enough: the operator and the series are built for you.

What it does

A Fuchsian operatora linear differential operator with polynomial coefficients whose singular points are all regular: near each of them every solution behaves 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))$ that 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, splits into the integer-and-logarithm tower plus $\sum_\alpha c_\alpha\Phi_\alpha(t)$; the numbers $c_\alpha$ are what Coalescer computes, one for every fractional exponent the operator has there. Such coefficients are wanted at the threshold or pseudo-threshold of a Feynman-integral family whose Picard–Fuchs operator (the 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 sequence 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 (about ten thousand times smaller in the package's K3 example). 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; 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}$ removes the logarithmic tower exactly, the remaining factors remove the other branches, and $P_\lambda f=c_\alpha\Phi_\alpha$ is read off component by component from the vector $(f,\theta f,\dots,\theta^{r-1}f)$, with $r$ the order. Order, exponents, multiplicities and eigenvalues are read from the operator at run time, so nothing in the code is tied to one example. The series $\Phi_\alpha$ are generated exactly over the rationals, and $f$ is carried from two seed points, where its Taylor series still converges, to a small circle around the singular point by adaptive Taylor-series integration.

In the general mode, coalescer.py --op FILE.json, the file holds the exact coefficients of each $P_j(z)$ and of the solution's series (a few hundred terms). Optional entries name the exponent to print as the headline, a label, the series' radius of convergence and run settings. The coordinates are yours to arrange: the series must converge around $z=0$ and the branch point must sit at $z=\infty$, where $t=1/z$ is the local coordinate. Apply a Möbius transformation to your operator first if they lie elsewhere; the fractional branches must be free of logarithms. The file examples/gauss_2f1.json, Gauss's hypergeometric function ${}_2F_1(\tfrac14,\tfrac34;1;z)$, is a runnable example and the template for your own. In the banana mode, coalescer.py --masses 1,1,1,9, the input is the worked example that comes with the package: the Feynman integral in which every propagator joins the same two vertices. The squared masses are tuned so that the threshold sits at $t=p^2=0$ ($\sqrt9=\sqrt1+\sqrt1+\sqrt1$) and the exponents there are half- or quarter-integers. Coalescer then builds the Picard–Fuchs operator exactly over the rationals from the known all-loop series of the holomorphic period (Bönisch, Fischbach, Klemm, Nega and Safari, arXiv:2008.10574), takes that series as the seed, and calls the same kernel.

The output is a high-precision numerical value for each $c_\alpha$, computed in Python with mpmath ("Route A") and accompanied by three self-consistency figures described in the examples; closed forms come afterwards, from an integer-relation search. For banana mass tuples the package also carries an independent 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 (PSLQ) search runs on the agreed digits. An operator supplied through --op runs Route A only.

Coalescer says nothing about the coefficients of the logarithmic tower, which the projector deletes by design, and it is not meant for expansions around a point of maximal unipotent monodromy such as the banana's large-momentum point (use Eichler). Two cautions apply. First, the seed points must lie inside the disk where the seed series converges; outside it the truncated series sums to a wrong value with no visible symptom. coalescer.py therefore computes a floor for the seed points from the operator before integrating anything, prints it, and refuses a seed point at or below it with exit status 3. In banana mode the floor is the threshold scale, one over the seed series' radius of convergence; for an operator given through --op it is by default the more conservative $1/\min|z|$ over all roots of the leading polynomial, and --anchor-law seed switches it to one over the "seed_radius" declared in the file. Seed coefficients must be exact; a float with a fractional part is refused with a message. Second, at a point whose monodromy has order four (quarter-integer exponents, eigenvalues $\pm i$) the sign of $c_\alpha$ depends on branch and orientation conventions, which differ between the two routes; compare $|c_\alpha|$ across routes and quote signs in the convention stated at the top of pf_engine.py.

Examples

Self-test. Check the installation:

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): the three-loop banana $(1,1,1,9)$, the K3 case, whose coefficient is $c_{3/2}=-\sqrt3/(36\pi)$, in banana mode; the same operator and seed written to a JSON file and run through --op in a second process; and examples/gauss_2f1.json through --op, checked against Gauss's connection formula $c_a=e^{i\pi a}\,\Gamma(b-a)/(\Gamma(b)\,\Gamma(1-a))$ for $a=\tfrac14$ and $\tfrac34$. 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 at all. Each part must match its closed form to at least 20 digits (about 25 at these settings); the script prints PASS and exits with status 0, or stops with status 1. The $10^{-28}$ imaginary part is round-off and marks the noise floor.

Your own operator. The Gauss file shows the layout. 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 carries 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", ...]
}
python3 tools/coalescer/coalescer.py --op tools/coalescer/examples/gauss_2f1.json --dps 30 --out gauss_out.json

The first line printed gives the seed-point floor (here 1: the only root of the leading polynomial $1-z$, which coincides with one over the declared "seed_radius"), the two seed points in force (2.2 and 4.2 times the floor unless the file or --sb, --sb2 set them) and the verdict; with --check-only the run stops there, in seconds. Then come the exponents and eigenvalues found, the number of digits to which the truncated seed series has converged at the seed point, and one block per matching radius in sdec. Each block gives every $c_\alpha$ with two consistency figures in digits: agreement among the components of $P_\lambda f/\Phi_\alpha$, and agreement between the two seed points. A last line gives the agreement between radii. Here $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 the digits requested need more seed terms, a larger --nthr or more precision. A banana operator makes the same round trip: python3 tools/coalescer/dump_pf_data.py --msq 1,1,1,9 --out DIR/k3.jl also writes DIR/k3.json in this layout, and coalescer.py --op DIR/k3.json runs it.

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 (dump_pf_data.py --msq ... --out NAME.jl writes one for a new tuple):

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), 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 that come with the package 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: the digits every Route A sample shares with every Route B sample (the smallest must reach --bar, default 30); the digits each shares with the recorded closed forms $c_{5/4}=-1/(\sqrt{2\pi}\,\Gamma(\tfrac14)^2)$ and $c_{7/4}=-5\,\Gamma(\tfrac14)^2/(384\sqrt2\,\pi^{5/2})$; the independence from the circle radius within each route; and the K3 outputs as a control. Its JSON summary carries 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

Command-line scripts

Python functions

Used on this site

Requirements and source

Python 3 with mpmath, SymPy and NumPy for coalescer.py, Route A and the data, comparison and search scripts; pslq_calpha.py also needs the sibling tools/lockpick/ package, and the test suite needs pytest. Route B needs Julia with Arblib and the Eichler.jl project, which is included in BootLoops' bootloops-dev repository (GitHub organization BootLoops-ai) under upgrades/Eichler.jl/; instantiate it once, or point EICHLER_PROJECT at your copy. Self-test: python3 tools/coalescer/coalescer.py --test from the repository root (Python only, about 35 seconds, exit status 0 on success; its scratch files go to a temporary directory that is removed afterwards). Test suite: python3 -m pytest tools/coalescer/tests -rs, about a minute. It covers the seed-point floors and exit codes for the three reference tuples and the --op mode's check, refusal and usage errors on a freshly written K3 file. It also reruns the comparison and integer-relation scripts on the recorded CY3 and CY4 outputs in tests/fixtures/; a repeat of --test compared with its recorded output is skipped unless COALESCER_SLOW=1. Code: tools/coalescer/ in the bootloops-dev repository, released under the MIT license. Related pages: Eichler, Annihilator, Lockpick, PSLQ, Arb.

← back to the tools index