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.
- Pole reduction. If $A$ has poles of order higher than one, a Moser reduction lowers them one order at a time until the system is Fuchsianevery singular point of the matrix, including the point at infinity, is a simple pole.
- Balances. A balance is a rank-one transformation $T=(1-P)+\tfrac{x-x_2}{x-x_1}P$ built from residue eigenvectors at two singular points. Each balance shifts the $\epsilon^0$ parts of the residue eigenvalues by one unit, until all vanish. The point at infinity and poles at the roots of an irreducible quadratic or cubic factor have their own moves. One is a single rational shear $T=M(x)/\hat q$, for a $\pm$ pair of $\epsilon^0$ parts at the two conjugate roots of an irreducible quadratic $\hat q$.
- Factoring out $\epsilon$. An $x$-independent change of basis over $\mathbb{Q}(\epsilon)$ removes any remaining $\epsilon^0$ part.
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:
- Basis only. Counterweight constructs a basis. It does not solve the equation or evaluate integrals.
- Irregular poles. A higher-order pole whose leading matrix is not nilpotent is an irregular singularity that no rational $T$ removes. For a system from an integration-by-parts reduction it means some masters lack a rational normalization factor. The diagnosis names the pole, its order and the offending eigenvalue factors, so that the basis can be fixed.
- Half-integer exponents. Half-integer $\epsilon^0$ parts in the residue eigenvalues at the roots of an irreducible polynomial mean the basis needs a square-root prefactor, and no purely rational form exists. Such blocks are work for Vopclose.
- Odd part at a quadratic factor. When the residue at the two conjugate roots of an irreducible quadratic has a nonzero odd part, the alphabet (the set of letters) needs the algebraic root as a letter. The engine stops with the residual obstruction.
- One variable at a time. Several kinematic variables are handled in one ratio variable with the others fixed.
check_flatnessthen confirms that the same $T$ factorizes the other directions.
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.
| Function | What 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_x | The finite singular points, with irreducible higher-degree denominator factors listed separately |
residue_matrix(ctx, A, a), residue_at_infinity | The exact residue matrix at a point or at infinity |
pole_profile, is_fuchsian | The pole order at every singular point; whether all are simple |
apply_gauge(ctx, A, T) | $TAT^{-1} + (dT/dx)\,T^{-1}$ |
moser_reduce | A MoserResult: ok, A, T, the pole profiles before and after, irregular and stop |
try_epsfactor | An EpsResult: ok, Atilde, T, Anew and report; verbose=true prints one line per round |
is_epsform, certify_epsform | Whether $A/\epsilon$ is free of $\epsilon$; the full dictionary of checks |
dlog_alphabet | The 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
- Banana: brought the differential equation to $\epsilon$-form on the six modular letters of $\Gamma_{1}(6)$.
Requirements
- Runs on: Julia 1.11 or newer with Nemo and JSON, both pinned by the committed
Manifest.toml. The front end needs Python 3 with sympy and mpmath, and Julia on the path for bridge calls. - Install: in the package directory run
julia --project=. -e "using Pkg; Pkg.instantiate()"once. - Self-test:
julia --project=. test/runtests.jlruns the shear, double-box and quadratic-letter tests in one Julia process and ends withSEC53_QORBIT: ALL LEGS AS EXPECTED. The last of the three callspython3. - Single tests:
test/validate_henn.jl,test/test_orbit_shear.jl(five cases) andtest/test_moser.jl(four pole-reduction cases) run the same way. - Front end:
python3 canonical_form/test_canonical_form.pyends withOK: 5/5 passed.CANONICAL_FORM_SKIP_JULIA=1skips the bridge case, and the parts of two cases that need optional data skip themselves.
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.
| Reference | What it supplies |
|---|---|
| J. M. Henn, arXiv:1304.1806 | The canonical $\epsilon$-form; the double-box matrices of the validation example |
| R. N. Lee, arXiv:1411.0911 | The reduction algorithm: Fuchsian form, balances and factoring out $\epsilon$ |
| Moser (1960); Barkatou | The 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.00279 | Public programs for Lee's algorithm; not used by Counterweight |
| F. Lange, J. Usovitsch and Z. Wu, Kira 3, arXiv:2505.20197 | The derive_dgl files that KiraDE reads |
| C. Fieker, W. Hart, T. Hofmann and F. Johansson, Nemo, arXiv:1705.06134 | The exact arithmetic, on FLINT |