Canonify
Canonify (the canonical_form Python module) prepares the basis of master integralsthe finite set of integrals to which every integral of a family reduces in which BootLoops fits Feynman integrals and writes their differential equations. It computes each master's leading singularitythe residue of the integrand when every propagator of the master is put on shell (the maximal cut); an algebraic function of the kinematics, or a period of a curve for elliptic sectors in the representation of P. A. Baikov (hep-ph/9611449) and returns the rescaling that divides it out. It also lets Python code call the Julia engine of Counterweight, the package that contains it, which brings a differential equation to ε-forma basis in which the matrix of the equation is ε times a matrix free of ε by the method of R. N. Lee (arXiv:1411.0911).
What it does
Reduction programs such as Kira return the master integrals, and the matrix $A(x,\epsilon)$ of their differential equation, in the basis the reduction program picked. Recognizing exact constants in high-precision numerical values, and solving the equation order by order in the dimensional regulator $\epsilon$, both work far better in a uniform-transcendentality basisa choice of masters in which every order in ε is a pure function of fixed transcendental weight with rational coefficients. The usual first move toward that basis is to divide each master $I_i$ by its leading singularity $\mathrm{LS}_i$:
$$J_i = \frac{1}{\mathrm{LS}_i(x)}\, I_i .$$
For the leading-singularity method see Arkani-Hamed, Bourjaily, Cachazo and Trnka (arXiv:1012.6032) and Henn, Mistlberger, Smirnov and Wasser (arXiv:2002.09492). Canonify takes a family block, the JSON object the amflow-cpp evaluator reads, and a list of masters written as {"tag": ..., "indices": [...]}. It works in these steps:
- Cut.
Familybuilds the Baikov representationa form of the integral with the propagators as integration variables and a power of a Gram-determinant polynomial as integrand.leading_singularitiessets each master's propagators to zero and takes iterated residues in the variables that remain. It labels the resultrational,sqrt,ellipticorunknown. - Elliptic sectors. In an elliptic sector (a sector is the set of propagators that appear in a master), the quartic $y^2=P(z)$ is read off the cut. The rescaling is $1/\varpi_0$, the inverse of its holomorphic period, which
elliptic_periodevaluates with a complete elliptic integral. - Rotation.
ut_rotationreturns the rescaling of each master, called the rotation below, in the format the Gatekeeper fitting routines read. - Check.
verify_unit_poleapplies the rotation to numerical values. The $\epsilon^{-L}$ coefficient of each rotated master ($L$ the loop number) must be the same constant at every kinematic point.
The second part of the module takes the matrix $A(x,\epsilon)$ to ε-form:
- Factorization.
factor_epsilonsends a sympy matrix $A$, rational in $x$ and $\epsilon$, to the Counterweight engine. It returns $\tilde A$ and $T$ with $TAT^{-1}+(\partial_xT)T^{-1}=\epsilon\tilde A$, so that $\partial_x J=\epsilon\,\tilde A(x)\,J$, the canonical form of J. M. Henn (arXiv:1304.1806). The engine works in exact arithmetic over $\mathbb{Q}(\epsilon)(x)$ and first lowers any poles of order higher than one with a Barkatou–Moser reduction. - Letters.
to_dlogpartial-fractions $\tilde A$ in $x$ into one constant matrix per letter (an argument of a logarithm) of a supplied alphabet. It needs no engine.
Canonify has these limits:
- The rotation is diagonal. Subtracting subsector integrals to complete the basis off the diagonal is outside this module.
- The leading singularity is computed up to an overall constant and sign.
- The automatic Baikov construction is exact for the top sector of a family, the one with every propagator. For subsectors (fewer propagators) the top-family Gram determinant can pick up spurious factors.
- When the Baikov exponent vanishes at $\epsilon=0$ (the equal-mass sunrise, for example) the representation is degenerate. In that case, and for subsectors, pass the cut polynomial yourself through a per-master
maxcutentry. factor_epsilonstops at a genuinely irregular singular point, which the Barkatou–Moser reduction cannot make regular. For a Feynman system such a stop usually means that some master still lacks its leading-singularity prefactor.
Examples
Leading singularities and rotation from the command line. The package includes the one-loop massless box family as box1l.json. With the package set up (see Requirements), run this from tools/counterweight/canonical_form/, after creating the directory out/box1l/:
python canonical_form.py box1l.json --point '{"s":-3,"t":-7}' \
--out out/box1l/ut_rotation.json
The script prints one JSON record with the family name, the point, a leading_singularities object and the ut_rotation dictionary evaluated at the point. With --out it also writes the record to that file. The bundled file lists the two bubble masters of the box family. Both are subsectors, so their automatic entries come back with kind sqrt and spurious factors, the case the maxcut entry is for.
The rotation from Python, passed to a fit. From the module README:
from canonical_form import Family, ut_rotation
from gatekeeper import heldout_certify, load_oracle_values
fam = Family(target["family"])
rot = ut_rotation(fam, target["masters"], point={"s": -3, "t": -7})
# rot = {'ut_box': {'box': '21/4'}, ...} ← exact heldout_certify format
values, kin, _ = load_oracle_values([oracle_dir])
res = heldout_certify(values, kin, weight=2, basis_fn=..., basis_names=...,
ut_rotation=rot)
Here target is a parsed target file like box1l.json with the box master [1,1,1,1] added, as in the test suite. The leading singularity of the box master comes out proportional to $1/(st)$. At $s=-3$, $t=-7$ its coefficient is the exact string '21/4', that is $st/4$. The Gatekeeper fit called on the last line multiplies the raw numerical values by these coefficients before it fits.
When the automatic cut is degenerate, give the curve directly in the master entry, as the README does for the equal-mass sunrise:
masters = [{"tag": "sun", "indices": [1,1,1],
"maxcut": {"poly": "z*(z-4)*((tt-z)**2 - 4*z)", "vars": ["z"]}}]
leading_singularities then reports kind == "elliptic" with that quartic, and ut_rotation at a numerical value of tt returns $1/\varpi_0$.
Full ε-factorization through the engine. Also from the README:
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])
A is a sympy Matrix in the symbols x and eps. The bridge fixes those two names, so import eps from the module and name your variable x. letters maps 'x' and 'x + 1' to constant matrices; confirm that letters['_residual'] is the zero matrix before using them.
Routines
The command line has one form, canonical_form.py target.json [--point JSON] [--out FILE]. It computes the leading singularities and the rotation for the masters in a target file (or a bare family file) and prints them as JSON.
| Function | What it returns |
|---|---|
Family(spec) | The parsed family block; baikov_poly(), baikov_exponent() and sector_of(indices) give the polynomial, its exponent and a master's sector |
leading_singularities(family, masters) | {tag: LSResult}, one leading singularity per master; maxcut_override supplies cut polynomials by tag |
LSResult | A record with tag, sector, kind, expr, radicand, quartic, residual_vars, note and a to_json() method |
elliptic_period(quartic, var, point) | The period $\varpi_0$ of $y^2=P(z)$, $P$ cubic or quartic, at a kinematic point, computed at dps digits |
ut_rotation(family, masters, point) | {ut_tag: {raw_tag: coeff}}: exact strings such as '21/4' or mpmath numbers at a point, expression strings without one |
ut_rotation_matrix(family, masters, point) | The same rotation as (matrix, row_names, col_names) |
verify_unit_pole(values, ut_rot, L=...) | For each rotated master: const (its $\epsilon^{-L}$ coefficient), spread_digits (the agreement across points) and ok |
factor_epsilon(A, x) | (Atilde, T, report): two sympy matrices and a dictionary describing what the engine did |
fuchsify(A, x) | (A_new, T, report); raises NotImplementedError on poles of order higher than one, and never returns a Moser-reduced matrix |
wrap_epsfactor(A, x, action=...) | The engine's JSON reply as a dict; "certify" only tests for simple poles and ε-form, "epsform" runs the full reduction |
to_dlog(Atilde, x, alphabet) | {letter: matrix} for $\tilde A=\sum_a A_a\,\partial_x\log a$, plus _residual and, where poles are left over, _unmatched |
eps | The sympy symbol the module and the bridge use for the regulator |
With include_eps_shift=True, ut_rotation also returns the recommended power of ε for each master. The engine calls go through the Julia script counterweight_bridge.jl, whose JSON reply has the keys ok, fuchsian, epsform, dlog, singular_points, T, Atilde and report.
factor_epsilon raises NotImplementedError when the engine directory is not found or the engine stops short of an ε-form. The message carries the stop reason and the names of other programs for this step (CANONICA, Libra, Fuchsia, epsilon). If the bridge process itself fails, the call raises RuntimeError with Julia's error output.
Requirements
- Runs on: Python 3 with sympy and mpmath. The ε-form functions also need Julia 1.11 or newer; everything else runs without Julia.
- Install: the ε-form functions need the Counterweight engine set up once: run
julia --project=. -e "using Pkg; Pkg.instantiate()"intools/counterweight/. - Self-test: from
tools/counterweight/,python3 canonical_form/test_canonical_form.pyruns five tests and ends withOK: 5/5 passed. The numerical-values test and the Julia bridge test skip when their optional data or Julia are absent, andCANONICAL_FORM_SKIP_JULIA=1skips the bridge test. - Optional:
verify_unit_poleimports its rotation helper from the Gatekeeper package, which sits beside Counterweight in the repository.COUNTERWEIGHT_ROOTin the environment points the bridge at an engine checkout other than the parent directory.
Source and references
The code is the canonical_form/ subdirectory of tools/counterweight/ in the BootLoops repository. The engine it calls, and the engine's own tests, are described on the Counterweight page.
| Reference | What it supplies |
|---|---|
| P. A. Baikov, hep-ph/9611449 | The Baikov representation |
| N. Arkani-Hamed, J. L. Bourjaily, F. Cachazo and J. Trnka, arXiv:1012.6032 | The leading-singularity method |
| J. Henn, B. Mistlberger, V. A. Smirnov and P. Wasser, arXiv:2002.09492 | The leading-singularity method; Canonify does not use their program DlogBasis |
| J. M. Henn, arXiv:1304.1806 | The canonical ε-form |
| R. N. Lee, arXiv:1411.0911 | The reduction algorithm of the Counterweight engine |
| Byrd and Friedman (1954) | The reduction to Legendre form in elliptic_period |
| C. Meyer, CANONICA, arXiv:1705.06252; R. N. Lee, Libra, arXiv:2012.00279; O. Gituliar and V. Magerya, Fuchsia, arXiv:1701.04269; M. Prausa, epsilon, arXiv:1701.00725 | Other programs for the ε-form step, named in the error message; Canonify does not call them |