Famhar

The content on this page was written by AI under human supervision.

Famhar evaluates a whole family of Feynman master integrals from one configuration file. The file states the differential equation the integrals satisfy, a starting point where their values are known, the functions whose zeros are the branch points, and how the physical target functions are built from the masters. You give it a path from the starting point to the point you want and a number of digits. It returns the target values there, their first derivatives, and a record of which sheet of the multivalued functions the path selected; a closed path gives the monodromy.

What it does

The master integralsa finite basis of integrals in terms of which every integral of the family can be written; they satisfy a closed system of linear first-order differential equations $J=(J_1,\dots,J_n)$ of a family depend on two chart variables, 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. Solving the system numerically means carrying $J$ from a point where it is known to the point of interest along straight segments between waypoints. Famhar rewrites each 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 its roots in $t$ are found numerically, each root contributing one pole. The system is handed to Wayfinder, which integrates it 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 with the result.

The integrals are multivalued, with branch points wherever a letter vanishes, so the answer depends on how the path winds around those points. Famhar tracks the continuous change of each letter's complex argument along the path, never reducing it to the principal range, and reports the total winding and the continued $\log\ell$ at the endpoint. A path that crosses a cut therefore 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. When testing a loop, derive the expected monodromy from the functions themselves; because of path ordering, $\exp(2\pi i\,M_\ell)$ is in general not the monodromy of the transported vector.

Before integrating a segment, Famhar measures how close each letter comes to zero along it, relative to the letter's size at the ends. Below the configured clearance_min it stops with an error that names the segment and the letter and asks for a detour waypoint in the complex plane; a waypoint exactly on a branch point is also 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 refused too. Waypoints for such a family must be exact rationals (strings, integers or Fractions), never floats. 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 dimensional-regularization parameter $\epsilon$ stays at the file's fixed eps0; there is no Laurent expansion in $\epsilon$.

The family file is JSON; its schema is in the package README. 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", converted only inside the working precision. A second format, connection_rational, covers connections that are general rational functions: one checksummed JSON file per differentiation variable with sparse entries as exact numerator and denominator polynomials, and extra file variables such as the dimension d fixed through subs. Denominator zeros then serve as the singular and branch points, with the same clearance check and winding record. This route refuses with SYSTEM_NOT_CLOSED when an entry refers to a function whose own equation is missing from the block, since integrating a non-square system would invent a solution; genuinely zero rows must be declared in the files' zero_rows list.

The tail bound controls the truncation of each Taylor step, but the digits of a final value are established by agreement: 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 an independent value where one exists. Before trusting a new family file, test it on a point with an independently known value, on a loop around nothing (which must return the starting vector) and on a loop around one branch point with a known monodromy. Current limits: affine or polynomial letters with $\epsilon$-independent rational dlog entries; two chart variables and two invariants; first derivatives only. The file layout is meant to carry an elliptic family through its starting-values function, but no elliptic family is included. Evaluation is done from Python; the only command-line entry point runs the self-tests. The package includes one complete worked family: the Usyukina–Davydychev four-point ladder integrals $\Phi^{(1)},\dots,\Phi^{(4)}$, whose known closed forms make every check free. Its file is families/ladder_L4.json, its closed-form starting-values module is ladder_reference.py, and build_ladder_config.py regenerates the file; use them as the pattern for a family of your own. Expect roughly 3 seconds per Taylor step for a 65-function family at 40 digits, with cost growing roughly as the 1.7 power of the digit count, so time one short segment before asking for 100 digits or more.

Examples

One evaluation. Working in the tools/famhar/ directory, load the included ladder family, get the starting vector from the plugin named in its file (ladder_reference.anchor_values), and evaluate the target Phi4 at the end of a path. The code is the usage block from the package README, pointed at that file:

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"} (rational strings; a complex detour waypoint is written like "1/2+1/3i") beginning at the file's starting point (its anchor block). In res["sheet"], windings is each letter's total change of argument, log_letters the continued logarithms at the endpoint, diags Wayfinder's step count and worst tail bound per segment, and clearances each segment's closest approach to a branch point; res["J"] is the transported vector. A segment that fails the clearance check raises ValueError whose message contains REFUSED and asks for a complex detour waypoint.

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 (points already converted with parse_point are also accepted when every letter is affine):

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, confirming the loop enclosed the intended branch point only.

A rational connection block. For a family whose file declares a connection_rational block (the included ladder family does not), stored as checksummed rational-function files with the dimension d as an extra variable, fixed 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"})

Waypoints must be exact rationals here; a float is refused. closure_census() reports whether the block is square, and march_rational refuses unless it is. rec carries windings and log_dens keyed by denominator, plus closure and provenance (the verified checksums). A_rational_at evaluates the sparse matrices at a point and is allowed on a block that is not square.

Routines

Command line

Loading and points

Evaluation along a path (dlog connection)

Rational connection blocks

The ladder example family

Requirements and source

Python 3 with mpmath (and pytest for the test directory). Famhar imports Wayfinder from the neighboring tools/wayfinder/ directory by putting the parent tools/ folder on the import path, so the two packages must sit side by side as they do in the repository; there is no install step. Self-tests: python3 tools/famhar/famhar.py --selftest, run from the repository root, takes a few seconds. It checks a straight transport against closed forms, an identity loop, a branch-point loop against the exact monodromy, a polynomial letter, the refusals, and the sheet of the ladder family's master $\log(ab)$, then prints [famhar selftest] PASS_ALL with exit code 0. Exit code 1 means a named check failed; 2 means a part was skipped because ladder_reference.py or its record file is missing. python3 -m pytest tools/famhar/tests -q runs the longer ladder sheet tests. Code: tools/famhar/ in BootLoops' bootloops-dev repository (GitHub organization BootLoops-ai), released under the MIT license, with the configuration schema in its README.md and a short reference card in GUIDE.md. Related page: Wayfinder.

← back to the tools index