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:

The second part of the module takes the matrix $A(x,\epsilon)$ to ε-form:

Canonify has these limits:

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.

FunctionWhat 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
LSResultA 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
epsThe 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

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.

ReferenceWhat it supplies
P. A. Baikov, hep-ph/9611449The Baikov representation
N. Arkani-Hamed, J. L. Bourjaily, F. Cachazo and J. Trnka, arXiv:1012.6032The leading-singularity method
J. Henn, B. Mistlberger, V. A. Smirnov and P. Wasser, arXiv:2002.09492The leading-singularity method; Canonify does not use their program DlogBasis
J. M. Henn, arXiv:1304.1806The canonical ε-form
R. N. Lee, arXiv:1411.0911The 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.00725Other programs for the ε-form step, named in the error message; Canonify does not call them

← back to the tools index