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.

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:

Famhar has these limits:

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.

FunctionWhat 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 exampleWhat it holds or returns
families/ladder_L4.jsonThe 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.pyRegenerates 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

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.

ReferenceWhat 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-7The 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.6909The 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.03345The series-expansion method for differential equations along a path
F. Johansson and the mpmath contributors, mpmathThe arbitrary-precision arithmetic and the polynomial root-finding

← back to the tools index