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 NestorSourceAuthors
Follows their code: the depth loop of cert_quad, which drives the serial routeQuadratureRule.summation in mpmath's calculus/quadrature.pyF. 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 routinesmpmathThe same authors
New code: the node list of the grid route, the stopping test, the endpoint check, the records and the dispersion moduleThe formulas of Takahasi and Mori, and the references under Source and referencesCode 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.

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.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.

CommandWhat 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:cacheproviderThe four dispersion checks alone, under pytest
python3 tools/nestor/tests/test_dispersion_surrogate.pyPrints the digits that Gauss–Legendre, tanh-sinh with panel breaks alone, and the subtracted assembly each reach
python3 tools/nestor/examples/box1_dilog.pyCompares 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.

FunctionWhat 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_probeGatekeeper'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.

FunctionWhat 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_panelThe 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

Requirements

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.

ReferenceWhat it supplies
H. Takahasi and M. Mori, Publ. RIMS Kyoto Univ. 9 (1974) 721, doi:10.2977/prims/1195192451The tanh-sinh (double-exponential) quadrature rule
F. Johansson and the mpmath contributors, mpmathThe 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) 317The use of tanh-sinh quadrature for integration at very high precision
Kahaner, Monegato, and Davis and RabinowitzThe classical singularity subtraction, specialized here to a dispersion integral with an analytic kernel

← back to the tools index