Famhar
Famhar evaluates a whole family of Feynman master integralsa finite basis of integrals in terms of which every integral of the family can be written along a path, from one configuration file. Given the path and a number of digits, it returns the target valuesthe values of the physical functions built from the masters, as the configuration file says at the endpoint, their first derivatives, and a record of the sheet (branch) of the multivalued functions that the path selected. The integration is done by Wayfinder, and the worked family is the ladder integrals of Ussyukina and Davydychev in the closed form of Drummond, Duhr, Eden, Heslop, Pennington and Smirnov (arXiv:1303.6909).
What it does
The master integrals $J=(J_1,\dots,J_n)$ of a family depend on two chart variablesthe two variables in which the differential equation is written, say $(a,b)$, and satisfy a linear system in "dlog" form,
$$\mathrm{d}J=\Big(\sum_{\ell}M_\ell\,\mathrm{d}\log \ell(a,b)\Big)J .$$
Each letter $\ell$ is an affine function $c_0+c_a a+c_b b$ or a polynomial in the chart variables, and each $M_\ell$ is a sparse matrix of exact rationals.
The evaluate call carries $J$ from a point where it is known to the point of interest along straight segments between waypoints. It does four things on each segment and a fifth at the endpoint.
- Check. It measures how close each letter comes to zero along the segment, relative to the letter's size at the ends. Below the configured
clearance_minit stops with an error that names the segment and the letter and asks for a complex detour waypoint. - Restrict. It rewrites the segment exactly as a one-variable system in $t\in[0,1]$ with simple poles at known $t$. An affine letter contributes one pole in closed form. A polynomial letter is composed exactly along the segment, and each numerically found root in $t$ contributes one pole.
- Integrate. Wayfinder integrates the system by high-order Taylor steps sized by the distance to the nearest pole. Each step is accepted against a bound on the neglected tail of the series, and the worst bound per segment is returned.
- Record. It tracks the continuous change of each letter's complex argument, never reducing it to the principal range, and reports the total winding and the continued $\log\ell$ at the endpoint.
- Differentiate. Target derivatives come exactly from the connection matrix applied to $J$ plus the derivative of the target's prefactor, then through a $2\times2$ Jacobian to two kinematic invariants. No finite differences are taken.
The integrals are multivalued, with branch points wherever a letter vanishes, so the answer depends on how the path winds around those points. A path that crosses a cut ends on the correct sheet, where principal-branch logarithms would be wrong by exactly the discontinuity. A closed path gives the monodromythe linear transformation a basis of solutions undergoes when carried once around a branch point and back: the vector after the loop, to compare with the vector before.
The configuration file, called the family file below, is JSON. It holds the differential equation, a starting point where the values are known, the letters, and how the target functions are built from the masters. The starting values come from a Python function you write, func(point, dps, masters), named in the file's anchor.values_plugin entry by its dotted module path. Every number in the file is an exact rational string such as "1/8" or "1/2+1/3i". Another file format, for connections that are general rational functions, is shown in the third example.
The tail bound controls the truncation of each Taylor step, but the digits of a final value are established by agreement. Make these checks:
- Run each evaluation at two working precisions (the package's own tests use 50 and 80 digits), keep the digits that agree, and compare with a value computed another way where one exists.
- Test a new family file on a point whose value is known from elsewhere and on a loop around nothing, which must return the starting vector.
- Test it on a loop around one branch point, with the expected monodromy derived from the functions themselves. Because of path ordering, $\exp(2\pi i\,M_\ell)$ is in general not the monodromy of the transported vector.
Famhar has these limits:
- Letters are affine or polynomial, and the dlog entries are rationals that do not depend on $\epsilon$.
- Two chart variables and two invariants; first derivatives only.
- The dimensional regularizationspace-time is continued to d = 4 − 2ε dimensions; results are Laurent series in ε parameter $\epsilon$ stays at the file's fixed
eps0. No Laurent expansion in $\epsilon$ is made. - A waypoint exactly on a branch point is an error. For a polynomial letter the clearance is the distance of its nearest root from the segment, so a segment whose root-finding fails is an error too.
- Waypoints for a family with a polynomial letter must be exact rationals (strings, integers or
Fractions), never floats. - The file layout is meant to carry an elliptic family through its starting-values function, but no elliptic family is included.
- Run time grows with the number of digits, so time one short segment before asking for 100 digits or more.
The package includes one complete worked family, the four-point ladder integrals $\Phi^{(1)},\dots,\Phi^{(4)}$ of Ussyukina and Davydychev, whose closed forms are known. Its files are listed under Routines; use them as the pattern for a family of your own.
Examples
One evaluation. With the package in place (see Requirements), work in the package directory tools/famhar/. Load the included ladder family, get the starting vector from the function named in its file, and evaluate the target Phi4 at the end of a path:
import famhar, importlib
fam = famhar.Family.from_json("families/ladder_L4.json")
# anchor values come from the plugin named in the config
mod, fn = fam.cfg["anchor"]["values_plugin"].rsplit(".", 1)
anchor = fam.parse_point(fam.cfg["anchor"]["point"], dps + 15)
y0 = getattr(importlib.import_module(mod), fn)(anchor, dps + 15, fam.masters)
res = fam.evaluate(path_spec, y0, dps) # path_spec = [anchor_pt, ..., end_pt]
res["targets"]["Phi4"]["value"] # value at the end point, on this sheet
res["targets"]["Phi4"]["d_chart"] # d/da, d/db (A.J + prefactor rule)
res["targets"]["Phi4"]["d_kin"] # d/du, d/dv (config's 2x2 Jacobian)
res["sheet"] # per-letter winding + continued logs
# + per-segment transport diagnostics
dps is the number of decimal digits wanted. path_spec is a list of point dictionaries such as {"a": "1/8", "b": "1/9"}, beginning at the file's starting point (its anchor block); a complex detour waypoint is written like "1/2+1/3i". res["J"] is the transported vector. A segment that fails the clearance check raises ValueError with REFUSED in its message.
A monodromy loop. To see how the masters transform around one branch point, integrate along a closed list of waypoints that encircles the zero of one letter. march takes the same point dictionaries as evaluate:
J_end, rec = fam.march(closed_loop, y0, dps) # closed_loop[0] == closed_loop[-1], y0 = J there
Comparing J_end with y0 gives the monodromy on this basis. rec["windings"] should read $\pm2\pi$ for the encircled letter and zero for the rest, which confirms that the loop enclosed the intended branch point only.
A rational connection block. A family file can declare a connection_rational block: one checksummed JSON file per differentiation variable, with sparse entries as exact numerator and denominator polynomials. The included ladder family has no such block. Extra file variables such as the dimension d are fixed through subs, here to $d=28/5$:
rc = fam.load_connection_rational() # verifies every file's sha256 checksum
rc.closure_census() # {..., 'closed': True}
J_end, rec = fam.march_rational(path_spec, y0, dps, subs={"d": "28/5"})
A = fam.A_rational_at(point, dps, subs={"d": "28/5"})
Denominator zeros serve as the singular and branch points, with the same clearance check and winding record, and waypoints must be exact rationals (a float is an error). march_rational stops with SYSTEM_NOT_CLOSED when an entry refers to a function whose own equation is missing from the block. Rows that are zero must be declared in the files' zero_rows list.
Routines
Everything is called from Python after import famhar; the only command-line entry point runs the self-tests.
| Function | What it returns |
|---|---|
Family.from_json(path), Family(cfg) | A Family from a family file, or from a parsed dictionary |
Family.parse_point(pt, dps), Family.parse_point_exact(pt) | The point as complex values at working precision, or as exact rationals |
Family.evaluate(path_spec, y0, dps) | Target values, chart and kinematic derivatives, the sheet record and the transported vector |
Family.march(waypoints, y0, dps) | (J_end, record) along a list of waypoints; use it for closed loops |
Family.load_connection_rational() | A RationalConnection from the files named in the family file, after verifying each checksum |
RationalConnection.closure_census() | Row and column coverage of the block, and whether it is square |
Family.march_rational(path_spec, y0, dps, subs) | (J_end, record) for the rational block along exact waypoints |
Family.A_rational_at(point, dps, subs) | The sparse connection matrices at a point; also works on a block that is not square |
The record of march, which evaluate returns as res["sheet"], holds windings, each letter's total change of argument, and log_letters, the continued logarithms at the endpoint. It also holds diags, Wayfinder's step count and worst tail bound per segment, and clearances, each segment's closest approach to a branch point. The record of march_rational has log_dens, keyed by denominator, in place of log_letters, and adds closure and provenance (the verified checksums). march_rational also stops with an error on a file variable missing from subs, a checksum mismatch or insufficient clearance.
The lower-level methods of Family and RationalConnection are defined in famhar.py.
| Ladder example | What it holds or returns |
|---|---|
families/ladder_L4.json | The family file: 65 masters, letters a, one_minus_a, b, one_minus_b, targets Phi1 to Phi4, kinematic variables u, v |
ladder_reference.anchor_values(point, dps, masters), basis_values(a, b, dps, masters) | The starting vector named in the family file, and the closed-form basis vector at any chart point |
ladder_reference.phi_value(L, a, b, dps), phi_derivs_chart(L, a, b, dps) | Closed-form $\Phi^{(L)}$ and its chart derivatives, the values to compare a transport against |
ladder_reference.default_ell_k(a, b, dps), ell_sheet(a, b, dps) | The sheet of the master $\log(ab)$ that the closed forms use at a point |
build_ladder_config.py | Regenerates families/ladder_L4.json with exact rational entries |
By default the closed forms use the principal branch of the product in $\log(ab)$; cont={'ell_k': k} selects another sheet.
Requirements
- Runs on: Python 3 with mpmath, and pytest for the test directory.
- Install: no install step is needed. Famhar imports Wayfinder from the neighboring
tools/wayfinder/directory, so the two packages must sit side by side as they do in the repository. - Self-test:
python3 tools/famhar/famhar.py --selftest, run from the repository root, takes a few seconds. It prints a line beginning[famhar selftest] PASS_ALLand exits with code 0. Exit code 1 means a named check failed; 2 means a part was skipped becauseladder_reference.pyor its record file is missing. - Longer tests:
python3 -m pytest tools/famhar/tests -qruns the longer ladder sheet tests.
Source and references
The code is tools/famhar/ in the BootLoops repository, released under the MIT license. The configuration schema is in its README.md and a short reference card in GUIDE.md.
| Reference | What it supplies |
|---|---|
| N. I. Ussyukina and A. I. Davydychev, Phys. Lett. B 298 (1993) 363, doi:10.1016/0370-2693(93)91834-A; Phys. Lett. B 305 (1993) 136, doi:10.1016/0370-2693(93)91118-7 | The ladder integrals of the worked family |
| J. Drummond, C. Duhr, B. Eden, P. Heslop, J. Pennington and V. A. Smirnov, JHEP 08 (2013) 133, arXiv:1303.6909 | The closed form of the ladder functions, eqs. (2.2) and (2.3), used in ladder_reference.py |
| F. Moriello, arXiv:1907.13234; M. Hidding, DiffExp, arXiv:2006.05510; T. Armadillo, R. Bonciani, S. Devoto, N. Rana and A. Vicini, SeaSyde, arXiv:2205.03345 | The series-expansion method for differential equations along a path |
| F. Johansson and the mpmath contributors, mpmath | The arbitrary-precision arithmetic and the polynomial root-finding |