Matchete includes a framework for dealing with contractions of Clebsch-Gordan coefficients (CGs) in a pseudo-symbolic manner. The workflow involves associating explicit tensor representations to each symbolic CG. This allows contractions to be evaluated numerically (exact) with tensor contractions before the result is projected onto a basis consisting of the already defined CGs.

All CGs transform under the action of a particular (gauge) group. It would be absurd to start talking about contracting invariants of SU(2)_L and SU(3)_c. Even contractions between two distinct SU(2) groups would not be sensible. To allow for evaluations in scenarios with multiple group indices, as required in realistic QFTs such as the SM, we must first define the symmetry groups and the relevant representations.

A group is initialized by giving it a reference name and specifying its Lie algebra (Alg), which informs all the representation theory associated with said group. The group name is a label that the user should use to refer to that specific group. The use of group names ensures that multiple groups with identical algebra can be discriminated. The user may, thus, define multiple SU(2) groups in the same session. When a group has been defined, one can define representations of that group to be used in Lagrangians of group theory contractions.

N.b. DefineCGGroup is too bare bones for QFT applications. The user is encouraged to use DefineGaugeGroup or DefineGlobalGroup instead according to circumstances. These functions specifies important additional information about the QFT to Matchete in addition to automatically setting up some common representations and and CGs.

Indices in Matchete — for fields, CGs, derivatives, etc. — all have an index type. They are represented internally with Index[label, type], and all the representations that have been defined are valid index types. Bar is used to denote conjugate indices for indices in pseudoreal or complex representations. Complex and pseudoreal representations are always supposed to contract between conjugate indices with the same label.

Having defined groups and representations it becomes possible to define new CGs for use in calculations. Matchete needs information about the representation of all indices on the CG symbol and should have an exact numerical tensor to substitute in for the symbol when performing contractions with other CGs. Currently, there are two ways for the user to specify a new CG symbol to the program.

The most direct way of defining a CG is to use DefineCG. It requires 3 arguments: a label, a list of the representations of the indices, and an explicit sparse array with the numerical values for the tensor. Typically, the functions made available for the group invariants are used to construct/find explicit invariant tensors as detailed in Group Magic.

For indices of non-real representations, we need to distinguish between the indices and the conjugates. For instance, the Kronecker delta δⁱ_j associated with fund comes with a fundamental and an anti-fundamental index of SU(3). It contracts (is an invariant of) an anti-fundamental and a fundamental representations: the order is reversed. We may specify that an index of a CG belongs to the conjugate representation by applying a Bar to the representation name.

N.b. The user has a lot of flexibility when defining new CGs, but it requires meticulous care to get it right. We encourage the user to perform crosschecks wherever possible, to ensure that their CGs behave as expected.

Clearly, many other invariants can be constructed, but DefineCG will already be sufficient for most purposes. Sometimes it can be useful to construct new CGs from contractions of previously defined CGs, rather than use the rather less transparent InvariantTensors function to obtain a suitable numeric tensor. In such cases we can use the DefineCompositeCG to initialize the CG. The first argument is the CG label; the second argument is a list of CGs to be included in this tensor; and the third and last argument is a list of list of index labels for each of the CGs, with repeated indices being contracted and the rest open.

The basic object in computations involving CGs is the CG head. The first argument of CG specifies the specific tensor (its label); the second argument is a list of its indices. For convenience we can enter a CG by specifying only the labels of the indices rather than entering them as Index objects. The full indices are automatically constructed based on the CG object. One can only enter CG objects that have already been initialized in the current session. Thus, Matchete never encounters unknown CGs. The CG objects are conveniently formatted under NiceForm, so that the user doesn't have to see the internal representation.

Other than constructing the indices, CG does not do any evaluation: there is nothing to evaluate. Rather it is just the internal representation of a CG tensor. Sometimes one might wish to use the complex conjugate CG. Bar can be applied to CGs to get the complex conjugate.

N.b. When applying Bar to a CG it turns the indices of any non-real representation into indices of the conjugate representation and vice versa.

Several functions are available to remove already loaded definitions of groups, representations, and CGs. When removing any of these, the functions automatically removes all associated definitions that rely on the one removed. These functions can be convenient when making mistakes during the setup of a model or something similar. In most other cases, the user may simply rely on ResetAll, which also removes all group definitions.

To evaluate contractions between CGs, we use the function ContractCGs , which will evaluate CG contractions appearing in all terms of an expression. That is ContractCGs carries out all Einstein summation between CGs, producing a result with no dummy-index contractions between CGs . To see how this works in practice, consider the following examples:

ContractCGs is a versatile implementation of all manner of CG contractions. This versatility is due to contractions being performed numerically, a technique that is generally applicable to all possible CG contractions. However, numerical contractions of tensors can be computationally expensive, especially if the representations are large.

Finally, we see what happens when the predefined CGs are insufficient to identify a CG showing up in a product. In that case a new CG will simply be added and a message is displayed to inform the user about it. Any new CG defined this way can be used in CG objects same as any user defined CGs.

Some detective work is typically required to figure out what a new CG is. Particularly if it got defined deep in some Matchete calculation outside the control of the user. It can also happen that a CG is defined during the course of an evaluation but never makes it to the output. The first clue is to look at the message informing about the creation of the new CG, which provides a list of the representation of all the indices of the new CG. In some simple cases the user might be able to identify the CG through the explicit tensor representation with GetCGTensor, although more often than not this is next to meaningless to humans (and basis dependent). More commonly, the new CG can be traced back by using ReplaceCGs[expr] to re-expand the new CG. By default ReplaceCGs replaces all composite CGs created both by the user an automatically. Using the option CGsToReplace (default All), only the specified CGs will be replaced in an expression.

The user might wonder what then is the reason for adding the new CG at all if we simply wish to deconstruct it again? The benefit is that it simplifies expressions, and removes all internal index contractions, which helps identify and collect terms in complicated expressions.

When dealing with new composite CGs showing up in a calculation, it can at times be beneficial to go back to the beginning and add a specific suitable CG to the basis (with definite symmetries) rather than relying on those that are automatically defined. Matchete does not attempt to be clever when assigning new CGs but takes the first new contraction that goes outside its basis as a new basis element with no consideration for further practicalities.