Appendix C: Computational Laboratory
A numerical value is reproducible only when three layers are recorded separately: the exact mathematical object, the finite algorithm used to approximate it, and the evidence supporting the reported digits. Increasing precision controls only part of the third layer. It cannot repair a wrong branch, a reversed connection matrix, an open lift mistaken for a cycle, or a discretized equation that differs from the intended continuum problem.
This appendix is a cross-method bench manual. It gives a common protocol for the book’s local-series, recurrence, monodromy, period, Borel–Padé, and TBA calculations, then links to the pages and programs where each method is developed in depth.
A frozen passport precedes every calculation
Section titled “A frozen passport precedes every calculation”Let be an exact scalar characteristic function, period, matrix entry, or nonlinear residual. Let be a finite approximation and its evaluation at working precision . At a computed candidate ,
The three rows are truncation or discretization error, arithmetic evaluation error, and nonlinear-solve residual. Conditioning is needed to turn their sum into an error in . A model or dictionary error is more basic: it changes itself and therefore does not belong in this additive budget.
The book uses the following evidence labels.
| Label | Minimum support |
|---|---|
| Computed | One declared finite algorithm returns a candidate |
| Internally converged | Independent controls such as cutoff, order, mesh, contour panels, and precision have stable refinement tables |
| Cross-verified | A representation with substantially different failure modes agrees under its own refinements |
| Certified | Outward-rounded bounds plus an inclusion, root-count, or uniqueness theorem prove the stated conclusion |
Physical or interpretive validation is an orthogonal question. A certified root of the wrong boundary problem remains the wrong observable.
Every method card should freeze five groups of data.
| Group | Required data |
|---|---|
| Object | Equation, exact parameters, gauge, normalization, boundary or connection datum |
| Analytic | Branches, cuts, path or contour, sheet, cycle, chamber, and lateral side |
| Finite model | Series order, recurrence depth, Padé shape, grid, panels, cutoff, and tail model |
| Arithmetic | Input provenance, working precision, guard digits, rounding, solver, and stopping norm |
| Evidence | Invariants, refinement table, conditioning estimate, independent representation, and claim label |
A useful planning estimate is
where estimates lost digits and is a guard margin. This is a budget, not a validation theorem.
Pathwise transport preserves an ordered frame
Section titled “Pathwise transport preserves an ordered frame”Write a linear ODE as
Along a declared path , , integrate
The path parameterization, initial ordered frame, and every rescaling belong to the result. A robust high-precision transport proceeds as follows.
- Seed a normalized local jet inside a certified or well-tested convergence disk, rather than directly at a singular point.
- Split the path before coefficient singularities, sharp bends, or regions where exponential separation exhausts the guard digits.
- Refine step size, method order, and precision independently. A last-term or step-doubling estimate is evidence unless a remainder theorem has been supplied.
- Rescale columns or use QR factorizations when necessary, but preserve the noncommuting factor order. If and a transport step gives , update : each new factor multiplies the accumulator on the left.
- Evaluate an off-mesh ODE residual and repeat the transport in reverse.
Arbitrary precision reduces roundoff; it does not validate the IVP solver. If a Taylor step is analytic on , a Cauchy bound can convert the local truncation into a proof. Without such a bound, order and step ladders remain convergence evidence.
Liouville’s formula supplies a cheap invariant. For transport from to ,
It detects many frame and integration failures, although a correct determinant does not determine the individual matrix entries.
Monodromy is endpoint transport around a loop
Section titled “Monodromy is endpoint transport around a loop”For a based loop and an initial frame , the house right action gives
Numerically solve the linear system rather than forming . If , the final transported frame is the monodromy matrix. The path product traverses first and then , so
Path ordering cannot be replaced by unless the coefficient matrices commute along the path. Audit a loop computation by checking
Liouville’s determinant, local nonresonant eigenvalues , the declared generator product, homotopic loop deformations, and simultaneous conjugation under a common frame change. Near a Jordan block, traces and determinants are much more stable than eigenvectors.
The global-data chapter fixes the path and matrix conventions. Its hypergeometric benchmark provides exact monodromy data against which a transport code can be calibrated.
Overlapping series turn local data into connection matrices
Section titled “Overlapping series turn local data into connection matrices”At a regular singular point, a normalized Frobenius branch has the form
Record the local coordinate, exponent lift, branch of , leading coefficient, recurrence, and analytic disk. Evaluate and from the same coefficient list. A proved ratio bound
gives the value-tail enclosure
This bounds the analytic factor . The full solution-tail bound carries the declared-branch multiplier . The derivative needs its own bound with and the additional factor.
Continue through overlapping Frobenius or ordinary Taylor disks, keeping each new center strictly inside the preceding analytic disk. In a common overlap the house direction is
Again, solve for rather than explicitly inverting a poorly conditioned frame. Move through the overlap, reverse the match, verify the Abel determinant, and compare with pathwise ODE transport. A drift with measures numerical error; it is not new connection data.
Local bases become global connection data only after their gauges, branches, derivative coordinate, and continuation paths agree. An independent match point tests every matrix entry, whereas the determinant supplies only one necessary invariant.
When exponent differences are integral, use a logarithmic Frobenius basis or a controlled resonant limit. Evaluating a nearly singular generic basis at more digits can still be far less stable than changing the basis first. The Frobenius and Leaver page derives the local recurrences, and the connection-matrix page develops the matching invariants.
Minimal recurrences impose a boundary condition at infinity
Section titled “Minimal recurrences impose a boundary condition at infinity”For a three-term recurrence
define
The backward Riccati map is
First establish the minimal-solution or continued-fraction theorem in the parameter domain of interest. Then seed a terminal approximation from large-order terms and sweep backward. A projective pair updates homogeneously as
with rescaling after every step. This chart survives values for which a scalar ratio overflows.
If the endpoint row is
the minimal-line residual is
Vary recurrence depth , tail order , working precision , terminal line, and any split index independently. Differentiate the terminal seed and every coefficient-dependent backward map when computing . Track ratio poles together with zeros: a pole of one projective chart need not be a spectral singularity.
A backward sweep and a Lentz evaluation mainly test arithmetic. A recurrence root and a direct ODE Wronskian have more independent failure modes. A finite depth becomes certified only after a tail enclosure has been propagated through the Möbius maps and a root-inclusion theorem has been applied. See the minimal-solution page, the continued-fraction page, and the large-order tail page.
Period quadrature must remain on the spectral cover
Section titled “Period quadrature must remain on the spectral cover”For
a projected contour is not enough. Store its orientation, initial sheet, cut crossings, lifted endpoints, and deleted poles. Along projected nodes , continue analytically; do not call an independent principal square root at each node. Away from turning points, a useful predictor is
after which the sign of closest to the predictor is chosen. This still requires step refinement and fails if used coarsely near .
At a simple branch point , set
Since ,
so the lifted integrand is regular in . For a cut cycle whose chosen bank runs from to ,
with the sign fixed by the sheet and orientation.
A numerical closed lift must return to the same and the same sheet. Audit path reversal, the deck involution, homology relations, contour deformation away from poles, residue jumps when a pole is crossed, and a known Weber or Mathieu closed period. An Airy calibration is instead a normalized relative action. Refine branch-point locations, panels, quadrature order, and precision separately. Picard–Fuchs or Gauss–Manin continuation is a valuable independent representation when available.
The spectral-cover page fixes the geometry, while the cycle and residue page and the regularized-period page explain which lifted forms may actually be integrated at each WKB order.
Borel–Padé separates continuation from quadrature
Section titled “Borel–Padé separates continuation from quadrature”For the shifted house convention,
From available coefficients construct a near-diagonal rational function
Use exact or guard-precision linear algebra, verify the matched Taylor coefficients, and inspect a triangle of nearby values. Stable poles, zeros, and residues are more informative than a single plot. A moving close pole–zero pair is often a Froissart defect; an alternating stable chain may represent a cut and must not be deleted automatically.
Before calling the result a Borel sum, verify analytic admissibility of the continued transform. If, for some and ,
then the actual Laplace integral requires
For the finite rational surrogate, a pole-free prescribed contour and the weaker condition with right-hand side zero suffice. Convergence of that surrogate integral alone does not prove that the original formal series is Borel summable in the direction.
For a declared ray and lateral side, evaluate
Record contour splits, pole clearance, quadrature rule, finite Laplace cutoff, and rational tail bound. Those bounds validate the integral of the chosen rational surrogate; they do not supply a generic bound on the unknown Padé continuation error. Separate coefficient, Padé-shape, contour, quadrature, and tail refinements.
The mandatory normalization tests are a monomial and the factorial one-pole model from Appendix B. The full Borel–Padé laboratory adds withheld-coefficient tests, lateral signs, root counts, and independent spectral determinants.
TBA residuals and continuum errors are different
Section titled “TBA residuals and continuum errors are different”Write a nonlinear integral equation schematically as
Freeze the logarithm sheet, integration contour and banks, source divisor, chamber, asymptotic subtraction, and observable before discretizing. Use Nyström panels on general contours. Use an FFT only when translation invariance justifies convolution, and zero-pad to the linear-convolution length rather than silently periodizing the line. Retain every quadrature weight and state whether is part of the kernel.
Let restrict a function to the grid, let reconstruct a function from grid data, and let be the computed grid vector. Set
Now both residuals live in the declared function space. Separate
from the continuum defect
If a complete declared set contains , , and is a contraction on with constant , then
A small discrete residual alone says nothing about cutoff, quadrature, FFT wrap, or logarithm-sheet error. Damping, Anderson acceleration, and Newton–Krylov methods may improve convergence but do not replace the invariant-set and contraction proof. Excited roots and divisor crossings belong to the nonlinear unknown rather than to post-processing.
Refine the left and right cutoffs, mesh, FFT padding or panel order, precision, nonlinear tolerance, bank offset, continuation step, and root tolerance independently. Compare dense and FFT multiplication on a smaller grid and evaluate an off-grid continuum residual. The TBA numerical laboratory derives these estimates and treats hard branches and excited roots.
Enclosures become conclusions only through a theorem
Section titled “Enclosures become conclusions only through a theorem”Ball arithmetic represents a set, for example , using outward-rounded operations. A narrow output ball encloses the desired exact value only if exact inputs, truncation tails, quadrature remainders, and every intervening operation have also been enclosed.
For a realified nonlinear system , suppose that is a box, , is nonsingular, and on a neighborhood of . Let the interval matrix enclose every Jacobian for . The Krawczyk operator is
If the strict inclusion
holds, then these hypotheses certify a unique zero in . Merely obtaining is not enough. For analytic scalar functions, Rouché or an argument-principle enclosure can certify a root count instead. The verified-numerics page develops tail balls, conditioning, Rouché, Krawczyk, and the distinction between backward and forward error.
A reproduction record should run without guesswork
Section titled “A reproduction record should run without guesswork”Archive the following fields with every publishable result.
| Group | Record |
|---|---|
| Mathematical object | Equation or operator, exact parameters, gauge, normalization, domain, and boundary data |
| Analytic choices | Branches, cuts, path or contour, sheet, cycle, chamber, and lateral side |
| Discretization | Orders, cutoffs, grids, panels, seeds, match or split points, and omitted-tail model |
| Arithmetic | Exact input strings, precision, guard digits, rounding mode, and coefficient provenance |
| Solve | Initial data, algorithm, tolerance norm, residual scale, derivatives, and conditioning estimate |
| Audits | Raw refinement table, invariant checks, unused coefficients, and independent representation |
| Environment | Code revision, exact command, interpreter, libraries, operating system, deterministic seeds, and thread count |
| Output | Raw data, checksums, reported digits, limitations, and evidence label |
Parse non-integer decimal inputs from exact strings. Promoting a binary64 number to a large multiple-precision container does not restore the digits already rounded away. Checks should raise explicit exceptions rather than language assertions that may disappear under optimized execution.
A quick connection-matrix micro-lab
Section titled “A quick connection-matrix micro-lab”The tested baseline is CPython 3.10 or later with mpmath==1.3.0; this
checker requires no other third-party package. From the repository root, run
python3 public/code/advanced-ode/general-heun-connection-check.py \ --t 0.04 --order 2 --terms 80 --dps 40 \ --no-table --check-second-pointThen repeat with --terms 160 --dps 80. In the baseline environment, the
match-point drift falls from about to
, while the Abel and direct determinants agree
at about . The fixed order-two block approximation has
a separate model error of about and therefore
does not improve with the series cutoff. The experiment distinguishes a
converging matching error from a deliberately frozen analytic truncation.
The repository contains a compact smoke suite.
| Workflow | Downloadable checker | Principal audit |
|---|---|---|
| Frobenius matching | general-heun-connection-check.py | Two match points and Abel determinant |
| Loop monodromy | classical-block-monodromy-check.py | Composite-loop trace and determinant at one declared step count; rerun with doubled --steps for refinement |
| Minimal recurrence and exact Bessel bracket | verified-numerics.py | Cutoff–tail–precision tensor and exact Bessel bracket |
| Lifted WKB actions | wkb-homology-action-check.py | Sheet sign, doubled lift, residues, and Gauss–Manin identity |
| Borel–Padé and spectra | borel-pade-spectral-check.py | Padé shapes, lateral jump, determinant, and root count |
| TBA iteration | tba-iteration-check.py | Dense-versus-FFT convolution and cutoff–mesh refinement |
Their source docstrings and linked pages state scope and limitations. Passing all of them validates the implementations on their declared benchmarks; it does not prove a new problem that merely resembles those benchmarks.
Common pitfalls
Section titled “Common pitfalls”Equating more digits with more evidence. Higher precision can reveal a truncation plateau, but it cannot bound an unproved tail or correct a wrong sheet. Refine the finite model and arithmetic independently.
Forming a matrix inverse because the formula contains one. Solve the linear system and monitor conditioning. Explicit inversion adds avoidable roundoff and hides which frame is ill-conditioned.
Recomputing principal square roots on a lifted contour. This can switch sheets without warning or fail to close a cycle. Continue the initial sheet and refine near every turning point.
Treating a discrete residual as a continuum residual. A nonlinear solver can solve the wrong finite grid to machine precision. Cutoff, quadrature, tail, and aliasing defects require separate estimates.
Calling two codes independent when they share the derivation. Rewriting the same recurrence in another language mainly tests transcription and arithmetic. Compare representations chosen for different failure modes.
Exercises
Section titled “Exercises”1. Transport a logarithmic frame
Section titled “1. Transport a logarithmic frame”For
use the ordered basis and a positive loop around zero. Determine the right-acting monodromy matrix, its determinant, and the matrix for the reverse loop.
Solution
The constant solution returns to itself, while
Therefore
Its determinant is one. This also follows from Liouville’s formula because in the companion system and
The reverse loop gives
A numerical transport should recover both loop matrices and make decrease under step and precision refinement.
2. Recover a minimal line backward
Section titled “2. Recover a minimal line backward”Consider
Starting from , apply the backward ratio map to obtain . Show explicitly that it converges to the minimal ratio.
Solution
The characteristic roots are and , so the minimal solution is proportional to and has ratio one. Here
After backward steps from zero,
This follows by induction. Taking gives
Forward recurrence would amplify any contamination by the dominant solution; the backward map selects the minimal line.
3. Smooth a branch-point panel
Section titled “3. Smooth a branch-point panel”Let with . On the bank above , choose and orient the bank from to . Use to evaluate the doubled cut-cycle period and explain why the endpoint quadrature is regular.
Solution
For ,
Thus the lifted integrand is the smooth function . The one-bank action is
The oppositely oriented return on the other sheet contributes the same value, so
Reversing the cycle or the initial sheet reverses the sign.
4. Convert a fixed-point residual into an error bound
Section titled “4. Convert a fixed-point residual into an error bound”Let be a complete invariant set, let be a contraction with constant , and let be a reconstructed discrete operator on the same function space. Suppose and and . Prove the bound used in the TBA section.
Solution
Let . Then
The first term is at most and the second at most . Moving it to the left gives
Without a proved invariant set and contraction constant, the same algebra is only a heuristic conditioning estimate.
5. Classify a high-precision spectral claim
Section titled “5. Classify a high-precision spectral claim”A program prints 60 stable digits of a recurrence root when the working precision is raised from 100 to 200 digits. It reports one depth , gives no tail remainder, uses no second representation, and archives neither branch data nor the command. Classify the claim and list the next controls needed before it can be called internally converged, cross-verified, or certified.
Solution
The result is computed with a precision refinement. It is not yet internally converged because recurrence depth, tail order, terminal line, split chart, and root-solver tolerance were not varied, and the analytic branch was not recorded.
Internal convergence requires those independent ladders, retained and first omitted recurrence residuals, conditioning information, and a complete passport. Cross-verification additionally requires a representation with different failure modes, such as endpoint-adapted ODE integration and an Abel-normalized Wronskian. Certification further requires outward-rounded coefficient and tail enclosures propagated to a Rouché, Krawczyk, or equivalent inclusion theorem. The exact command, code revision, dependency versions, inputs, and raw tables must be archived at every level.
References
Section titled “References”- NIST DLMF, §2.7 Differential Equations, §3.6 Linear Difference Equations, §3.7 Ordinary Differential Equations, §3.10 Continued Fractions, and §31.18 Methods of Computation, for the standard analytic and numerical reference formulae.
- À. Jorba and M. Zou, “A Software Package for the Numerical Integration of ODEs by Means of High-Order Taylor Methods”, Experimental Mathematics 14 (2005), 99–117.
- M. Mezzarobba, “NumGfun: a Package for Numerical and Analytic Computation with D-finite Functions”, ISSAC 2010, 139–145, and “Rigorous Multiple-Precision Evaluation of D-finite Functions in SageMath”, for pathwise series continuation and rigorous evaluation.
- W. Gautschi, “Computational Aspects of Three-Term Recurrence Relations”, SIAM Review 9 (1967), 24–82.
- P. Molin and C. Neurohr, “Computing Period Matrices and the Abel–Jacobi Map of Superelliptic Curves”, Mathematics of Computation 88 (2019), 847–888.
- G. A. Baker Jr. and P. Graves-Morris, Padé Approximants, second edition, Cambridge University Press (1996).
- P. Dorey and R. Tateo, “Anharmonic Oscillators, the Thermodynamic Bethe Ansatz, and Nonlinear Integral Equations”, Journal of Physics A 32 (1999), L419–L425.
- S. M. Rump, “Verification Methods: Rigorous Results Using Floating-Point Arithmetic”, Acta Numerica 19 (2010), 287–449.
- F. Johansson, “Arb: Efficient Arbitrary-Precision Midpoint-Radius Interval Arithmetic”, IEEE Transactions on Computers 66 (2017), 1281–1292, and “Numerical Integration in Arbitrary-Precision Ball Arithmetic”, ICMS 2018, 255–263.
- G. K. Sandve et al., “Ten Simple Rules for Reproducible Computational Research”, PLoS Computational Biology 9 (2013), e1003285.