Frobenius

Frobenius finds the non-integer powers with which the solutions of a Feynman-integral differential equation behave at infinite mass, and decides which of them the physical solution can contain. Its purpose is to cut down the number of unknown boundary constants (the constants of integration that select the physical solution) before any expensive numerical evaluation. Its two companions are asdminer, which mines the congruences of Atkin and Swinnerton-Dyer, and deform_transport, which implements the deformation method of Dwork and Lauder as given by Candelas, de la Ossa and van Straten (arXiv:2104.07816).

What it does

A family of Feynman integrals reduces to a finite set of master integralsa basis of independent integrals to which every integral of the family reduces through integration-by-parts identities $M_k(x)$, which obey a system of linear differential equations in a kinematic variable $x$, here a squared mass. Solving the system numerically means carrying a known solution from one point to another, and $x\to\infty$ is a convenient start because the integrals usually have a simple large-mass expansion there.

On a maximal cutthe version of the integral with every propagator put on its mass shell; it obeys the homogeneous part of the same differential equation that can fail: the naive large-mass value vanishes and the solution is not analytic at infinity. It is instead a combination of Frobenius branches, solutions of the form $x^{\lambda}$ times a series in $1/x$, one per allowed exponent $\lambda$, each with its own free constant.

The frobenius_boundary package reads an integration-by-parts reduction table and a list of master integrals, and works in five steps.

The surviving constants $c$ are fixed afterward, outside this package, by a small linear solve $R\,\Phi\,c = O$ against a few numbers known by other means.

The decision step uses these rules:

Resonances (exponents differing by integers) are treated by a minimum-norm solve that sets log_branch_required if a logarithmic term would be needed. A non-Fuchsian system (a nilpotent block $D_0$ ahead of $D_1$ that is not fitting noise) is first brought to Fuchsian form by an exact shear reduction of Moser's type. The driver then classifies the eigenvalues of the reduced residue and records the frame in classification_frame.

The package has these limits:

The two companions concern the Frobenius mapthe map raising coordinates to the p-th power; its characteristic polynomial determines the number of points over F_p and every extension field of a differential operator reduced modulo a prime $p$.

asdminer takes an exact integer or rational series $a(n)$, a prime $p$ and a weight $k$. It solves the three-term Atkin–Swinnerton-Dyer congruences $a(np) - \gamma_p\,a(n) + p^{k-1}\,a(n/p) \equiv 0 \pmod{p^s}$ for a single $\gamma_p$. For each prime it reports one of four outcomes: a single $\gamma_p$ fits every congruence, the congruences disagree, they are underdetermined, or $p$ divides a denominator and nothing can be read.

classify_gamma then separates a modular $\gamma_p$ from the trivial unit-root value (the root that is a $p$-adic unit). Every series shows that value at a degenerate point of a family, and it is not evidence of modularity.

deform_transport implements the deformation method of Dwork and Lauder for the Frobenius matrix of a differential operator, in the form given for Picard–Fuchs operators by Candelas, de la Ossa and van Straten (arXiv:2104.07816). It carries the full Frobenius matrix along a one-parameter deformation and returns the complete local factor at $p$ (the polynomial that the prime $p$ contributes to the L-function), an integer characteristic polynomial.

The polynomial is checked against the functional equation and the Weil bounds (the bounds on the size of its roots), and must agree under two separate truncations.

Two public programs apply the same method to Calabi–Yau operators: CY3Zeta, by Candelas, de la Ossa and Kuusela (arXiv:2405.08067), and PFLFunction, by Kuusela, Lathwood, Mosso Rojas and Stepniczka (arXiv:2604.01191).

Run asdminer first: deform_transport costs far more.

Examples

Run all five steps from a configuration file. With the package set up (see Requirements), copy frobenius_boundary/config_example.json, point kira_targets_m at your kira2math table and masters at your preferred-masters list. Set var, mass_slots, n_loops, eps_list, dps, branch_n_terms and Mstart, then run from the package directory tools/frobenius-boundary/:

python3 -m frobenius_boundary.cli config.json

