Dogtag

Dogtag reads the file that defines a family of Feynman integralsall the integrals built from one list of propagators and establishes which family it is, before any reductionrewriting every integral of the family in terms of a finite basis of master integrals or numerical evaluation is run on it. It reports whether the family matches a known one after a relabeling of the loop momenta, whether its graph is planar or crossedwhether the diagram can be drawn without crossing lines when the external legs keep their physical order, and whether it agrees with a drawing. The isomorphism and planarity tests are networkx's (VF2, after Cordella, Foggia, Sansone and Vento), and a second module, loomcheck, tests conformal integrals against the Yangianan infinite-dimensional symmetry algebra that extends conformal symmetry and signals integrability-symmetry theorems for fishnet and loom graphs.

What it does

An integral family is a list of propagators $q^2 - m^2$, with $q$ a linear combination of loop momenta $k_i$ and external momenta $p_j$. Two files can list propagators that look different and still describe the same graph, because a propagator depends on $q$ only through $q^2 = (-q)^2$.

Dogtag was built to catch a file labeled as the nonplanar (crossed) two-loop double box whose graph is the planar one. After $k_2 \to -k_2$ and momentum conservation, its propagators are exactly those of the planar double box (hep-ph/9905323). Reading the list by eye does not reveal this, and every later step of a reduction trusts the label. Run the script once on a family file before starting a Kira reduction or an AMFlow evaluation on it. The name is meant literally: a dog tag identifies its wearer.

For each family the audit has three steps.

The catalog holds nine reference families, among them the massless planar double box (planar_smirnov_dbox) and the crossed double box (crossed_tausk_dbox, hep-ph/9909506). The report for each family opens with its fingerprint: the loop and propagator counts, the cut signature, the planarity and two hashes. One hash is of the routed propagator set; the other is of the rebuilt graph and does not change under rerouting.

Dogtag reads four kinds of family file:

Irreducible scalar productsdot products such as k1·p3 that a reduction keeps in its basis but that are not lines of the diagram and entries with no loop momentum are dropped. The external legs are read as data. For a Kira yaml they come from the kinematics.yaml passed with --kinematics or found beside the family file, or from the external_momenta, momentum_conservation and leg_virtualities keys in the family block. The other formats declare their own legs.

When a Kira yaml carries none of this, the legs are inferred from the propagator symbols. The report then prints planar=None and a LEG-SET-INFERRED warning in place of a planarity verdict, because a family whose top-sector propagators never contain the dependent leg would be read with one leg too few.

The compare mode (--drawn) takes the family file and a drawn graph. The drawing is an edge list in JSON, a yaml drawn_graph: block, or a routed yaml whose header comments state the edges, the legs with their $p^2$, the cyclic order and the propagator powers. Dogtag rebuilds both graphs and tests them for isomorphism, with masses, propagator powers and leg virtualities as labels. It prints exactly one verdict:

Under the verdict come the leg map, the relabeling and the identification of symbolic mass labels across the two sides. For both sides the output lists the legs per vertex, the vertex and edge counts and the planarity in the drawn order. A declared cyclic leg order that the leg map does not preserve is reported as CYCLIC-ORDER MISMATCH without changing the verdict.

The checks are exact graph computations with no numerical tolerance. The audit and the compare mode have these limits:

The Yangian screen is the loomcheck module, in the loomcheck/ subfolder of the package. It takes a conformal Feynman integral in position space, $I = \int \prod_{v} d^D x_v \prod_{i \lt j} (x_{ij}^2)^{-a_{ij}}$, given as a dictionary {(i, j): a_ij} with numerator factors entered as negative powers. It tests whether the integral can fall under the published Yangian-symmetry theorems for fishnet and loom graphs (arXiv:1708.00007, arXiv:2304.04654, arXiv:2505.05550). It checks three conditions on the graph:

A failed condition is a proof that the graph lies outside those theorems as published. A pass says only that the conditions do not exclude it. The screen has these limits:

Examples

Run the self-test. With the package set up (see Requirements), run the self-test from the package directory tools/dogtag/. It confirms the install and shows the report format, using the catalog families as controls.

python3 topology_audit.py --selftest

Abridged output:

[2] catalog planar Smirnov dbox (control, must read planar):
   name=planar_dbox_control  loops=2  genuine_props=7  isp=0  massive=0
   planar=True  (networkx.check_planarity with external-leg closure cycle in canonical order 1,2,3,4)
   cut_signature={'s': 2, 't': 3, 'u': 4}  multiset=[2, 3, 4]  t/u asymmetric
   ...
