A set of tools to perform calculations with trivalent diagrams in Mathematica.

Written by Deniz Stiegemann.

• Installation & Setup
• List of Files in the Repository
• Background
• Documentation
  • Analysis of Trivalent Diagrams
    b, Components, d, Diagram, dimC4, DistinctDiagrams, FindDiagramIsomorphisms, IsomorphicDiagramQ, MakeGraphs, ReduceDiagram, ReduceSquares, t
  • Operations on Diagrams
    ConnectAt, DiagramCompose, DiagramConjugate, DiagramFlipH, DiagramMoveDown, DiagramMoveUp, DiagramNorm, DiagramRotate, DiagramScalar, DiagramTensor, DiagramTensorPower, DiagramTrace
  • Other Tools
    Bilinearize, ConjugateLinearize, EnsureGraph, EnsureMatrix, Linearize, Sesquilinearize
  • Libraries
    ClearLibrary, Description, LoadLibrary, Retrieve
• Acknowledgements
• License

You need Mathematica 11.2 or higher to run the package.

The easiest way to get started is to copy the two files

• TriCats.m
• stdlib.m

into the folder that also contains the notebook in which you want to use the package. You can then load the package with the following two lines:

SetDirectory[NotebookDirectory[]];
<< TriCats`;

The main reference is

• S. Morrison, E. Peters, and N. Snyder. Categories generated by a trivalent vertex. Selecta Mathematica 23 (2017), no. 2, pp. 817–868. doi:10.1007/s00029-016-0240-3. arXiv:1501.06869

where trivalent categories were introduced and classified for a large variety of dimensions. The arXiv source contains notebooks with which the authors did some of the calculations and where they implement many functions also found in this package.

After having loaded the package, you can use

?TriCats`*

to obtain a list of all symbols and functions introduced by the TriCats package, together with their usage descriptions.

The DOI 10.5281/zenodo.1245752 only links to the latest version of this package, archived at Zenodo. DOIs for specific versions are available at that link.

⚠️ Please note that the package does not yet have any exception handling, so you are always expected to enter valid arguments, and errors might not always be visible.

b represents the formal bigon parameter of a trivalent category. It is also an option of functions such as ReduceDiagram, having the symbol b as its default value.

Components[expr, diagrams] gives the coefficients that the diagrams specified in the list diagrams have in the linear combination expr of diagrams.

d represents the formal loop parameter of a trivalent category. It is also an option of functions such as ReduceDiagram, having the symbol d as its default value.

Diagram[a, in, out]
represents a diagram with adjacency matrix a, ingoing legs in, and outgoing legs out.

Diagram[a]
represents a diagram with adjacency matrix a and no exernal legs. Equivalent to Diagram[a,{},{}].

Diagram[g, in, out] and Diagram[g]
represent diagrams with graph g.

Legs are represented by 1-valent vertices. Obsolete 2-valent vertices (i.e. 2-valent vertices that are not loops) are allowed and correctly removed by ReduceDiagram.

Vertices with degree 0 are also allowed. The empty diagram is thus represented by Diagram[{{0}}].

The convention for graphical representations of diagrams is that ingoing legs are located at the bottom of a diagram and outgoing legs at the top.

dimC4 represents the dimension of C4 of a trivalent category, the linear space of diagrams with four external legs. It is an option of functions such as ReduceDiagram, where it is relevant for substituting squares. In this case, the default value is 4.

DistinctDiagrams[expr] gives a list of all distinct diagrams appearing at any level in expr.

DistinctDiagrams[expr, levelspec] gives a list of all distinct diagrams found in expr on levels specified by levelspec.

DistinctDiagrams[expr] is equivalent to DistinctDiagrams[expr, Infinity].

DistinctDiagrams is useful for finding all distinct diagrams in a complicated expression, especially when the number of external legs is large. The list returned by DistinctDiagrams can then be used as a second argument to Components, for example:

Components[expr, DistinctDiagrams[expr]]

FindDiagramIsomorphisms[diagram1, diagram2] finds all graph isomorphisms from diagram1 to diagram2 that correctly map open legs.

IsomorphicDiagramQ[diagram1, diagram2] yields True if diagram1 and diagram2 are isomorphic, and False ortherwise.

MakeGraphs[expr] gives a list of graphs for all adjacency matrices occuring in expr.

ReduceDiagram[diagram] simplifies diagram by removing 2-valent vertices and applying substitution rules for loops, lollipops, bigons, triangles, and squares. If the diagram has no external legs and can be completely reduced, an expression in terms of only d, b, and t is returned. Otherwise, the simplified form of diagram is returned.

ReduceDiagram admits the following options:

Note that unless there is no other way of reducing a diagram, it is often helpful to set ReduceSquares->False in order to avoid complicated return values.

ReduceDiagram is linear with respect to expressions with head Diagram.

ReduceSquares is an option of ReduceDiagram that specifies whether squares should be reduced. Its default value is True.

Note that unless there is no other way of reducing a diagram, it is often helpful to set ReduceSquares->False in order to avoid complicated return values when calling ReduceDiagram.

t represents the formal triangle parameter of a trivalent category. It is also an option of functions such as ReduceDiagram, having the symbol t as its default value.