The driver runs the $\varepsilon$ values in parallel (ncpu) and prints a [cli] wrote ... line for each file. <out_dir>/SPECTRUM_<tag>.json holds the eigenvalues at each $\varepsilon$, the classified families (groups, each with a, b, mult and class), the trace check, and the counts n_free_constants, n_killed, n_flagged. When branch_n_terms is nonzero, <out_dir>/BRANCHES_<tag>.json holds each branch's series coefficients and resonance report and, if Mstart was set, Phi.

Classify a hand-built spectrum. From tools/wayfinder/tests/test_boundary_branches.py, which needs no data files. bb is Wayfinder's boundary_branches module, which forwards each call unchanged to frobenius_boundary.core:

eps_list = ["1/101", "1/103", "1/107", "1/109"]
with mp.workdps(60):
    EVs = []
    for e in eps_list:
        _dd_rat, _dd, ev = bb.eps_to_d(e)
        EVs.append([1 - 2 * ev, mp.mpf(1) / 2 + ev / 2, mp.mpf(3)])
    fams, groups = bb.classify(EVs, eps_list, kill_integer_eps_indep=True)
with mp.workdps(60):
    ex = bb.exclude_strata(groups)
assert ex["n_free_constants"] == 2, ex["n_free_constants"]
assert ex["n_killed"] == 1

Three exponents are given at four values of $\varepsilon$: $1-2\varepsilon$, $\tfrac12+\tfrac12\varepsilon$ and the constant $3$. The first two groups carry class RATIONAL_LINEAR__SURVIVES_pinch and the integer one INT_EPS_INDEP__KILLED_vacuum_theorem, because kill_integer_eps_indep=True was passed, so exclude_strata counts two free constants and one excluded branch. The calls sit inside mp.workdps(60) because several entry points take their precision from the ambient mpmath setting.

Run the acceptance test.

cd tools/frobenius-boundary && python3 -m frobenius_boundary.selftest

The test reads the configuration named by FROB_CONFIG (default config_example.json). The reference reduction table is not distributed, so on a fresh clone the test stops with exit code 4 and a message naming the missing kira_targets_m path. With a table in place it prints a [PASS] or [FAIL] line per check, ends with SELFTEST PASS or the list of failures, and writes SELFTEST_VERDICT.json.

The expected values are the reference family's, so a different table exercises all five steps but reports FAIL on the comparisons.

Run the self-tests of the two companions. Both run on a fresh clone, from the same directory:

python3 asdminer/run_control.py
python3 deform_transport/battery/run_battery_deform.py --stages S0,S1

The first prints VERDICT: and control_pass = True, and writes asdminer/work/ASD_CONTROL.json. The second transports the rank-2 Legendre family at $p=23$ and $p=29$, where the answer is a known theorem, and prints a BATTERY VERDICT: line beginning FAST-TIER-GREEN.

Routines

All commands are run from tools/frobenius-boundary/. The companions write to asdminer/work/ and to deform_transport/work/ or deform_transport/battery/work/.

CommandWhat it does
python3 -m frobenius_boundary.cli config.jsonRuns the five steps; writes SPECTRUM_<tag>.json and BRANCHES_<tag>.json
python3 -m frobenius_boundary.selftestAcceptance test against the reference family's expected numbers
python3 asdminer/run_control.pySelf-test of the congruence miner: series with proven congruences must pass; a corrupted series and a structureless one must be rejected
python3 asdminer/run_l6_gauge.py, run_l6_mine.py, run_l6_topup.pyMiners driven by the FROB_L6_OPERATOR file
python3 deform_transport/battery/run_battery_deform.py [--stages S0,S1,...]Self-test of the matrix transport, stages S0 to S4; a full run writes BATTERY_RECEIPT.json

Stage S0 rebuilds the order-6 operator used as the rank-6 control and S1 is the rank-2 control. The other stages are S2 to S4: S3 needs S1, and S4 needs FROB_L6_OPERATOR.

The functions of the five steps are in frobenius_boundary.core. The first six are also importable from the package itself.