[3] catalog crossed box entries (declared planar False, must read NONplanar):
   name=crossed_tausk_dbox_control  loops=2  genuine_props=7  isp=0  massive=0
   planar=False  (networkx.check_planarity with external-leg closure cycle in canonical order 1,2,3,4)
   cut_signature={'s': 2, 't': 3, 'u': 3}  multiset=[2, 3, 3]  t<->u symmetric
   ...
SELF-TEST: 17 executed / 0 skipped (17 PASS, 0 FAIL) of 17 legs
SELF-TEST: ALL PASS (rc 0)

Seventeen groups of checks run in one to two minutes. One group runs the compare mode over a test corpus of 30 published families, each paired with the graph drawn in its paper. The last group runs the loomcheck module's own checks.

Catch a mislabeled double box. A Kira family file whose name says nonplanar crossed box and whose last propagator, $(k_1+k_2)^2$, looks like the crossing rung:

integralfamilies:
  - name: "NP2L_xbox"
    loop_momenta: [k1, k2]
    top_level_sectors: [127]
    external_momenta: [p1, p2, p3, p4]
    momentum_conservation: {p4: "-p1 - p2 - p3"}
    leg_virtualities: {p1: "0", p2: "0", p3: "0", p4: "0"}
    propagators:
      - [ "k1^2", 0 ]
      - [ "(k1 + p1)^2", 0 ]
      - [ "(k1 + p1 + p2)^2", 0 ]
      - [ "k2^2", 0 ]
      - [ "(k2 + p3 + p4)^2", 0 ]
      - [ "(k2 + p4)^2", 0 ]
      - [ "(k1 + k2)^2", 0 ]

The file declares its legs in the family block. Run the audit on it:

python3 topology_audit.py NP2L_xbox.yaml

Output (one long line shortened):

   name=NP2L_xbox  loops=2  genuine_props=7  isp=0  massive=0
   planar=True  (networkx.check_planarity with external-leg closure cycle in canonical order 1,2,3,4)
   cut_signature={'s': 2, 't': 3, 'u': 4}  multiset=[2, 3, 4]  t/u asymmetric
   canonical_hash=b6577ea5d3bf  (routed)   canonical_hash_realized=b6d3659027de  (realized graph, routing-independent)
   >> ISO to 'planar_smirnov_dbox' under [k2 -> -k2]
   !! graph-isomorphic to catalog family 'planar_smirnov_dbox' under [k2 -> -k2]  (massless planar double box (Smirnov hep-ph/9905323)); labels carried: masses [...], multiplicities [...] and leg classes {...} match the entry under [k2 -> -k2]
   !! LABEL/PROVENANCE MISMATCH: file is labeled nonplanar/crossed but the reconstructed graph is PLANAR in the canonical external-leg order (networkx). This is the NP-dbox-style mislabel. Cross-check the cut signature {'s': 2, 't': 3, 'u': 4}.

Lines starting >> are catalog matches, and lines starting !! are warnings. The relabeling can be checked by hand. With $p_4 = -p_1-p_2-p_3$, the substitution $k_2 \to -k_2$ turns $(k_2+p_3+p_4)^2$ into $(k_2+p_1+p_2)^2$, $(k_2+p_4)^2$ into $(k_2+p_1+p_2+p_3)^2$ and $(k_1+k_2)^2$ into $(k_1-k_2)^2$. That is the planar routing, propagator for propagator.

A crossed family prints planar=False and no mismatch line.

Compare a family with its drawn graph. Two of the included fixture files are a published double-box family and the graph drawn for it in the paper:

python3 topology_audit.py tests/fixtures/row02/family_of_record.jl \
        --drawn tests/fixtures/row02/drawn_graph.yaml --verdict

Abridged output:

VERDICT: IDENTITY-PASS (leg map {'p4': 'p1', 'p3': 'p2', 'p1': 'p3', 'p2': 'p4'}; the propagator sets differ by a loop redefinition: affine map ['l1 -> k1 +k2 -p1 -p2 -p3', 'l2 -> k1 -p1 -p2 -p3'] with leg map {...})
   family doublebox (family_of_record.jl): loops ['l1', 'l2'], legs ['p1', 'p2', 'p3', 'p4'], ...
          realized: V=6 E=7 N=4 legs per vertex [1, 1, 1, 1, 0, 0]; distinct connected realizations 1
   drawn  drawn_row02 (drawn_graph.yaml): loops ['k1', 'k2'], legs ['p1', 'p2', 'p3', 'p4'], ...
   isomorphism of the realized labeled graphs (VF2): bare True, with masses and multiplicities True, with leg classes True; by leg name False
   ...

