Counterweight

Counterweight takes the system of differential equations satisfied by a family of Feynman integrals and finds an exact rational change of basis that puts it in canonical ε-formHenn's canonical form: the right-hand side is ε times an ε-independent matrix with only simple poles. It implements the reduction algorithm of R. N. Lee (arXiv:1411.0911) for the canonical form of J. M. Henn (arXiv:1304.1806), as a Julia package on Nemo/FLINT with a Python front end, Canonify. It returns the transformation with a verification of the result, or a report saying why no transformation was found.

What it does

The master integralsthe finite basis to which every integral of the family reduces $I$ of a Feynman-integral family obey a linear system $dI/dx = A(\epsilon,x)\,I$. The entries of the connection matrix $A$ are rational in the dimensional regulator $\epsilon$ and in one kinematic variable $x$. In the basis an integration-by-parts reduction delivers, $A$ mixes $\epsilon$ and $x$ arbitrarily. Henn proposed that a better basis $J = T\,I$ usually exists, in which

$$T A T^{-1} + \frac{dT}{dx}\,T^{-1} \;=\; \epsilon\,\tilde A(x), \qquad \tilde A(x)=\sum_i \frac{R_i}{x-a_i},$$

with constant rational matrices $R_i$. In this form the solution is read off order by order in $\epsilon$ as iterated integrals over the letters $x-a_i$, and the BootLoops fitting and transport tools work in it. Counterweight computes $T$.

All arithmetic is exact, over $\mathbb{Q}(\epsilon)(x)$ (rational functions of $x$ whose coefficients are rational functions of $\epsilon$), so every intermediate matrix can be tested by equality. The engine follows Lee's algorithm in three stages.

The result is then verified: simple poles only, $A/\epsilon$ free of $\epsilon$, every residue of $\tilde A$ a constant rational matrix. A successful run returns $T$, the new connection, $\tilde A$ and a report of the moves made. An unsuccessful run returns ok = false with a stop reason and the move history instead of a guess.

Counterweight has these limits:

Small systems are typed in with matF2x, and Kira derive_dgl output is parsed by the KiraDE module. Large systems whose entries arrive as long uncancelled numerator and denominator lists go through MpolyFeed, which cancels common factors as FLINT polynomials before entering the field.

The canonical_form/ front end is described on its own page as Canonify. From an integral-family definition it computes each master's leading singularitythe residue of the integrand on its maximal cut, computed in the Baikov representation; dividing by it removes the algebraic prefactor and leaves a pure function. It returns the diagonal rotation $J_i = I_i/\mathrm{LS}_i$ in the format Gatekeeper's heldout_certify accepts, and it wraps the engine so that a sympy matrix is factorized in one Python call. Off-diagonal subsector corrections are outside this tool.

Examples

Check an installation. With the package set up (see Requirements), run the double-box validation from the package directory tools/counterweight/:

julia --project=. test/validate_henn.jl

The script builds Henn's published canonical connection for the massless planar double box (eight masters, letters $x$ and $1+x$) and scrambles it with an $\epsilon$-dependent rational change of basis. It then runs try_epsfactor on the scrambled system and checks that the recovered residues at $x=0$ and $x=-1$ have the same eigenvalues as Henn's matrices. The run ends with a PASS line; a failure raises an error.

The same steps at the Julia prompt (julia --project=. in the package directory), showing the objects involved:

using Counterweight, Nemo
using Counterweight.HennDbox

ctx = make_ctx()                               # the field Q(eps)(x)
A = HennDbox.henn_canonical(ctx)               # 8×8, already in eps-form
Ascr, Bgauge = HennDbox.henn_scramble(ctx, A)  # a generic non-canonical basis
is_epsform(ctx, Ascr)[1]                       # false
r = try_epsfactor(ctx, Ascr; max_balance_rounds=400)
r.ok                                           # true
certify_epsform(ctx, r.Anew)

Most routines take the context from make_ctx() as their first argument. Here r.T is the transformation and r.Anew the transformed connection $\epsilon\tilde A$. Because the arithmetic is exact, apply_gauge(ctx, Ascr, r.T) == r.Anew holds identically. certify_epsform reports the singular points 0 and -1.

From Python. With a sympy matrix A rational in x and the module's symbol eps (from canonical_form/README.md):

