Membound
Membound computes soft-region ($\omega\to0$) boundary constants for worldlineeach body is treated as a point particle moving along a line in spacetime and post-Minkowskianan expansion of the two-body problem of general relativity in powers of Newton's constant expansions. In that region a loop integral reduces to a two- or three-dimensional integral over frequencies, which the user describes in a short JSON file. Membound expands the integrand in the dimensional-regularization parameter $\epsilon$ before integrating numerically, the method of Driesse, Jakobsen, Mogull, Nega, Plefka, Sauer and Usovitsch (arXiv:2601.16256), and returns the first three coefficients in $\epsilon$.
What it does
Integrals in these expansions are usually computed from differential equations in the kinematic variables, which need starting values at a special point. For black-hole scattering the soft region is the memory region, where exchanged gravitons are real radiation with zero net frequency. In the soft region the special point is the static limit (zero relative velocity). There the integrals reduce to integrals over $n=2$ or $3$ frequencies and a coupler frequency equal to their sum, $\omega_{n+1}=\omega_1+\dots+\omega_n$:
$$J(\epsilon)=\frac{1}{(2\pi)^{n}}\int d^{n}\omega\;\prod_{i}\big(0^+-i s_i\omega_i\big)^{p_i-q_i\epsilon}\;\prod_{j}|\omega_j|^{-\epsilon}K_\epsilon(|\omega_j|)\;\prod_{l}\omega_l^{n_l}.$$
Here $\epsilon=(4-d)/2$ with $d$ the spacetime dimension, $K_\epsilon$ is the modified Bessel function, and $p_i$ and $n_l$ are integers. The sign $s_i=\pm1$ selects the retarded or advanced $i0^+$ prescriptionthe rule for passing the pole of a propagator in frequency space: retarded, advanced, or Feynman of a factor. Membound calls such an integral a core.
For each core Membound returns the moments $J^{(0)},J^{(1)},J^{(2)}$ of $J(\epsilon)=J^{(0)}+J^{(1)}\epsilon+J^{(2)}\epsilon^2+O(\epsilon^3)$, measure included, and the layer index $k=\sum_i q_i+(\text{number of Bessel lines})$. The index is the power in the small-frequency behavior $|\omega|^{-k\epsilon}$ under which a family of cores assembles into a boundary vector.
Membound expands the integrand in $\epsilon$ before integrating, because a fixed-$\epsilon$ evaluation of these cores loses most of its digits to cancellations between pole orders. The expansion before integration, the phase of the order-$\epsilon$ logarithm and the numerical integration over frequencies are the method of Driesse et al., from the supplement of their paper. A run has three steps.
- Expand. The integrand is expanded in $\epsilon$ to second order. Each frequency factor splits into a leading part $(-i)^{p}\omega^{p}$ and an order-$\epsilon$ logarithm $\log|\omega|+i\varphi(\operatorname{sign}\omega)$, whose phase is set by the factor's flag.
- Split. The frequency space is cut into sign sectors: six for two frequencies, and fourteen pieces of the eight sign octants for three. Each sector's weight at each order is derived from the factor list, and sectors with equal integrands are merged.
- Integrate. Each remaining sector is integrated with mpmath's tanh-sinh quadraturea change of variables that clusters sample points at the ends of each panel, so endpoint singularities such as $\log|\omega|$ or $K_0$ at $\omega=0$ cost little accuracy on panel breakpoints along every magnitude axis. The quadratures run in parallel worker processes.
A flag changes only a factor's order-$\epsilon$ phase. The leading factor always keeps the retarded form.
"ret"on every factor is the retarded assignment and is exact."adv"on every factor is exact too and gives the same integrals, because $\omega_i\to-\omega_i$ maps one into the other.- Mixing
"ret"and"adv"between factors misses an overall sign and is not supported. "fey"puts the constant Feynman phase $-\pi/2$ on top of the retarded leading factor. A"fey"run is a diagnostic of how sensitive an assembled constant is to the phase layer. It is not the Feynman propagator prescription, which changes the whole power to $(0^+-i|\omega|)^{p-q\epsilon}$ and with it the leading factors. That assignment is outside what the package computes.
Membound has these limits:
- The result is a numerical estimate without a proven error bound.
--dps(working digits),--maxdegree(quadrature depth per axis) and--panels(put a breakpoint near every scale of the integrand) control the accuracy. The cost grows steeply with the first two. - A core of your own has no known value to compare with. Its output record carries
digits: nulluntil you repeat the run at higher settings and difference the two. - The integrand must decay at large $|\omega|$ along every independent direction. The package does not test this, and a non-decaying integrand returns a finite wrong number, not an error.
- The odd projection (
"proj": "im") is accepted but has not been validated against any known value.
The worked example is the planar memory sector of black-hole scattering at fifth order in Newton's constant and second order in the mass ratio, at the static limit. The Black-hole scattering page describes the memory region and the constant $c_M$. The two cores I1M and I3M (two frequencies, layer $k=7$), multiplied by exact $\Gamma$-function series, give the integrals $I_1^{(M)}$ and $I_3^{(M)}$ of Driesse et al. The third integral $I_2^{(M)}$ follows from their integration-by-parts identity, and $c_M=-\tfrac{6}{5}(8\pi)^4\,I_2^{(M)}\big|_{\epsilon^{-2}}$.
Four checks measure the accuracy:
- The zeroth moment of
I1Mequals $1/30$. - The $\epsilon^{-1}$ coefficient of $I_1^{(M)}$ equals $1/(15(8\pi)^4)$.
- The $\epsilon^{-4}$ and $\epsilon^{-3}$ terms of $I_2^{(M)}$ cancel.
- $c_M=1$.
At --dps 30 --maxdegree 6, $c_M$ comes out to about 25 digits and the pole to about 28; this quadrature route does not go further. With "fey" on both memory factors the poles still cancel and $c_M$ moves from 1 to exactly $1/5$. That is not the value with Feynman propagators, for which the leading cores change and the $\epsilon^{-4}$ pole of $I_2^{(M)}$ does not cancel.
The example's registry also names the crossed-planar (PX2) memory sector and the non-planar (NP) family, which needs three-frequency cores ("n_freq": 3, supported by the engine). No cores or constants are provided for them, and an absent entry should not be read as zero. Number recognition beyond the built-in test with PSLQ (an integer-relation algorithm) is meant to go through Lockpick.
Examples
Compute a core from a JSON spec. The package includes the small two-frequency core examples/core_example.json, $J(\epsilon)=(2\pi)^{-2}\int d\omega_1\,d\omega_2\,(0^+-i\omega_3)^{2-\epsilon}\prod_{i=1}^{3}|\omega_i|^{-\epsilon}K_\epsilon(|\omega_i|)$ with $\omega_3=\omega_1+\omega_2$. Its zeroth moment is exactly $-1/15$. Without the file's free-text _comment key, the spec is
{
"name": "w3sq_K123",
"n_freq": 2,
"ret": [[3, 2, 1, "ret"]],
"klines": [1, 2, 3],
"poly": {},
"proj": "re"
}
ret: one entry[index, p, q, flag]per factor $(0^+-is\,\omega_{\text{index}})^{p-q\epsilon}$, withflagone of"ret","adv","fey".klines: the frequencies carrying $|\omega|^{-\epsilon}K_\epsilon(|\omega|)$.poly: a map from an index to an extra integer power.n_freq: 2 or 3. Indexn_freq+1(here 3) is the coupler.
Indices outside 1..n_freq+1 and unknown keys are refused with a message. With Python and mpmath in place (see Requirements), run from the directory that contains membound/ (tools/ in the repository):
python3 -m membound --spec membound/examples/core_example.json --dps 9 --maxdegree 3 --panels 0,2,inf
The run prints the core's name, the layer index (4 here) and the settings, one progress line per quadrature, then J^(0), J^(1), J^(2) and the assembled J(eps) = ... + O(eps^3). At these settings it finishes in seconds and J^(0) agrees with $-1/15$ to eight or more digits.
Reproduce $c_M=1$ from both cores. The check script computes both cores of the worked example at 11 digits, applies the prefactors and the integration-by-parts step, and runs the four checks. From the same directory:
python3 membound/gate_cM.py --dps 11 --maxdegree 4 --jobs 12
The script prints one line per quadrature, then the six moments and the assembled Laurent series of the three integrals. One CHECK line per test gives the digits of agreement (or, for the cancellation tests, the relative size of the term) beside the demand, dps minus 5. It ends with $c_M$, the integer relation PSLQ finds between $c_M$ and 1 ([1, -1] means $c_M=1$), and PASS or FAIL.
At these settings expect a couple of minutes on twelve processes, well under a gigabyte of memory, and agreement to roughly ten digits. Before a longer run add --micro to the intended command (for a 30-digit run, --dps 30 --maxdegree 6 --micro). The script then integrates only the most expensive piece and projects the time of a full run, as an upper estimate.
Routines
| Command | What it does |
|---|---|
python3 -m membound --spec FILE | Computes the moments $J^{(0)},J^{(1)},J^{(2)}$ of the core in FILE |
python3 cli.py --spec FILE | The same, from inside the package |
gate_cM.py | Runs the worked example: both cores, the assembly, the four checks and a PSLQ test of $c_M$ against 1 |
Both python3 -m membound and gate_cM.py take --dps, --maxdegree, --panels, --jobs (1 runs serially) and --json-out FILE. The first also takes --quiet (no progress lines) and --order-max (0, 1 or 2); --order-max 0 computes only the leading moment, for sizing a run. gate_cM.py also takes --micro, shown in the second example.
--json-out writes the result as a JSON record with the coefficients as decimal strings: membound.core_moments.v1 from python3 -m membound, and membound.boundary_vector.v1 from gate_cM.py.
The Python names are given with their module inside the membound package.
| Function | What it returns |
|---|---|
core.OmegaCoreSpec, cli.load_spec(path) | One core, built in Python with the fields of the JSON spec or read from a spec file |
core.compute_core(spec, dps, brk, maxdegree) | The moments of one core, measure included, computed serially on the breakpoints brk |
farm.compute_cores_parallel(specs, dps, panels, maxdegree, jobs) | The moments of several cores, computed over jobs processes |
spec.I1M_CORE, spec.I3M_CORE, spec.REGISTRY | The two cores of the planar memory sector, and the registry keyed by (family, region, sector) |
assemble.prefactor_I1(), assemble.prefactor_I3(), assemble.ibp_I2(I1, I3) | The exact $\Gamma$-function prefactors as laurent.L series, and $I_2^{(M)}$ from the integration-by-parts identity |
assemble.boundary_vector, assemble.emit | The boundary-vector record, and its file as indented JSON |
The lower-level names are defined in core.py, farm.py, assemble.py and laurent.py.
Requirements
- Runs on: Python 3 with mpmath. Parallel runs use the process pool of the standard library.
- Install: no install step is needed. Work from the directory that contains
membound/(tools/in the repository), or run the scripts inside the package directly. Each script puts that directory on the import path. - Self-test:
python3 selftest.pyfrom insidetools/membound/runs thirteen checks at 9 digits against exact or closed-form values. It takes about twenty seconds and ends with# BATTERY: PASS; the exit status is 0 on pass. If mpmath is missing it says so and exits with 0.--fulladds the $c_M$ reproduction at 11 digits and takes minutes.
Source and references
The code is tools/membound/ in the BootLoops repository, released under the MIT license. GUIDE.md there gives the spec format in full and the defaults of the main options.
| Reference | What it supplies |
|---|---|
| M. Driesse, G. U. Jakobsen, G. Mogull, C. Nega, J. Plefka, B. Sauer and J. Usovitsch, Phys. Rev. Lett. 137 (2026) 081402, arXiv:2601.16256, and its supplement | The memory-region integrals, their evaluation by expanding in $\epsilon$ before numerical integration, the $\Gamma$-function prefactors, the integration-by-parts identity and $c_M=1$ |
| F. Johansson and the mpmath contributors, mpmath | The arbitrary-precision arithmetic, the Bessel and $\Gamma$ functions, the tanh-sinh quadrature and PSLQ |