The drawing's propagators come from a spanning-tree routing of its edge list, so no signed permutation relates the two files. The verdict rests on the isomorphism of the rebuilt graphs, and the affine map is the loop redefinition that carries one propagator set onto the other. by leg name False says that the match needs the legs relabeled, as the leg map shows.

Routines

CommandWhat it does
topology_audit.py FAMILY_FILEAudits every family in the file and prints fingerprint, catalog matches and warnings; exit code 2 if no family is found
topology_audit.py FAMILY_FILE --drawn DRAWN_GRAPHThe compare mode: the verdict line, its evidence, then the family's audit
python3 -m loomcheck --basis FILEScreens entries of a basis file in the arXiv:2607.11645 format: one result line per entry and a summary count
OptionWhat it does
--name NAMESelects one family of a multi-family file; an unknown name stops with exit code 2 and lists the names in the file
--leg-permsAlso tries permutations of the external legs in the catalog match
--kinematics K.yaml, --kinematics-drawn KD.yamlThe Kira kinematics.yaml of the family and, with --drawn, of the drawn side
--integral NFor an AMFlow job file: the target integral that defines the family
--verdictWith --drawn: prints the verdict and its evidence without the family's audit
--jsonPrints the report as a JSON list with one object per family; with --drawn the compare is under "verdict"
--targets LIST, --D D, --json OUTFor loomcheck: the 1-indexed entries to screen (nine by default), the dimension and a JSON output file

python3 -m loomcheck is run from the package directory; python3 loomcheck/loomcheck.py ... works from anywhere.

The audit is loaded in Python with import topology_audit. The screen is loaded with from loomcheck import screen_graph, with the package directory on sys.path.

FunctionWhat it returns
load_family(path, name, kinematics, integral_index)A list of Family objects read from any of the input formats, with the dependent leg completed
audit(fam, try_leg_perms)The fingerprint dict extended with catalog_matches, cut_symmetry, planarity_report, leg_set and warnings
fingerprint(fam), planarity(fam, leg_order), cut_signature(fam)The parts of the audit on their own: the fingerprint, the planarity report and the minimum cut per channel
build_graph(fam)(G, ok): the rebuilt graph as a networkx MultiGraph; ok=False with a named cause when no graph realizes the propagators
compare_drawn(famA, famB, ...), verdict_lines(res)The compare result as a dict, with the verdict under verdict, and its printed lines
screen_graph(powers, D, internal)The result of each condition, and yangian_class, true only when all three hold
CATALOG_SOURCESThe dict of reference families; add an entry to extend the catalog

The lower-level functions, among them isomorphism_to, affine_iso_search, realized_graph_iso, realized_canonical_hash and read_kinematics_yaml, are documented in their docstrings in topology_audit.py.

Requirements

Source and references

The code is tools/dogtag/ in the BootLoops repository (topology_audit.py, the loomcheck/ subfolder, README.md, GUIDE.md, tests/ with the fixture files), released under the MIT license. The last three rows of the table list an algorithm and the public programs that address parts of the same problem by other methods.

ReferenceWhat it supplies
A. Hagberg, D. Schult and P. Swart, networkxThe isomorphism, planarity and minimum-cut routines that Dogtag calls
L. P. Cordella, P. Foggia, C. Sansone and M. Vento, IEEE TPAMI 26 (2004) 1367The VF2 isomorphism algorithm, used through networkx
V. A. Smirnov, Phys. Lett. B 460 (1999) 397, hep-ph/9905323The planar double box of the catalog
J. B. Tausk, Phys. Lett. B 469 (1999) 225, hep-ph/9909506The crossed double box of the catalog
N. I. Ussyukina and A. I. Davydychev, Phys. Lett. B 298 (1993) 363 and 305 (1993) 136The three-loop off-shell ladder of the catalog
D. J. Broadhurst and A. I. Davydychev, arXiv:1007.0237The routing of that ladder in the catalog
arXiv:1708.00007, arXiv:2304.04654, arXiv:2505.05550The Yangian-symmetry theorems whose conditions loomcheck checks
arXiv:2607.11645, ancillary fileThe four-loop basis format that the loomcheck parser reads
A. Pak, J. Phys. Conf. Ser. 368 (2012) 012049, arXiv:1111.0868An algorithm for the same question: whether two families are equivalent
V. Magerya, feynsonA public program for the same question, by a method other than Dogtag's; it also prints the loop-momentum substitutions
A. Maier, dynast; A. von Manteuffel and C. Studerus, Reduze 2; R. Lee, LiteRed; V. Shtabovenko, R. Mertig and F. Orellana, FeynCalcPrograms that rebuild a graph from propagators or find the momentum map between two families

← back to the tools index