FunctionWhat it returns
build_poly_DE(kira_targets_m_path, masters, var=, eps=, mass_slots=)(D, G, fit_err_log10), the exact polynomial system from a Kira table; extras in core.LAST_BUILD
spectrum(D, G, ai, eps, n_loops)The expansion at infinity, the residue matrix D1 and its eigenvalues
classify(exponents, eps_list, kill_integer_eps_indep=)(families, groups): the fit $\lambda=a+b\varepsilon$ across the $\varepsilon$ lists, with a class per group
exclude_strata(groups, EVs=, eps_vals=)Surviving, excluded and flagged families, n_free_constants, and, when EVs and eps_vals are passed, the rationality scan behind each exclusion
branch_series(D, G, lambda_j, v_j, n_terms, ai=, eps=, n_loops=, seed_index=)The $1/x$ series of one branch, and a record with resonances, refine_rfinal, log_branch_required, reduce_failed
phi_matrix(Mstart, branch_list, ai, dd, n_loops)The $N\times J$ matrix of branch solutions at Mstart
seed_vectors(D1, lam)(V, dimension, residual): the null space of $D_1-\lambda I$, the seeds of branch $\lambda$
eps_to_d(eps)$d$ as a sympy rational, then $d$ and $\varepsilon$ as mpmath numbers
de_core.load_masters(path_or_list), de_core.alpha_int(basis)The masters list and their integer weights ai

mass_slots defaults to 0..7, so set it for your family. Pass the index of a column of V to branch_series as seed_index. The trace check and the Jordan data are trace_rule and jordan_info, and the table reader is kira_parse.parse_kira2math.

The companions' main functions are in asdminer/asdlib.py and deform_transport/code/deform_kit.py.

FunctionWhat it returns
asdlib.mine(aval, p, N, k)The outcome at one prime, the depth reached, $\gamma_p$ modulo $p^D$, any disagreeing congruences and the Weil-bound candidates
asdlib.classify_gamma(entry, D, k)A label for a mined $\gamma_p$: trivial (unit root or Eisenstein), non-trivial cuspidal, ambiguous or outside the cuspidal range
deform_kit.transport(op, p, K_true)The transport state; pinned_E, assemble_full_F, eval_F_at and berkowitz_charpoly then give $F(x)$ at a Teichmüller point and its characteristic polynomial
deform_kit.op_legendre(), op_sym5(path), op_L6()The Legendre, rank-6 control and order-6 operators, as input for transport
deform_kit.isolate_factor, gamma_normalizeThe integer local factor from the characteristic polynomial

The lower-level functions, among them the operator routines load_operator, frobenius_exact and frobenius_modular, are in the same two files and in deform_transport/code/lfact_kit.py. GUIDE.md in the package lists the other files of the two companions, the calibration scripts of deform_transport/code/ and the remaining environment variables.

The main environment variables are:

A related routine, richardson_boundary(partial_sums, Ms, tail_exponents) in the epslimit module of Wayfinder, sums a branch series at the edge of its disk of convergence by eliminating known $M^{-\alpha}$ tail powers from the partial sums.

Requirements

Source and references

The code is tools/frobenius-boundary/ in the BootLoops repository. Wayfinder's boundary_branches module wraps the same functions.

ReferenceWhat it supplies
Dwork; LauderThe deformation method that deform_transport implements
Pancratz and Tuitman, arXiv:1307.1250The deformation method
Candelas, de la Ossa and van Straten, arXiv:2104.07816The form of the method for Picard–Fuchs operators
Candelas, de la Ossa and Kuusela, CY3Zeta, arXiv:2405.08067A public program for the same method, for Calabi–Yau operators
Kuusela, Lathwood, Mosso Rojas and Stepniczka, PFLFunction, arXiv:2604.01191A public program for the same method, for Calabi–Yau operators
Atkin and Swinnerton-DyerThe three-term congruences that asdminer solves
Honda; BeukersThe proven congruences of the asdminer self-test (formal groups; Apéry numbers)
Moser (1960)The shear reduction of a non-Fuchsian system
The PARI Group, PARI/GPThe comparison values of the asdminer self-test

← back to the tools index