Nestor
Nestor computes definite integrals numerically to high precision (tens of digits or more) and reports only the digits on which two successive refinements of the calculation agree. It uses tanh-sinh quadraturea rule that maps the interval onto the whole real line and applies the trapezoid rule there, also called double-exponential quadrature, the rule of H. Takahasi and M. Mori, and is built on mpmath by F. Johansson and the mpmath contributors. A separate module, nestor.dispersion, integrates a spectral densitytypically the imaginary part of a self-energy, as a function of energy against a smooth kernel when the density has known singularities at thresholdsthe energies at which a new channel opens.
Where it comes from
mpmath, by F. Johansson and the mpmath contributors, is a Python library for arithmetic and quadrature at any precision. Nestor is BootLoops code built on it. One loop of Nestor follows mpmath's code.
| Part of Nestor | Source | Authors |
|---|---|---|
Follows their code: the depth loop of cert_quad, which drives the serial route | QuadratureRule.summation in mpmath's calculus/quadrature.py | F. Johansson and the mpmath contributors |
| Called at run time: the tanh-sinh rule of the serial route and of the dispersion module, and the Taylor and Gauss–Legendre routines | mpmath | The same authors |
| New code: the node list of the grid route, the stopping test, the endpoint check, the records and the dispersion module | The formulas of Takahasi and Mori, and the references under Source and references | Code by Claude |
The loop of cert_quad has the same statements as mpmath's loop, in the same order and with the same method names. The stopping test is Nestor's. It compares two successive depths directly and raises an error where mpmath's loop ends without one.
Please cite Takahasi and Mori, and mpmath, when you use it. Nestor is not affiliated with or endorsed by the mpmath developers.
What it does
The substitution $x=\tanh(\tfrac{\pi}{2}\sinh t)$ maps the interval onto the whole line, and the trapezoid rule is applied in $t$. The weights fall off doubly exponentially toward the ends, so integrable endpoint singularities such as $x^{-1/2}$ or $\log x$ need no special treatment. Halving the step reuses every node already computed, so each refinement level contains the previous one.
Nestor uses that nesting as its test. It raises the level, with guard digits (extra digits carried beyond the request), until two successive levels agree to at least the requested number of digits. It returns that value as an mpf, mpmath's real number type. If the levels run out first it raises CertFail, whose message states how many digits the run could have delivered, and returns no value. An integrand may itself call Nestor, so a multiple integral is done as nested one-dimensional ones.
A call to nestor.integrate checks the endpoints, integrates on one of two routes and records the run.
- Check. Before any quadrature,
singchecktests the endpoint declaration against samples of the integrand near each endpoint. The declaration is a dictionary such as{"a": {"type": "algebraic", "exponent": -0.5}, "b": {"type": "none"}}, with typesnone,algebraicandlog. An omitted endpoint counts asnone. - Serial route. Nestor drives mpmath's tanh-sinh rule through increasing depths, ten guard digits above the request. The upper limit may be
mp.inf. - Grid route. Nestor builds its own node list at level
md(step $h=2^{-md}$, default 6) and evaluates the nodes over a pool ofnprocworker processes. The even-numbered nodes give the levelmd-1result. If the two levels agree to fewer digits than requested, Nestor repeats the grid atmd+1,md+2,md+3. - Record. Every run can write a JSON record: the configuration, checksums of the engine files, the result of the check and one entry per level. It ends with the value as a decimal string, or with the class, message and exit code of the error.
The grid route is taken whenever nproc>1, md is given, a singular endpoint is declared, or wants_dists is set. Its nodes are placed by their distances from each endpoint without cancellation, whereas mpmath's rule loses about half its working digits at an inverse-square-root endpoint. It is also the route for expensive integrands, typically inner Nestor integrals, which a serial outer integral would evaluate on one core.
The module nestor.dispersion handles dispersion integrals $I=\frac{1}{\pi}\int\rho(w')\,K(w')\,dw'$. A spectral density $\rho$ (typically the imaginary part of a self-energy, expensive to evaluate) multiplies a kernel $K$ that is inexpensive and analytic between thresholds. The density switches on at the lowest threshold $w_\ast$ like $(w'-w_\ast)^{\alpha}[\log(w'-w_\ast)]^{m}$ and may jump at higher thresholds. A Gauss–Legendre rule then gains digits only polynomially in the number of nodes.
The module breaks the range into panels at the thresholds, which is all a finite jump needs. On a short sub-panel next to each singular threshold it subtracts the known model $S(w')=\sum_j c_j\,(w'-w_\ast)^{\alpha_j}[\log(w'-w_\ast)]^{m_j}$. The difference $(\rho-S)K$ is analytic, so tanh-sinh converges exponentially on it, and $\int S\,K$ is added back in closed form. With $K(w')=\sum_n K_n (w'-w_\ast)^n$ every term is a moment $\int_0^L u^{p}(\log u)^{m}\,du$, which is elementary.
Nestor has these limits:
- Nestor is a numerical integrator, and its agreement figure is measured self-consistency, not a proven error bound. The test cannot detect a bias shared by every level, for example a truncated series inside your own integrand.
- Singular behavior must sit at the endpoints and be declared. Split the interval at an interior singularity yourself.
- The run stops with
SpecRefusalif the samples do not match the declaration, if a declared exponent is $-1$ or below (not integrable), or if a sample is not finite. With no declaration nothing is checked, and the record says so. - For a singular endpoint at nonzero $a$, or at both ends, write the integrand as
f(u, d_a, d_b)and passwants_dists=True. It then receives the distances to both endpoints at full relative accuracy. - Parallel runs need the integrand as an importable
"module:function"string, because the workers re-import it. A bare Python callable is run serially, with a log line saying so. - The dispersion module is plain quadrature without the agreement test of
integrate. Repeat the call at two tanh-sinh levels (themaxdegreeargument) or two precisions and keep the digits that agree, or hand the panel integrands tonestor.integrate. - The sub-panel width and the Taylor radius must both be smaller than the distance from the threshold to the nearest singularity of $K$, or the add-back is wrong without warning.
- The closed-form moments cover $p\gt-1$ and log powers 0, 1 and 2, and $K$ must be analytic inside every panel.
nestor.probe is the quad_probe of Gatekeeper, re-exported unchanged. Fixing the tanh-sinh level of a dispersion integral fixes the nodes in advance, so a density that obeys a differential equation can be produced at every node in one pass with Wayfinder.
Examples
Run the self-tests. With the package set up (see Requirements), run from the repository's tools/ directory, which holds the package directory nestor/:
python3 -m nestor.selftest --nproc 2
Six checks integrate functions with known values, among them $\int_0^1 4\,dx/(1+x^2)=\pi$. Three give deliberately wrong input, such as $x^{-1/2}$ declared regular, and must be refused. Four test the dispersion module. Each check prints a PASS or FAIL line, and the run, which takes a few seconds, ends with
[selftest] 13/13 controls passed, wall 2.4 s -> PASS
(the time varies by machine). The exit status is 0 on pass and 3 on any failure.
Regular, singular and nested integrals. These are the calls the self-test makes (tools/ on sys.path):
import mpmath as mp
import nestor
D = 30
v = nestor.integrate(lambda x: 4 / (1 + x * x), 0, 1, dps=D)
spec = {"a": {"type": "algebraic", "exponent": -0.5}}
v = nestor.integrate(lambda x: 1 / mp.sqrt(x), 0, 1, dps=D, spec=spec)
spec = {"a": {"type": "algebraic", "exponent": -0.5},
"b": {"type": "algebraic", "exponent": -0.5}}
v = nestor.integrate(lambda u, da, db: 1 / mp.sqrt(da * db), 0, 1,
dps=D, spec=spec, wants_dists=True)
def outer(y):
return nestor.integrate(lambda x: 1 / (1 + x * y), 0, 1, dps=26)
v = nestor.integrate(outer, 0, 1, dps=20)
Each call returns an mpf good to at least the requested digits (the self-test measures 40.3 against $\pi$ for the first). The second and third take the grid route because a singular endpoint is declared, and the third builds $1/\sqrt{u(1-u)}$ from the endpoint distances. In the nested call the inner integral is requested at 26 digits, so that its error stays below the outer target of 20 plus the guard digits.
A parallel grid run that keeps the record. The self-test's grid test (in selftest.py, so __file__ is that file) integrates a module-level function by name over nproc workers:
pe = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
rec = nestor.oracle("nestor.selftest:pilot_integrand", 0, "0.5",
dps=D, md=6, nproc=nproc, f_bound=2,
path_entry=pe, log=lambda *a: None)
vf = mp.mpf(rec["value"])
The string names $e^u\cos 3u$ so the workers can import it, and path_entry is the directory they need on sys.path (here tools/). md=6 sets the grid level, f_bound=2 bounds $|f|$ for deciding where the node list may stop, and log silences the progress lines. rec["rungs"][0] holds the level, the node count (541) and the level-5-against-6 agreement (46.8 digits).
A dispersion integral with two thresholds. The test in tests/test_dispersion_surrogate.py integrates an inexpensive stand-in density rho against the kernel K, equal to $1/(w'+0.7)^2$, up to the cutoff WINF = 40. The density has a $(w'-1)\log(w'-1)$ turn-on at $w'=1$ with coefficient A and a $\sqrt{w'-9}$ onset at $w'=9$ with coefficient D. The panel list and call are
from nestor.dispersion import disp_subtracted
panels = [
{'a': 1, 'b': 9, 'thresh': ('left', 1, [(A, mp.mpf(1), 1)]),
'sub_width': mp.mpf('0.5'), 'radius': mp.mpf('0.6')},
{'a': 9, 'b': WINF, 'thresh': ('left', 9, [(D, mp.mpf('0.5'), 0)]),
'sub_width': mp.mpf('0.5'), 'radius': mp.mpf('0.6')},
]
J = disp_subtracted(rho, K, panels, dps=30, maxdegree=5)
The first panel declares one singular term at its left end, $w_\ast=1$ (coefficient A, power 1, one logarithm), subtracted over a sub-panel of length 0.5 with the kernel expanded within radius 0.6. The second declares the square-root onset at $w_\ast=9$ (power 1/2, no logarithm). J is $(1/\pi)\int\rho K$ with the tanh-sinh level fixed at 5, and the test requires it to match an adaptive tanh-sinh reference to at least 30 digits (it reaches 46).
A physical kernel. The package includes one worked kernel, examples/box1_dilog.py. With tools/nestor/examples on the path,
from box1_dilog import box_closed_dilog, make_K value = box_closed_dilog(s, t, m2, M5, dps=40) K = make_K(s, t, m2, dps)
gives the box at one kinematic point to at least dps digits, and a memoized function K(w'), the same box with M5 equal to $w'$, ready to pass to disp_subtracted.
The kernel is the finite part of the one-loop box with massless external legs, three internal lines of squared mass m2 and one of squared mass M5, in the normalization of pySecDec. It covers $s\lt0$, $t\lt0$, $m^2\gt0$, $M_5\gt0$ with $u=-s-t\lt4m^2$ only and raises ValueError outside.
Routines
Commands are run from the repository root unless noted.
| Command | What it does |
|---|---|
python3 -m nestor.selftest [--nproc N] [--receipt PATH] | The thirteen checks, run from tools/; --receipt writes the JSON record of the run |
python3 -m pytest tools/nestor/tests -q -p no:cacheprovider | The four dispersion checks alone, under pytest |
python3 tools/nestor/tests/test_dispersion_surrogate.py | Prints the digits that Gauss–Legendre, tanh-sinh with panel breaks alone, and the subtracted assembly each reach |
python3 tools/nestor/examples/box1_dilog.py | Compares the box kernel with the reference script box1_closed.py, which is not in the repository |
The last command looks for the reference script in the directory named by BOX1_DILOG_ORACLE_DIR. Without it the command prints SKIP and exits 0.
The Python module is loaded with import nestor, with tools/ on sys.path.
| Function | What it returns |
|---|---|
nestor.integrate(f, a, b, dps=, spec=, md=, nproc=) | The value at dps agreed digits as an mpf (mpc if complex), or a NestorRefusal exception |
nestor.oracle(...) | The same run as a record dictionary; receipt_path= also writes it to disk |
nestor.singcheck(f, a, b, spec) | The endpoint check alone: slope and samples per endpoint, or SpecRefusal |
nestor.farm_integrate(spec, a, b, dps, md, nproc) | One grid at level md over a process pool: value, value_lo (level md-1), selfcons_digits, nodes and the worker ids |
nestor.farm_campaign(spec, points, out_path) | farm_integrate over a list of configurations, with a JSON checkpoint saved after each; a rerun skips those done |
nestor.wp_for(D), nestor.inner_tol_exp(D) | The working precision for a D-digit request, and the tolerance exponent to ask of an inner integral |
nestor.probe, nestor.EnvEvaluator, nestor.quad_probe | Gatekeeper's probes.quad_probe: the digits gained per quadrature level, read before a long run |
With raise_on_refusal=False, nestor.oracle returns the record on a failed check; an abort is always raised. Every exception is a subclass of NestorRefusal and carries .exit_code. Exit codes are 0 for success, 3 for a failed check and 4 for a missing dependency or an integrand that cannot be imported (2 is reserved). A SIGTERM during a run becomes AbortRefusal, and an exception inside the integrand becomes EvalRefusal with the original attached. The lower-level names, among them cert_quad and ladder, are listed in __all__ in __init__.py.
Each entry of points in nestor.farm_campaign is a dictionary with a, b, dps, md and an optional nproc.
The dispersion module is loaded with from nestor.dispersion import ..., with tools/ on the path.
| Function | What it returns |
|---|---|
disp_subtracted(rho, K, panels, dps, kernel_nmax, maxdegree) | The full subtracted assembly, $(1/\pi)\int\rho K\,dw'$ as an mpf |
moment_powerlog, kernel_taylor, addback_endpoint, tanhsinh_panel | The parts of the assembly: the closed-form moments, the Taylor coefficients of the kernel, the exact $\int S\,K$ and the panel quadrature |
box_closed_dilog(s, t, m2, M5, dps), make_K(s, t, m2, dps) | From box1_dilog, with tools/nestor/examples on the path: the box at one kinematic point, and a memoized kernel K(w') for disp_subtracted |
rho and K are Python callables. Each panel is a dictionary with 'a', 'b', 'thresh', 'sub_width' and 'radius'. 'thresh' is None, or a tuple of the side ('left' or 'right'), the threshold $w_\ast$ and a list of terms (c, alpha, m). The coefficients c are known in closed form, or fitted from a few accurate values of $\rho$ near the threshold. A last panel with 'map': 'tail' covers $[a,\infty)$. maxdegree fixes the tanh-sinh level, and kernel_nmax sets the order at which the Taylor series of the kernel is cut.
Used on this site
- Modular graph functions: evaluated thirty-eight of the functions directly as integrals over the torus, with no sector expansion, as a numerical check of the exact results.
- Light-by-light box with a kite insertion: the dispersion integral over $w$, with the threshold behavior of the density subtracted and restored analytically.
- QED light-by-light graphs with a kite self-energy: the dispersion integral over $w$, with the threshold behavior of the density subtracted and restored in closed form.
- Light-by-light box with a sunrise insertion: the subtracted dispersion integral over the sunrise cut against the one-loop box kernel.
- Light-by-light box with a vacuum-polarization insertion: quadrature of the dispersion integral with the threshold behavior at $w'=m^2$ subtracted analytically.
Requirements
- Runs on: Python 3 with
mpmath. Parallel runs use the standardmultiprocessingmodule, and the dispersion module needs nothing beyondmpmath. - Install: nothing is built. Run from the repository's
tools/directory or put it onsys.path. The package has no hard-coded paths. - Self-test:
python3 -m nestor.selftestfromtools/. The last line reads13/13 controls passedand ends inPASS, with exit status 0. From the repository root,python3 run_selftests.py nestorruns the same checks and prints aPASSline fornestor. - Optional:
nestor.probeneeds Gatekeeper beside Nestor (tools/gatekeeper/) and raisesMissingRefusalwithout it.
Source and references
The code is tools/nestor/ in the BootLoops repository: the integrator modules at the top, the dispersion module in dispersion/, the box kernel in examples/ and the dispersion tests in tests/. The probe it re-exports is tools/gatekeeper/probes/quad_probe.py.
| Reference | What it supplies |
|---|---|
| H. Takahasi and M. Mori, Publ. RIMS Kyoto Univ. 9 (1974) 721, doi:10.2977/prims/1195192451 | The tanh-sinh (double-exponential) quadrature rule |
| F. Johansson and the mpmath contributors, mpmath | The arbitrary-precision arithmetic, the tanh-sinh rule of the serial route, and the loop that cert_quad follows |
| Bailey, Jeyabalan and Li, Exp. Math. 14 (2005) 317 | The use of tanh-sinh quadrature for integration at very high precision |
| Kahaner, Monegato, and Davis and Rabinowitz | The classical singularity subtraction, specialized here to a dispersion integral with an analytic kernel |