from canonical_form import factor_epsilon, to_dlog
Atilde, T, report = factor_epsilon(A, x)       # → Julia Counterweight (Lee 1411.0911)
letters = to_dlog(Atilde, x, alphabet=[x, 1+x])

factor_epsilon serializes the matrix and runs counterweight_bridge.jl under julia --project pointed at the engine directory (the environment variable COUNTERWEIGHT_ROOT, by default the parent of canonical_form/). It returns $\tilde A$ and $T$ as sympy matrices with the engine's report. If the engine stops, or the engine directory cannot be found, it raises NotImplementedError carrying the stop reason; a Julia error raises RuntimeError with Julia's message.

to_dlog returns one constant matrix per supplied letter, plus a _residual entry that is zero when the alphabet is complete and an _unmatched entry for any pole it does not cover.

Routines

The Julia module is loaded with using Counterweight. Each function takes the context and a matrix, (ctx, A), unless its arguments are shown.

FunctionWhat it returns
make_ctx()The field context Ctx
matF2x(ctx, n, entry)An $n\times n$ matrix from a function entry(i,j)
singular_points_xThe finite singular points, with irreducible higher-degree denominator factors listed separately
residue_matrix(ctx, A, a), residue_at_infinityThe exact residue matrix at a point or at infinity
pole_profile, is_fuchsianThe pole order at every singular point; whether all are simple
apply_gauge(ctx, A, T)$TAT^{-1} + (dT/dx)\,T^{-1}$
moser_reduceA MoserResult: ok, A, T, the pole profiles before and after, irregular and stop
try_epsfactorAn EpsResult: ok, Atilde, T, Anew and report; verbose=true prints one line per round
is_epsform, certify_epsformWhether $A/\epsilon$ is free of $\epsilon$; the full dictionary of checks
dlog_alphabetThe letters of a Fuchsian connection and the residue matrix at each, including infinity
check_flatness(Ax, Ay, dx, dy)The integrability residual of a two-variable connection
load_kira_de(path; family="A1"), build_A_from_rows(ctx, rows, masters, kin)The rows of a Kira derive_dgl file for the named family; the connection matrix for an ordered master list
feed_matrix_from_chunks(ctx, n, chunks)The matrix from raw numerator and denominator chunk lists; cache=path stores the reduced entries for reuse

The report of an EpsResult is a dictionary holding balance_rounds, history and, on failure, stop, plus a moser entry when pole reduction ran. The keys of certify_epsform are fuchsian, singular_points, algebraic_factors, epsform and dlog. The lower-level exports are listed in src/Counterweight.jl.

The Python functions factor_epsilon, fuchsify, wrap_epsfactor and to_dlog are listed with the rest of the front end on the Canonify page. fuchsify raises NotImplementedError on non-Fuchsian input, because the wrapper does not pass back a Moser-reduced matrix. Strip the leading-singularity prefactors first, or call the Julia engine directly.

Two more examples come with the package. examples/coupled_tower_counterweight.jl factorizes the Kira derive_dgl export named by TOWER_DE_JSON and writes rotation_T.json. examples/sec121_baikov.py builds the two-loop Baikov polynomial of a double-bubble sector.

Used on this site

Requirements

Source and references

The code is tools/counterweight/ in the BootLoops repository. The file src/Fuchsia.jl shares its name and its algorithm with Fuchsia, the public program of O. Gituliar and V. Magerya, and shares no code with it. Counterweight also shares no code with fuchsia.cpp, epsilon or Libra, the other public programs for Lee's algorithm.

ReferenceWhat it supplies
J. M. Henn, arXiv:1304.1806The canonical $\epsilon$-form; the double-box matrices of the validation example
R. N. Lee, arXiv:1411.0911The reduction algorithm: Fuchsian form, balances and factoring out $\epsilon$
Moser (1960); BarkatouThe criterion and the rank-reduction theory behind the pole-reduction stage
O. Gituliar and V. Magerya, Fuchsia, arXiv:1701.04269; V. Magerya, fuchsia.cpp; M. Prausa, epsilon, arXiv:1701.00725; R. N. Lee, Libra, arXiv:2012.00279Public programs for Lee's algorithm; not used by Counterweight
F. Lange, J. Usovitsch and Z. Wu, Kira 3, arXiv:2505.20197The derive_dgl files that KiraDE reads
C. Fieker, W. Hart, T. Hofmann and F. Johansson, Nemo, arXiv:1705.06134The exact arithmetic, on FLINT

← back to the tools index