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.
- Catalog match. It applies every signed permutation of the loop momenta, $k_i \to \pm k_{\sigma(i)}$, and compares the resulting propagator set with a catalog of reference families stored in the script. When no signed permutation works it tries loop redefinitions $k \to Uk + c\cdot p$, with $U$ an integer matrix of determinant $\pm 1$, which is how two routings of one graph differ. A match is reported with its relabeling, and the report says whether the line masses, propagator powers (printed as multiplicities) and leg virtualities (the $p^2$ of each leg) agree too.
- Planarity. It rebuilds the Feynman graph from the propagator momenta, placing vertices by momentum conservation. It then tests planarity with the external legs joined by a cycle in a fixed cyclic order: the one the file declares, otherwise $p_1, \ldots, p_N$. The planar and crossed boxes are the same abstract graph and differ only in that order, so the test needs the cycle.
planar=Trueis the planar box;planar=Falsemeans a crossing is forced. - Cut signature. For each channel ($s$, $t$, $u$) it counts the fewest internal lines a cut must sever to separate that pair of legs from the rest. The triple depends on the momentum routing, so planarity is the deciding check.
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:
- Kira: an
integralfamilies.yamlwith itskinematics.yaml. The lines of the diagram are the propagators oftop_level_sectors. - AmflowFamily: a
.jlfile. The lines are those of the*_INDICESvector. - AMFlow job file: an AMFlow JSON file with its
familyblock and target integrals. The lines are those of one target integral, by default the one with the most positive indices. - pySecDec: a
LoopIntegralFromGraphscript.
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:
IDENTITY-PASS: the labeled graphs are isomorphic.FAMILY-MISMATCH: they are not, and the verdict line names the first level that fails (bare graph, masses, legs).NON-GRAPH: one side's propagators do not close into a connected graph with one cycle per loop momentum.NOT-CHECKABLE: one side cannot be read or leaves a leg's virtuality undeclared, and the verdict line names that side.
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 vertex reconstruction is exact for two-loop four-point boxes and the related one- and two-loop boxes, triangles and ladders. On large or many-loop families it may not complete. The script then reports
planar=Nonewith the cause and raises no mismatch warning. - The planarity test discriminates only with four or more external legs. With fewer, the report says
not discriminating (N < 4 legs), and a file labeled nonplanar that reads planar gets an "inconclusive" note instead of a warning. - "Labeled nonplanar" means a keyword search of the family name, the file name and the top of the file for words such as
nonplanar,crossedortausk.
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:
- The powers at every internal vertex sum to the dimension $D$.
- The full graph, with numerator edges included, is planar.
- Every $k$-sided face of the planar embedding has powers summing to $(k-2)D/2$.
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:
- The face count treats the outer face like any other, so a violation count of 0 to 2 is not to be trusted on its own.
- The file parser reads only the four-loop basis format of the arXiv:2607.11645 ancillary. Other integrals go to
screen_graphdirectly.
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
| Command | What it does |
|---|---|
topology_audit.py FAMILY_FILE | Audits 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_GRAPH | The compare mode: the verdict line, its evidence, then the family's audit |
python3 -m loomcheck --basis FILE | Screens entries of a basis file in the arXiv:2607.11645 format: one result line per entry and a summary count |
| Option | What it does |
|---|---|
--name NAME | Selects one family of a multi-family file; an unknown name stops with exit code 2 and lists the names in the file |
--leg-perms | Also tries permutations of the external legs in the catalog match |
--kinematics K.yaml, --kinematics-drawn KD.yaml | The Kira kinematics.yaml of the family and, with --drawn, of the drawn side |
--integral N | For an AMFlow job file: the target integral that defines the family |
--verdict | With --drawn: prints the verdict and its evidence without the family's audit |
--json | Prints the report as a JSON list with one object per family; with --drawn the compare is under "verdict" |
--targets LIST, --D D, --json OUT | For 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.
| Function | What 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_SOURCES | The 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
- Runs on: Python 3 with
sympyandnetworkx. No YAML library, Kira or AMFlow is needed. - Install: nothing to build. Run the commands from the package directory
tools/dogtag/. - Self-test:
python3 topology_audit.py --selftest(alias--self-test) must end withSELF-TEST: ALL PASS (rc 0). The exit code is 0 only when every check ran and passed, 1 if any failed, and 2 if any was skipped (networkx or a fixture file missing; the skipped check is named). - Without networkx: the tool still runs but prints
Nonefor every value that needs the rebuilt graph, and the self-test exits 2. - Yangian screen:
python3 -m loomcheck --selftestruns ten hand-checkable cases and must end withSELFTEST PASS: 10/10 checks passed. - Full test suite:
python3 -m pytest testscovers the audit checks case by case and needspytest. - Optional: the environment variable
LOOMCHECK_BASISsets the default basis file ofloomcheck. The fixture files of the self-test come with the package undertests/fixtures/.
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.
| Reference | What it supplies |
|---|---|
| A. Hagberg, D. Schult and P. Swart, networkx | The isomorphism, planarity and minimum-cut routines that Dogtag calls |
| L. P. Cordella, P. Foggia, C. Sansone and M. Vento, IEEE TPAMI 26 (2004) 1367 | The VF2 isomorphism algorithm, used through networkx |
| V. A. Smirnov, Phys. Lett. B 460 (1999) 397, hep-ph/9905323 | The planar double box of the catalog |
| J. B. Tausk, Phys. Lett. B 469 (1999) 225, hep-ph/9909506 | The crossed double box of the catalog |
| N. I. Ussyukina and A. I. Davydychev, Phys. Lett. B 298 (1993) 363 and 305 (1993) 136 | The three-loop off-shell ladder of the catalog |
| D. J. Broadhurst and A. I. Davydychev, arXiv:1007.0237 | The routing of that ladder in the catalog |
| arXiv:1708.00007, arXiv:2304.04654, arXiv:2505.05550 | The Yangian-symmetry theorems whose conditions loomcheck checks |
| arXiv:2607.11645, ancillary file | The four-loop basis format that the loomcheck parser reads |
| A. Pak, J. Phys. Conf. Ser. 368 (2012) 012049, arXiv:1111.0868 | An algorithm for the same question: whether two families are equivalent |
| V. Magerya, feynson | A 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, FeynCalc | Programs that rebuild a graph from propagators or find the momentum map between two families |