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:
- Structure. The order, exponents, multiplicities and eigenvalues are read from the operator at run time, so nothing in the code is tied to one example.
- Branches. The series $\Phi_\alpha$ are generated exactly over the rationals.
- Transport. $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.
- Projection. $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.
Coalescer has two modes:
- 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). - Banana mode,
coalescer.py --masses 1,1,1,9. The input is the list of squared masses of the banana integral. 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 builds the Picard–Fuchs operator exactly over the rationals from the all-loop series of the holomorphic period and takes that series as the seed.
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:
- It says nothing about the coefficients of the logarithmic tower, which the projector deletes by design.
- It is not meant for expansions around a point of maximal unipotent monodromythe standard expansion point for Calabi–Yau periods such as the banana's large-momentum point; use Eichler.
- In general mode 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. An operator supplied through
--opruns Route A only. - 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.pycomputes 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
--opit is by default the more conservative $1/\min|z|$ over all roots of the leading polynomial, and--anchor-law seedswitches 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.
- 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.
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):
- the three-loop banana $(1,1,1,9)$ in banana mode, the K3 case, whose coefficient is $c_{3/2}=-\sqrt3/(36\pi)$;
- the same operator and seed written to a JSON file and run through
--opin a second process; examples/gauss_2f1.jsonthrough--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. 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:
- the seed-point floor, the two seed points in force (2.2 and 4.2 times the floor unless the file or
--sb,--sb2set them) and the verdict; with--check-onlythe run stops there; - the exponents and eigenvalues found, and the digits to which the truncated seed series has converged at the seed point;
- for each circle radius in
sdec, every $c_\alpha$ with two consistency figures in digits: agreement among the components of $P_\lambda f/\Phi_\alpha$, and between the two seed points; - the agreement between radii.
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:
- 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 agreement between circle radii within each route;
- the K3 outputs as a control.
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.
| Command | What it does |
|---|---|
coalescer.py --op FILE.json | General 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 --test | The self-test of the first example |
routeA_monoproj.py | Route A for the two reference bananas; --target is K3, CY3 or both |
routeB_monoproj.jl | Route B, set by PFDATA, PREC, SDEC, SB, OUT and EICHLER_PROJECT in the environment |
dump_pf_data.py --msq a,b,... --out DIR/NAME.jl | Builds the banana operator; writes DIR/NAME.jl for Route B and DIR/NAME.json, which coalescer.py --op reads |
gate_compare.py | The two-route comparison of the third example |
pslq_calpha.py | The integer-relation search for the coefficients, through Lockpick |
calpha_rings.py | The 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.
| Function | What 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
- Three-loop banana at the mass threshold: built the exact Picard–Fuchs operator from the period series and extracted $c_{3/2}=-\sqrt3/(36\pi)$ for the $(1,1,1,9)$ banana with the spectral projector.
- Four-loop banana at the mass threshold: extracted the fractional branches $c_{5/4}$ and $c_{7/4}$ of the $(1,1,1,1,16)$ banana from the transported period with the spectral projector.
Requirements
- Runs on: Python 3 with mpmath, SymPy and NumPy. The commands on this page are run from the root of the repository.
- Self-test:
python3 tools/coalescer/coalescer.py --testends with a line beginning[selftest] PASSand exit status 0, or stops with status 1. Its scratch files go to a temporary directory that is removed afterwards. - Test suite:
python3 -m pytest tools/coalescer/tests -rsneeds pytest and takes about a minute. One slow test is skipped unlessCOALESCER_SLOW=1. - Integer-relation search:
pslq_calpha.pyalso needs the siblingtools/lockpick/package. - Optional: Route B needs Julia with Arblib and the Eichler.jl project, which is in the repository under
upgrades/Eichler.jl/. Instantiate it once, or pointEICHLER_PROJECTat your copy.
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.
| Reference | What it supplies |
|---|---|
| K. Bönisch, F. Fischbach, A. Klemm, C. Nega and R. Safari, JHEP 05 (2021) 066, arXiv:2008.10574 | The 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.05310 | The 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.4263 | The established public tool for continuing solutions of a differential operator, with rigorous error bounds |
| F. Johansson, Arb, arXiv:1611.02831 | The ball arithmetic of Route B |
| F. Johansson and the mpmath contributors, mpmath | The arithmetic of Route A |
| H. R. P. Ferguson, D. H. Bailey and S. Arno, "Analysis of PSLQ", Math. Comp. 68 (1999) 351 | The integer-relation algorithm of the closed-form search |