ConnectAt[a1, a2, legs1, legs2] is a low-level function that gives the adjacency matrix obtained by connecting the legs legs1 of matrix a1 to the legs legs2 of matrix a2.

Do not use this function for composition; use DiagramCompose instead.

DiagramCompose[diagram1, diagram2] gives the diagram obtained by composing diagram1 and diagram2.

DiagramCompose[diagram1, diagram2, …] composes a finite sequence of diagrams.

DiagramCompose[diagram] gives diagram.

DiagramCompose is bilinear with respect to expressions with head Diagram.

DiagramConjugate[diagram] gives diagram reflected horizontally by swapping ingoing with outgoing legs.

DiagramConjugate is the conjugate-linear version of DiagramFlipH and therefore more useful for computations.

DiagramConjugate is conjugate-linear with respect to expressions with head Diagram.

DiagramFlipH[diagram] gives diagram reflected horizontally by exchanging the lists of in and out vertices.

DiagramConjugate is the conjugate-linear version of DiagramFlipH and therefore more useful for computations.

DiagramMoveDown[diagram,n] takes the n rightmost outgoing legs of diagram and makes them ingoing legs in reverse order.

DiagramMoveDown[diagram,-n] takes the n leftmost outgoing legs of diagram and makes them ingoing legs in reverse order.

DiagramMoveDown is linear with respect to expressions with head Diagram.

DiagramMoveUp[diagram,n] takes the n rightmost ingoing legs of diagram and makes them outgoing legs in reverse order.

DiagramMoveUp[diagram,-n] takes the n leftmost ingoing legs of diagram and makes them outgoing legs in reverse order.

DiagramMoveUp is linear with respect to expressions with head Diagram.

DiagramNorm[diagram] gives the norm of diagram.

DiagramNorm uses ReduceDiagram to compute the value of the scalar product of diagram with itself. Options to be used by ReduceDiagram can be specified as options for DiagramNorm and are passed along.

DiagramNorm uses DiagramScalar and therefore supports linear combinations of expressions with head Diagram as input.

DiagramRotate[diagram] gives diagram rotated by 180 degrees, i.e. the lists of ingoing and outgoing legs are swapped and each reversed.

DiagramRotate is linear with respect to expressions with head Diagram.

DiagramScalar[diagram1, diagram2] gives the scalar product of diagram1 and diagram2.

DiagramScalar is sesquilinear with respect to expressions with head Diagram, i.e. conjugate-linear in the first and linear in the second argument.

DiagramTensor[diagram1, diagram2] gives the tensor product of the diagrams diagram1 and diagram2.

DiagramTensor[diagram1, diagram2, …] gives the tensor product of a finite sequence of diagrams.

DiagramTensor[diagram] gives diagram.

DiagramTensor is bilinear with respect to expressions with head Diagram.

DiagramTensorPower[diagram, n] gives the n-th tensor power of diagram, and the empty diagram if n is zero.

n must be a non-negative integer.

DiagramTrace[diagram] gives the trace of diagram.

DiagramTrace is linear with respect to expressions with head Diagram.

Bilinearize[f] makes the function f bilinear with respect to expressions with head Diagram.

f can be any function of two arguments which has already been defined for expressions with head Diagram in the following way:

f[diagram1_Diagram, diagram2_Diagram] := expr

ConjugateLinearize[f] makes the function f conjugate-linear, in its first argument, with respect to expressions with head Diagram.

f can be any function which has already been defined for expressions with head Diagram in the following way:

f[diagram_Diagram, …] := expr

f can have more than one argument.

EnsureGraph[expr] replaces adjacency matrices with graphs, if necessary, in all diagrams occuring in expr.

EnsureMatrix[expr] replaces graphs with adjacency matrices, if necessary, in all diagrams occuring in expr.

Linearize[f] makes the function f linear, in its first argument, with respect to expressions with head Diagram.

f can be any function which has already been defined for expressions with head Diagram in the following way:

f[diagram_Diagram, …] := expr

f can have more than one argument.

Sesquilinearize[f] makes the function f sesquilinear with respect to expressions with head Diagram, i.e. conjugate-linear in its first and linear in its second argument.

f can be any function of two arguments which has already been defined for expressions with head Diagram in the following way:

f[diagram1_Diagram, diagram2_Diagram] := expr

Diagrams and relations often used in computations can be conveniently stored in a file and are loaded with the following routines.

The library is a dictionary whose entries can be looked up with Retrieve["name of item"]. By default, the library is empty. LoadLibrary can be used to load the contents of a file into the library. For example, to load the standard library stdlib, use

LoadLibrary["stdlib"]

and use

Retrieve["C4Atoms"]

to obtain the basic diagrams in C4.

ClearLibrary[] deletes all entries from the library.

Description[key] gives the description of key in the library.

LoadLibrary[libname] adds the contents of the file <libname>.m to the library.

libname must be a string.

Retrieve[key] gives the value of key in the current library.

Options can be specified in the form Retrieve[key, opts] and are applied to the result of the library search. dimC4 has default value 4.

I would like to thank Tobias Osborne for introducing me to the topic, and Markus Duwe and Ramona Wolf for many helpful comments and for testing the package.

The package is available under the terms of the MIT license. See the LICENSE file for details.

Copyright (c) 2018 Deniz Stiegemann