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.
- Equation. It builds the exact polynomial system $D(x)\,dM/dx = G(x)\,M$ at fixed rational dimension $d = 4-2\varepsilon$ from a per-point Kira reduction table (kira2math format, every kinematic quantity other than $x$ already numeric).
- Exponents. It expands $x\,G/D$ at infinity and forms a residue matrix $D_1$ whose eigenvalues are the exponents.
- Fit. It repeats the first two steps at several values of $\varepsilon$ (two at least; four is the tested pattern) and fits each exponent as $\lambda = a + b\,\varepsilon$ with rational $a, b$.
- Decision. It sorts the families of exponents by the rules below.
- Branches. It builds the $1/x$ series of each surviving branch and evaluates them at a large starting value
Mstart. The result is an $N\times J$ matrix $\Phi$ whose columns span the space the physical solution lives in.
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:
- Rational-linear in $\varepsilon$: the exponent survives.
- Complex or irrational: excluded, because the physical large-mass expansion contains only powers $x^{p+q\varepsilon}$ with rational $p, q$.
- Integer and $\varepsilon$-independent: excluded only when
kill_integer_eps_indepis true, which asserts that a vacuum-integral reduction shows those terms vanish for your family. The Python functions default to true, so passFalseunless you have that check. The example configuration sets it to false. - Other rational $\varepsilon$-independent: only flagged for review.
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 equation, $D_1$ and the exponents are exact to the stated precision. The driver checks that $\mathrm{tr}\,D_1$ is exactly rational-linear in $\varepsilon$, which catches a mis-built equation.
- The rational $(a,b)$ of survivors come from numerical fits that agree to about $10^{-26}$ across the $\varepsilon$ values, with no symbolic derivation behind them. They are labeled that way in the output.
- Excluding $\varepsilon$-incommensurate branches relies on the completeness of the expansion by regionsthe standard technique that writes a Feynman integral's large-mass asymptotics as a sum over momentum regions, each contributing definite powers of the large scale. Keep more matching conditions than surviving constants in the downstream solve and confirm that the extra ones hold.
- Do not use the package for a Frobenius expansion around a finite singular point; that is
frobeniusandfrob_scalarin Wayfinder. Do not use it when the solution is analytic at infinity, where ordinary large-mass values suffice. - Reading a single boundary constant off the Picard–Fuchs operatorthe linear differential operator of lowest order, with polynomial coefficients, whose solutions include the period reduced modulo primes (the $p$-adic Frobenius trace) is done elsewhere on this site, with GeoTriage and Lockpick.
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/.
| Command | What it does |
|---|---|
python3 -m frobenius_boundary.cli config.json | Runs the five steps; writes SPECTRUM_<tag>.json and BRANCHES_<tag>.json |
python3 -m frobenius_boundary.selftest | Acceptance test against the reference family's expected numbers |
python3 asdminer/run_control.py | Self-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.py | Miners 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.
| Function | What 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.
| Function | What 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_normalize | The 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:
FROB_CONFIG=<path>: the configuration the acceptance test reads.FROBENIUS_POLYDE_CACHE=<dir>,FROBENIUS_SAMPLE_NCPU=<n>: cache the fitted system on disk; sample in parallel. Both are off by default and leave the results unchanged.FROB_L6_OPERATOR=<json>: an order-6 operator file ({"coeffs": [[...], ...]}, seven rows) read by therun_l6_*miners,op_L6()and stageS4. Each stops with a message when it is unset.
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
- Runs on: Python 3 with mpmath, sympy, gmpy2 and numpy.
- Input: a per-point reduction table made with Kira, and the list of preferred masters.
- Self-test:
python3 -m frobenius_boundary.selftest, withFROB_CONFIGpointing at a filled-in copy ofconfig_example.json. It ends withSELFTEST PASSand takes roughly 15 to 25 minutes. asdminer: uses only the Python standard library. Its self-test also needsgpfrom PARI/GP on the PATH and takes a few seconds.deform_transport: needs python-flint and gmpy2 (numpy and scipy only inside one control). The full self-test,--stages S0,S1,S2,S3,S4, takes hours.- Not distributed: the reference reduction table, the order-6 operator file, and the comparator inputs of
run_cal_d.pyandrun_cal_d2.py(DEFORM_R2_GRID,DEFORM_F1_RECEIPTS).
Source and references
The code is tools/frobenius-boundary/ in the BootLoops repository. Wayfinder's boundary_branches module wraps the same functions.
| Reference | What it supplies |
|---|---|
| Dwork; Lauder | The deformation method that deform_transport implements |
| Pancratz and Tuitman, arXiv:1307.1250 | The deformation method |
| Candelas, de la Ossa and van Straten, arXiv:2104.07816 | The form of the method for Picard–Fuchs operators |
| Candelas, de la Ossa and Kuusela, CY3Zeta, arXiv:2405.08067 | A public program for the same method, for Calabi–Yau operators |
| Kuusela, Lathwood, Mosso Rojas and Stepniczka, PFLFunction, arXiv:2604.01191 | A public program for the same method, for Calabi–Yau operators |
| Atkin and Swinnerton-Dyer | The three-term congruences that asdminer solves |
| Honda; Beukers | The 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/GP | The comparison values of the asdminer self-test |