1 Introduction

The description of QCD color structure in the presence of many external colored partons is a field of increased importance. Some methods for performing automatic color summations of fully contracted vacuum bubbles, for example as implemented in FeynCalc [1], in the C program COLOR  [2], or as presented in [3], have been around for a while, and recently a more flexible Mathematica package, ColorMath [4], allowing color structures with any number of open indices, has been published. Yet other general purpose event generator codes, such as MadGraph  [5], have separate built in routines for dealing with the color structure.

In the present paper a stand-alone C++ code, ColorFull, designed for dealing with color contraction using color bases is presented.Footnote 1 ColorFull  is written with interfacing to event generators in mind, and is currently interfaced to Herwig++ (2.7) [6, 7], but can also be used as a stand-alone package for investigations in color space.

ColorFull  is based on trace bases [8–16], where the basis vectors are given by (products of) closed and open quark-lines, but the code also offers functionality for reading in and treating any (orthogonal) basis for color space, such as multiplet bases [17, 18].

The intent of this paper is to convey the underlying idea of ColorFull. For full technical details we refer to the online Doxygen documentationFootnote 2. To set the stage, a brief introduction to the QCD color space is given in Sect. 2 and the trace basis approach is presented in Sect. 3. Following this, some remarks about the computational strategy are made in Sect. 4 and the key design features are presented in Sect. 5, whereas examples of stand-alone usage are given in Sect. 6, and the interface to Herwig++  is commented upon in Sect. 7. The following section, Sect. 8, describes the classes of ColorFull  and code validation is discussed in Sect. 9. Finally some concluding remarks are made in Sect. 10.

2 Color space

Apart from four-gluon vertices for which the color structure can be rewritten in terms of (one-gluon contracted) triple-gluon vertices, the QCD Lagrangian contains

(2.1)

and

(2.2)

where we follow the convention of reading the fully anti-symmetric structure constant indices in counter clock-wise order. The color structure of any amplitude, tree-level or beyond, pure QCD or not, can thus be expressed in terms of these objects alone. For observables we are – as QCD is confining – only interested in color summed/averaged quantities.

Letting \(\mathbf {c}_1\) denote the color structure of the amplitude under consideration, we are thus interested in \(|\mathbf {c}_1|^2\) where the scalar productFootnote 3 is given by summing over all external color indices, i.e.,

$$\begin{aligned} \left\langle \mathbf {c}_1 | \mathbf {c}_2 \right\rangle =\sum _{a_1,\,a_2,\,\ldots }\mathbf {c}_1^{* a_1\,a_2\ldots } \, \mathbf {c}_2^{a_1\,a_2\ldots } \end{aligned}$$
(2.3)

with \(a_i=1,\ldots ,N_c\) if parton i is a quark or an anti-quark and \(a_i=1,\ldots ,N_c^2-1\) if parton i is a gluon.

Clearly, in any QCD calculation, the color amplitudes, \(\mathbf {c}_1\) and \( \mathbf {c}_2\), may be kept as they are, with color structure read off from the contributing Feynman diagrams. Alternatively – and this is likely to be the preferred solutions for more than a few partons – they may be decomposed into a color basis (spanning set), such as a trace basis [8–16], a color flow basis [19] or a multiplet basis [17, 18].

3 Trace bases

One way of organizing calculations in color space is to use trace bases [8–16]. To see that this is always possible, we note that the triple-gluon vertex can be expressed as

(3.1)

where \(T_R\) is the normalization of the SU(\(N_c\)) generators, \(\text{ tr }(t^a t^b)=T_R\delta ^{ab}\), commonly taken to be 1 / 2 or 1.

Using this relation on every triple-gluon vertex in any amplitude results in general in a sum of products of (connected) traces over SU(\(N_c\)) generators and open quark-lines. More specifically, there is one open quark-line for every incoming quark/outgoing anti-quark and outgoing quark/incoming anti-quark. (Note that, from a color perspective outgoing anti-quarks are equivalent to incoming quarks; we will here refer to them collectively as quarks. Similarly outgoing quarks are equivalent to incoming anti-quarks, and will be referred to as anti-quarks.)

To further simplify the color structure, we may contract every internal gluon propagator (which after application of Eq. (3.1) connects quark-lines) using the Fierz (completeness) relation

(3.2)

From this we see that every amplitude in QCD, at any order, may be expressed as a sum of products of open and closed quark-lines, where all gluon indices are external indices. The set of all such products of quark-lines can thus be used as a spanning set for any QCD process, for example, for one \(q\overline{q}\)-pair and seven gluons, we may have color structures of form

(3.3)

for all possible gluon permutations, as well as color structures with more or fewer traces. We here refer to this type of basis as a trace basis, although we remark that when the number of gluons, \(N_g\), plus the number of \(q\overline{q}\)-pairs, \(N_q\), exceeds \(N_c\), this spanning set is overcomplete, and hence strictly speaking not a basis. For \(N_g+N_q\le N_c\), the bases are not overcomplete, but they are still non-orthogonal, having non-diagonal scalar products being suppressed by powers of \(N_c\). Only in the \(N_c\rightarrow \infty \) limit, are these bases minimal and orthogonal.

As a simple, but non-trivial example, we may consider the basis needed for \(q_1 \overline{q}_2 \rightarrow g_3 g_4\). The basis, which is constructed by connecting quarks and gluons in all allowed ways [16] is given byFootnote 4

(3.4)

To all orders in perturbation theory in the \(N_c\rightarrow \infty \) limit, one can prove that the number of basis vectors can be found using the recursion relation [17]

$$\begin{aligned} N_{\mathrm{vec}}[N_q, N_g]&= N_{\mathrm{vec}}[N_q, N_g-1](N_g-1+N_q) \nonumber \\&\quad + N_{\mathrm{vec}}[N_q, N_g-2](N_g-1) \, , \end{aligned}$$
(3.5)

where

$$\begin{aligned} N_{\mathrm{vec}}[N_q, 0]= & {} N_q!\;,\;\;\; N_{\mathrm{vec}}[N_q, 1]=N_qN_q!\;. \end{aligned}$$
(3.6)

In the gluon-only case, at tree-level, the only color structures that can appear are traces over generators, meaning that a general tree-level gluon amplitude can be decomposed as

(3.7)

That only fully connected color structures enter in tree-level gluon amplitudes can easily be understood from the decomposition of Feynman diagrams into basis vectors; upon application of Eq. (3.1) all external gluons remain attached to a quark-line, and – while contracting internal gluons using the Fierz identity, Eq. (3.2) – they remain connected to the same quark-line, as the color suppressed terms cancel each other out. (This can be proved by a short calculation.) The same cancellation appears for gluon exchange between a quark and a gluon, meaning that also tree-level color structures for one \(q\overline{q}\)-pair and \(N_g\) gluons must be of the “fully connected” form of a trace that has been cut open, an open quark-line,

(3.8)

i.e., only the first two basis vectors in Eq. (3.4) are needed. However, when the Fierz identity is applied directly to a gluon exchange between quarks, as in Eq. (3.2), both terms do appear, and color structures with up to \(N_q\) disconnected quark-lines may appear even at tree-level.

Starting from a trace basis tree-level color structure, for example a single trace over gluons, and exchanging a gluon between two partons may split off a disconnected color structure, such as in

(3.9)

Thus, counting to \(l_g\) additional gluon exchanges (on top of a tree-level diagram), the color structures can not consist of more than \(\text{ max }(1,N_q)+l_g\) open and closed quark-lines, two in the above case. In general, when any Feynman diagram is decomposed into a trace basis, there can be at most \(N_q+\lfloor N_g/2 \rfloor \) quark-lines, since all gluons may be disconnected from the quarks, but no gluon can stand alone in a trace, giving the factor \(\lfloor N_g/2 \rfloor \).

For NLO color structures having a quark-loop in the Feynman diagram, the quark-loop is necessarily connected to the remaining color structure via at least one gluon exchange, unless the Feynman diagram consists of only gluons attached to one quark-loop, in which case the trace basis decomposition is trivial. In general it may be connected to more tree-level color structures, for example of form

(3.10)

where the gray blobs denote any tree-level color structures. For each color structure connected to the quark-loop (gray blob), contracting the connecting gluon gives a term where the quark-loop is disconnected if the connecting gluon goes to a quark, the second term in

(3.11)

If the quark-loop is not connected to any other color structure (there is no remaining gray blob in the equation above), the resulting color structure thus contains one more single trace meaning that, decomposed in the trace basis, we get one more quark-line than at tree-level. (For purely gluonic processes, no additional trace will appear.) The same argument can be applied repeatedly if the Feynman diagram contains more than one closed quark-loop, giving (similar to the gluon case) no more than \(\text{ max }(N_q,1)+l_q\) quark-lines for \(l_q\) quark-loops.

Finally, we note that, if, on top of the quark-loops, there are also \(l_g\) loops from gluon exchanges in the Feynman diagram, these may contribute with up to one additional quark-line each (such as in Eq. (3.9)), completing the argument that for \(n_l=l_q+l_g\) loops, a general color structure in pure QCD can be written in terms of sums of products of closed and open quark-lines, where each product contains at most \(\text{ min }[\text{ max }(1,N_q) +n_l, N_q+\lfloor N_g/2 \rfloor ]\) traces and open quark-lines.

4 Computational strategy

The ColorFull  strategy for treating color space is based on the above observations, i.e.,

  • For given external particles (quarks, anti-quarks and gluons), we may always decompose the color space into a linear combination of closed and open quark-lines, as described in Sect. 3. (Other color bases may be expressed in terms of linear combinations of these terms.)

  • We can always evaluate scalar products by first replacing triple-gluon vertices using Eq. (3.1), then removing all gluon propagators using Eq. (3.2), and finally contracting the remaining product of \(q\overline{q}\)-delta functions.

The above outlined procedure for calculating scalar products has the advantages of being conceptually easy, and of covering all contractions occurring in QCD. It has the disadvantage of potentially giving a very large number of terms, since every replacement of a structure using Eq. (3.1) may double the number of terms, and similarly, so does naive application of the Fierz identity, Eq. (3.2).

In order to mitigate this potential explosion of terms upon index contraction, the ColorFull  procedure for scalar product contraction is:

  1. 1.

    Contract all quark-ends, giving a sum of products of closed quark-lines.

  2. 2.

    On the individual quark-lines, contract all neighboring gluons (giving a factor \(C_F\)) and all next to neighboring gluons, giving a factor \(-T_R/N_c\) each, as only the color suppressed term in the Fierz identity, Eq. (3.2), survives. Also, contract traces of two gluons, \(\text{ tr }(t^{g_1}t^{g_2}) = \delta ^{g_1 g_2}T_{R}\).

  3. 3.

    Look for gluons to contract within the quark-lines. Each such contraction may give rise to two terms, but at least the new traces tend to be shorter.

  4. 4.

    Look for gluon index contractions between the quark-lines.

In this way all color indices can be iteratively contracted. To further speed up calculations, ColorFull  can use memoization to save calculated topologies, meaning that contractions that differ only by a relabeling of indices are performed only once. This significantly speeds up the calculations.

5 ColorFull at a glance

ColorFull  is designed to handle the contraction of QCD color indices, to decompose the QCD color space using (trace) basis vectors, and to describe the effect of gluon exchange and gluon emission. In particular, ColorFull  can, for arbitrary \(N_c\):

  • Square any QCD amplitude and calculate any interference term.

  • Create a trace basis for any number of quarks and gluons, and to arbitrary order.

  • Read in and write out color bases, including non-trace bases.

  • Calculate scalar product matrices, i.e., the matrices of scalar products between the basis vectors, write these out and read them in again.

  • Describe the effect of gluon exchange, including calculating the color soft anomalous dimension matrices.

  • Describe the effect of gluon emission.

ColorFull  can also be interfaced to Herwig++  (\(\ge \) 2.7) via Matchbox  [20] and can thus easily be used for event generation with Herwig++.

5.1 Technical overview

This section is intended to give an overview of ColorFull. For examples, the reader is referred to Sect. 6, for overviews of the classes to Sect. 8, and for details, the tables in the Appendix A, as well as the online Doxygen documentation.

Table 1 Below is a complete list of the ColorFull  classes, ordered by dependence, such that, a certain class only depends on classes standing above it in the list
Full size table

As contraction of indices gives rise to polynomials in \(N_c\), \(T_R\) and \(C_F\), ColorFull  by necessity needs minimal classes for dealing with such polynomials. This is implemented in the classes \(\mathtt {Monomial}\)  (a single term in a polynomialFootnote 5), \(\mathtt {Polynomial}\)  (a sum of Monomials), \(\mathtt {Poly\_vec}\)  (a vector of Polynomials) and \(\mathtt {Poly\_matr}\)  (a matrix of Polynomials).

For the color structure itself, ColorFull  uses the class \(\mathtt {Quark\_line}\)  for treating an individual closed or open quark-line, a class \(\mathtt {Col\_str}\)  for treating a product of Quark_lines  and a class \(\mathtt {Col\_amp}\)  for treating a general color amplitudes, i.e., a linear combination of Col_strs.

For performing numerical evaluations, taking the leading \(N_c\) limit, evaluating scalar products, and describing gluon emission and exchange, ColorFull  has a library class \(\mathtt {Col\_functions}\).

Finally, ColorFull  has classes for describing color bases. The classes intended for the user, \(\mathtt {Trace\_basis}\), Tree_level_gluon_basis  and Orthogonal_basis, are derived from the base class Col_basis  (in the case of the first two via the class Trace_type_basis).

All ColorFull  classes are listed in Table 1 according to dependencies, meaning that each class only depends on classes listed above it. The next section will give an introduction to using ColorFull  in stand-alone mode.

6 Stand-alone usage

ColorFull  is mainly designed to deal with relatively large color spaces where it is advantageous to use bases in which color structures coming from Feynman diagrams – or alternative recursive strategies – are decomposed.

For trace bases, the bases may be automatically created by ColorFull. For example, a basis for 1 \(q\overline{q}\)-pair, 3 gluons and 0 loops (in pure QCD) can be created using

$$\begin{aligned} \mathtt {Trace\_basis \ MyBasis(1,3,0);}. \end{aligned}$$
(6.1)

The last argument is provided to avoid carrying around basis vectors for which the kinematic factors vanish to a certain order in perturbation theory. It can be skipped upon which an all order basis vector is created.

To view the resulting basis, it can be written out to a stream (cout) or to a file, either with default filename (no argument) or a user supplied name,

$$\begin{aligned}&\mathtt {cout << MyBasis;} \nonumber \\&\mathtt {MyBasis.write\_out\_Col\_basis} \nonumber \\&\quad \mathtt {("ColorResults/MyBasis");} \end{aligned}$$
(6.2)

resulting in

$$\begin{aligned}&\displaystyle \mathtt {0}\;\;\;\; \mathtt {[\{1,3,4,5,2\}]} \nonumber \\&\displaystyle \mathtt {1}\;\;\;\; \mathtt {[\{1,3,5,4,2\}]} \nonumber \\&\displaystyle \mathtt {2}\;\;\;\; \mathtt {[\{1,4,3,5,2\}]} \nonumber \\&\displaystyle \mathtt {3}\;\;\;\; \mathtt {[\{1,4,5,3,2\}]} \nonumber \\&\displaystyle \mathtt {4}\;\;\;\; \mathtt {[\{1,5,3,4,2\}]} \nonumber \\&\displaystyle \mathtt {5}\;\;\;\; \mathtt {[\{1,5,4,3,2\}]} \end{aligned}$$
(6.3)

where, for example,

(6.4)

If no argument is supplied to MyBasis.write_out_Col_basis(), the basis is written out to a file with a default filename, in this case CF_TB_q_1_g_3. The bases can thus be written out and saved for future purposes. For reading in a basis MyBasis.read_in_Col_basis("path/to/filename") can be used.

The option of reading in bases is particularly useful for the Orthogonal_basis  class. Presently ColorFull  can not automatically create orthogonal multiplet bases, such as in [17], but externally created (orthogonal) bases, with basis vectors expressed in terms of sums of products of traces, may be read in and used. For the Orthogonal_basis  class, the orthogonality is then utilized to significantly speed up the calculation of scalar products. For a non-orthogonal basis it is necessary to evaluate all scalar products between all basis vectors, which can be done as

$$\begin{aligned} \mathtt {MyBasis.scalar\_product\_matrix();}. \end{aligned}$$
(6.5)

\(\mathtt {Polynomial}\)  and double versions of the scalar product matrix are then calculated and saved in the member variables P_spm and d_spm. For larger bases, the evaluation can be sped up by only calculating the numerical version using MyBasis.scalar_product_matrix_num(). The content of P_spm and d_spm can be explored by using the \(\mathtt{<<}\) operator, but it may also be saved to a file using the Col_basis  member functions write_out_P_spm() and write_out_d_spm() which write out the result in ColorFull  and Mathematica, readable format, by default to a file with a default filename in the directory ColorResults. Alternatively the user may supply a filename as argument.

While the intended usage of ColorFull  is to use color bases, ColorFull  can also directly define color amplitudes

$$\begin{aligned}&\mathtt {Col\_amp \ Ca1("[\{1,3,2\}(4,5)]");} \slash \slash (t^{g3})^{q1}{}_{q2} \text{ tr }(t^{g4}t^{g5} ) \nonumber \\&\mathtt {Col\_amp \ Ca2("[\{1,3,4,5,2\}]");} \slash \slash (t^{g3}t^{g4}t^{g5})^{q1}{}_{q2}\nonumber \\ \end{aligned}$$
(6.6)

and evaluate scalar products using the scalar_product member function in the \(\mathtt {Col\_functions}\)  library class

$$\begin{aligned}&\mathtt {Col\_functions \ Col\_fun;} \nonumber \\&\mathtt {Col\_fun.scalar\_product(Ca1,Ca1);} \\&\mathtt {Col\_fun.scalar\_product(Ca1,Ca2);} \nonumber \end{aligned}$$
(6.7)

giving the results TR*Nc^2*CF^2 and TR*Nc*CF^2, respectively.

In several contexts, such as parton showers, cancellation of infrared singularities in NLO calculations, and recursive methods for calculating amplitudes [21], it is of interest to know the effect of gluon emission on a color structure. This can be calculated by using the \(\mathtt {Col\_functions}\)  member function emit_gluon

$$\begin{aligned} \mathtt {Col\_fun.emit\_gluon(Ca1,3,6);} \end{aligned}$$
(6.8)

resulting in

$$\begin{aligned} \mathtt {[\{1,3,6,2\}(4,5)]-[\{1,6,3,2\}(4,5)]}. \end{aligned}$$
(6.9)

The sign conventions here and elsewhere are such that every gluon inserted after the emitter in the quark-line comes with a plus sign and every gluon inserted before comes with a minus sign. In a basis-decomposed calculation, one would be interested in this result decomposed in the large basis required for one additional gluon. Having a trace basis for this larger vector space, this decomposition can be calculated using

$$\begin{aligned}&\mathtt {Trace\_basis \ LargerBasis(nq,ng+1);} \\&\mathtt {LargerBasis.new\_vector\_numbers(Cs, emitter);}\nonumber \end{aligned}$$
(6.10)

where Cs is the \(\mathtt {Col\_str}\)  (basis vector in the smaller trace basis) from which the parton emitter emits a new gluon.

Similarly the effect of gluon exchange on a color structure is of interest. ColorFull  offers several functions for dealing with this. Starting with an amplitude, the new amplitude after gluon exchange can be obtained as

$$\begin{aligned} \mathtt {Col\_fun.exchange\_gluon(Ca1, 1, 4);} \end{aligned}$$
(6.11)

resulting in TR[{1,4,5,3,2}]-TR[{1,5,4,3,2}]. ColorFull  also has a function for directly calculating the color correlator, i.e., given a color amplitude \(| \mathbf {c}>\), the quantity \(\left<\mathbf {c}| \mathbf {T}_i \cdot \mathbf {T}_j |\mathbf {c}\right>\) where \(\mathbf {T}_i\) describes the effect of attaching a gluon to parton i. For example

$$\begin{aligned} \mathtt {Col\_fun.color\_correlator(Ca1, 1, 2);} \end{aligned}$$
(6.12)

results in the \(\mathtt {Polynomial}\)  TR^(2)*Nc*CF^(2).

In some situations, such as soft gluon resummation, it is also useful to calculate the soft anomalous dimension matrix, i.e., to have the result of gluon exchange on any basis vector decomposed into the basis. This can be computed automatically using the Col_basis  member function color_gamma. The result is contained in a \(\mathtt {Poly\_matr}\). For this we need the full basis since color structures not present at LO will appear at NLO, etc. Coding

$$\begin{aligned}&\mathtt {Trace\_basis \ MyFullBasis(1,3);} \nonumber \\&\mathtt {MyFullBasis.color\_gamma(1,4);} \end{aligned}$$
(6.13)

for gluon exchange between the partons 1 and 4 results in the matrix

$$\begin{aligned}&\mathtt {\{\{ 0, 0, 0, 0, 0, 0, 0, 0, 1*-1 \ TR, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1*-1 \ TR\},}\nonumber \\&\mathtt {\{ 0, 0, 1 \ TR \ Nc, 0, 0, 0, 0, 0, 1 \ TR, 0, 1 \ TR\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 1 \ TR \ Nc, 0, 0, 1 \ TR, 0, 0, 1 \ TR, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 1*-1 \ TR, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 0, 0, 0, 1*-1 \ TR, 0, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 0, 0, 1*-1 \ TR, 0, 0, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 1 \ TR, 0, 0, 1 \ TR, 0, 0, 1 \ TR \ Nc, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 1*-1 \ TR, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 0, 1*-1 \ TR, 0, 0, 0, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 1*-1 \ TR, 0, 0, 0, 0, 0, 0, 0, 0, 0\}\}}. \end{aligned}$$
(6.14)

In this way all the soft anomalous dimension matrices needed in [22] can easily be recalculated.

While the number of colors in QCD is three, ColorFull  can deal with any \(N_c\), both algebraically and numerically. Numerical evaluation is handled by the \(\mathtt {Col\_functions}\)  class, using the (private) member variables \(\mathtt {Nc}\), \(\mathtt {TR}\)  and \(\mathtt {CF}\). Thus also \(T_R\) and \(C_F\) can be changed independently. The reason for keeping \(C_F\) as a parameter technically independent of \(N_c\) is that this allows for keeping the color suppressed part of \(C_F\), \(-T_R/N_c\), in a consistent way. This choice has proved useful for accounting for sub-leading \(N_c\) effects in several phenomenological studies [23, 24].

To numerically evaluate a \(\mathtt {Monomial}\), \(\mathtt {Polynomial}\), \(\mathtt {Poly\_vec}\)  or \(\mathtt {Poly\_matr}\), the \(\mathtt {Col\_functions}\)  member functions double_num are used, for example we may want the \(N_c=3\) version of a scalar product

$$\begin{aligned}&\mathtt {Col\_fun.double\_num}( \nonumber \\&\quad \mathtt {Col\_fun.scalar\_product(Ca1,Ca1)}); \end{aligned}$$
(6.15)

giving 8.

For comparison, it is of interest to evaluate (squared) amplitudes in the limit \(N_c\rightarrow \infty \). For taking the leading \(N_c\) limit of any of the polynomial classes \(\mathtt {Polynomial}\), \(\mathtt {Poly\_vec}\)  or \(\mathtt {Poly\_matr}\), the \(\mathtt {Col\_functions}\)  member function(s) leading can be used. For example we may take the leading \(N_c\) limit of the matrix in Eq. (6.14),

$$\begin{aligned}&\mathtt {Col\_fun.leading} (\nonumber \\&\quad \mathtt {MyFullBasis.color\_gamma(1,4));} \end{aligned}$$
(6.16)

resulting in the diagonal matrix

$$\begin{aligned}&\mathtt {\{\{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 1 \ TR \ Nc, 0, 0, 0, 0, 0, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 1 \ TR \ Nc, 0, 0, 0, 0, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 0, 0, 0, 0, 1 \ TR \ Nc, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0\},}\nonumber \\&\mathtt {\{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0\}\}}. \end{aligned}$$
(6.17)

For an expression containing \(C_F\), the color suppressed term \(-T_R/N_c\) can be kept in numerical evaluation by setting full_CF to true, Col_fun.set_full_CF(true).

7 Interfacing to Herwig via matchbox

ColorFull  can also be interfaced to Herwig++  (\(\ge \)2.7) [7] via the Matchbox  component [20], and can be used to treat the hard interaction, as in for example [25], as well as the parton shower itself [23]. When linked to Herwig++, ColorFull  is hooked into the boost linear algebra package, enabling a very efficient treatment of numerical linear algebra. From the next major release of Herwig++, ColorFull  will be directly shipped with the Herwig++, code.

8 ColorFull code

8.1 Operators

In order to simplify calculations and increase readability, ColorFull  defines a standard set of operators, listed in Table 2. This includes the arithmetic operators +, - and * as well as the comparison operators, == and !=, and the stream operator \(\mathtt{<<}\). The comparison operators, == and !=, work by comparing data entries term by term, both for the polynomial classes and for the color carrying classes. Thus, for example, two Polynomials  only differing by the order of terms are not considered equal.

Table 2 Standard operators for color structure and polynomial classes. (Operators for both orders of arguments are defined for the arithmetic operators +, - and *.)
Full size table

8.2 Classes for polynomials

The result of color index contraction can always be written as a sum of terms of the form \(N_c{}^a T_R{}^b C_F{}^c \,\times \text{ constant }\) where we allow for negative integers a, b, c. For the purpose of treating contracted color structures, ColorFull  has a minimalistic set of classes for basic manipulation of color factors arising when contracting color indices. One such term is defined as a \(\mathtt {Monomial}\), and a sum of such terms as a \(\mathtt {Polynomial}\). To decompose vectors in a color space we also need a vector of Polynomials, contained in a \(\mathtt {Poly\_vec}\), and for a scalar product matrix (or soft anomalous dimension matrix) we need a matrix of polynomials, a \(\mathtt {Poly\_matr}\).

Apart from the \(\mathtt {Monomial}\)  class, these classes have the actual polynomial information contained in uncapitalized typedefs carrying the same name as the class in question. There are thus \(\mathtt {polynomial}\), \(\mathtt {poly\_vec}\), and \(\mathtt {poly\_matr}\)  typedefs. For manipulating the polynomial classes, the operators listed in Table 2 may be used. For example, we may multiply a \(\mathtt {Polynomial}\)  and a \(\mathtt {Monomial}\).

8.2.1 Monomial

The simplest class for containing contracted color information is a \(\mathtt {Monomial}\)

$$\begin{aligned}&\mathtt {Monomial}\sim \mathtt {Nc}^{\mathtt {pow\_Nc}} \, \mathtt {TR}^{\mathtt {pow\_TR}} \, \mathtt {CF}^{\mathtt {pow\_CF}} \nonumber \\&\quad \times \mathtt {\mathtt{int\_part }} \times \mathtt {{cnum\_part}}. \end{aligned}$$
(8.1)

The exponents \(\mathtt {pow\_Nc}\), \(\mathtt {pow\_TR}\) and \(\mathtt {pow\_CF}\), as well as int_part  are of type int and cnum_part  is a cnum, an \(\mathtt {std::complex<double>}\). These member variables carry the information about the actual monomial.

By default, using the standard constructor,   \(\mathtt {Monomial}\) (), a \(\mathtt {Monomial}\)  is set to 1, by letting cnum_part=1, int_part=1 and setting all powers to 0Footnote 6. A \(\mathtt {Monomial}\)  with different integer part can be obtained by using the constructor taking an int as argument, and a general \(\mathtt {Monomial}\)  can be constructed using the string constructor (see Table 3 in Appendix A.

8.2.2 Polynomial

A sum of Monomials  is contained in the class \(\mathtt {Polynomial}\)

$$\begin{aligned}&\displaystyle \mathtt {Polynomial}\sim \mathtt {Monomial}_0 + \mathtt {Monomial}_1+ \cdots \nonumber \\&\displaystyle \mathtt {poly}\end{aligned}$$
(8.2)

where, technically, the polynomial information is stored in the public member \(\mathtt {poly}\), of type \(\mathtt {polynomial}{=}\mathtt {std::vector<Monomial>}\). ColorFull  is not designed for manipulating polynomials but \(\mathtt {Polynomial}\)  nevertheless has a minimalistic simplify() function which collects terms with equal power of \(N_c\), \(T_R\) and \(C_F\). It also has a remove_CF() function for replacing \(C_F\) with \(T_RN_c-T_R/N_c\). Details about the \(\mathtt {Polynomial}\)  class can be found in Table 4 in Appendix A.

8.2.3 Poly_vec

For dealing with vectors of Polynomials, ColorFull  has a class \(\mathtt {Poly\_vec}\)

$$\begin{aligned} \begin{array}{ccccc} \mathtt {Poly\_vec}&{} \sim &{} (\mathtt {Polynomial}_0, \mathtt {Polynomial}_1, \ldots )\\ &{} &{} \mathtt {pv} \end{array}. \end{aligned}$$
(8.3)

\(\mathtt {Poly\_vec}\)  is a container class for functions acting on vectors of Polynomials  whereas the actual information is stored in the \(\mathtt {poly\_vec}\,{=}\,\mathtt {typedef \ std::vector}\,{<}\mathtt {Polynomial>}\) data member, pv. The member functions of \(\mathtt {Poly\_vec}\), which include simplify() and remove_CF(), can be found in Table 5 in Appendix A.

8.2.4 Poly_matr

Finally, there is a class for treating matrices of Polynomials, a \(\mathtt {Poly\_matr}\),

$$\begin{aligned}&\begin{array}{ccc} \mathtt {Poly\_matr}&{} \sim &{} \{\{\mathtt {Polynomial}_{00}, \mathtt {Polynomial}_{01}, \ldots , \mathtt {Polynomial}_{0n}\} \\ &{}&{} \vdots \\ &{}&{} \;\; \{\mathtt {Polynomial}_{m0}, \mathtt {Polynomial}_{m1}, \ldots , \mathtt {Polynomial}_{mn}\}\} \\ &{}&{} \mathtt {pm} \end{array} \end{aligned}$$
(8.4)

which stores the matrix information as a vector of vectors of Polynomials, a \(\mathtt {poly\_matr=typedef \ std::}\mathtt {vector<Poly\_vec>}\). Again, details can be found in the Appendix A, in Table 6.

8.3 Classes containing the color structure

This section describes the building blocks used by ColorFull  to treat the color structure. All classes used to carry the color structure, \(\mathtt {Quark\_line}\), \(\mathtt {Col\_str}\), \(\mathtt {Col\_amp}\), including the basis classes Col_basis  – from which Trace_type_basis, \(\mathtt {Trace\_basis}\), Tree_level_gluon_basis  and Orthogonal_basis  are derived – have the property that the actual information of the color structure is contained in a type with corresponding name, whereas the class acts as a container for related functions. Thus, for example, the color amplitude information in a \(\mathtt {Col\_amp}\)  is contained in a \(\mathtt {col\_amp}\)  variable.

8.3.1 Quark_line

The most basic color carrying class is a \(\mathtt {Quark\_line}\). Loosely speaking, a \(\mathtt {Quark\_line}\)  is a \(\mathtt {quark\_line}\)  times a \(\mathtt {Polynomial}\),

$$\begin{aligned} \begin{array}{ccccc} \mathtt {Quark\_line}&{} \sim &{} \mathtt {Polynomial}&{} \times &{} \mathtt {quark\_line}\,\\ &{} &{} \mathtt {Poly} &{} \times &{} \mathtt {ql},\\ \end{array} \end{aligned}$$
(8.5)

where the \(\mathtt {quark\_line}\)  (a \(\mathtt {std::vector<int>}\)) ql contains the actual quark-line information, together with the boolean variable open which is true if the quark-line is open, and false for a trace over gluon indices. The \(\mathtt {quark\_line}\)  is multiplied by a \(\mathtt {Polynomial}\). For example, we may have the closed \(\mathtt {Quark\_line}\)

(8.6)

or the open \(\mathtt {Quark\_line}\)

$$\begin{aligned} \mathtt {Nc \ TR \ \{1,3,4,2\} }\sim & {} N_cT_R\; (t^{g_3}t^{g_4})^{q_1}{}_{q_2}. \end{aligned}$$
(8.7)

Quark_lines  may be created using the Quark_line(std::string) constructor. Closed quark-lines are denoted by standard parenthesis, whereas curly brackets represent open quark-lines. For example, we may write

(8.8)

for the above quark-lines. Among the \(\mathtt {quark\_line}\)  member functions we especially note the functions for contracting neighboring and next to neighboring gluon indices, contract_neighboring_gluons() and contract_next_neighboring_gluons(), as well as the normal_order() member function which orders a closed \(\mathtt {Quark\_line}\)  such that the smallest gluon index is written first. Thus, for example

$$\begin{aligned}&\mathtt {Quark\_line}\; \mathtt {Ql("(2,3,4,4,5,1)");} \nonumber \\&\mathtt {Ql.contract\_neighboring\_gluons();} \\&\mathtt {Ql.normal\_order();} \nonumber \end{aligned}$$
(8.9)

results in \(\mathtt {CF}\) (1,2,3,5). The other public member functions are listed in Table 7 in Appendix A.

8.3.2 Col_str

A general color amplitude consists not only of one quark-line, but of a linear combination of products of Quark_lines. One term in this linear combination, a \(\mathtt {Polynomial}\)  times a product of closed and open quark-lines is contained in a \(\mathtt {Col\_str}\),

$$\begin{aligned} \begin{array}{ccccc} \mathtt {Col\_str}&{} \sim &{} \mathtt {Polynomial}&{} \times &{} \mathtt col\_str \\ &{} &{} \mathtt {Poly} &{} \times &{} \mathtt {cs}\\ \end{array}. \end{aligned}$$
(8.10)

Here the actual information about the color structure is carried by a col_str, (technically a vector of Quark_lines), for example we may thus have

(8.11)

Like the other color classes, Col_strs  may be created using a string constructor

(8.12)

where we note that the col_str  is written inside square brackets. The \(\mathtt {Polynomial}\)  should multiply the whole col_str, rather than individual quark_lines.

The \(\mathtt {Col\_str}\)  member functions, listed in Table 8 in Appendix A, overlap to a high degree with the \(\mathtt {Quark\_line}\)  member functions. In particular there are functions for contracting neighboring and next to neighboring gluons, and a normal_order member function. Apart from normal ordering the individual Quark_lines, the \(\mathtt {Col\_str}\)  normal_order() member function sorts the Quark_lines  as described in Table 8, where the public members of \(\mathtt {Col\_str}\)  are listed.

For \(\mathtt {Col\_str}\)  (and \(\mathtt {Quark\_line}\)  and \(\mathtt {Col\_amp}\)), there is also a simplify() member function. This function removes quark-lines with 0 quarks, (these are \(\mathtt {Nc}\)  for closed Quark_lines  and 1 for open Quark_lines), normal orders the col_strs, and simplifies the Polynomials. Potential Polynomials  multiplying individual Quark_lines  are also moved to the \(\mathtt {Col\_str}\)  member variable Poly.

8.3.3 Col_amp

The linear combination of Col_strs  which in general is needed to keep track of a color structure is contained in a \(\mathtt {Col\_amp}\). In order to contain scalar results, i.e., terms not containing any color structure (which arise in the process of color contraction) a \(\mathtt {Col\_amp}\)  also contains a \(\mathtt {Polynomial}\)  part, Scalar,

For example, we may have the \(\mathtt {Col\_amp}\)

(8.13)

where Scalar is 0, and the Polynomials  multiplying the Col_strs  (1,2)(3,4) and (1,2,3,4) are 1 and 1/Nc respectively.

Also the \(\mathtt {Col\_amp}\)  class has a string constructor which reads in to the \(\mathtt {col\_amp}\)  part according to the syntax

$$\begin{aligned}&\mathtt {Col\_amp}\; \mathtt {Ca("[(1,2,3,4)]-1/Nc} \mathtt {[(1,2)(3,4)]");}.\nonumber \\ \end{aligned}$$
(8.14)

As for \(\mathtt {Quark\_line}\)  and \(\mathtt {Col\_str}\), \(\mathtt {Col\_amp}\)  has member functions for contracting all neighboring and next to neighboring gluons. Gluon contraction between gluons which are further away on the \(\mathtt {Quark\_line}\)  may result in a sum of Quark_lines. Such contractions cannot be seen as actions on a single \(\mathtt {quark\_line}\)  and are therefore not implemented in the \(\mathtt {Quark\_line}\)  and \(\mathtt {Col\_str}\)  classes. Instead the \(\mathtt {Col\_amp}\)  class contains functions for contracting a gluon or contracting all gluons in the \(\mathtt {Col\_amp}\). These functions are intended for Col_amps  with closed Quark_lines, i.e., quarks should be contracted first, using contract_quarks( \(\mathtt {Col\_amp}\) 1, \(\mathtt {Col\_amp}\) 2). When calculating a scalar product, all quark indices are thus contracted first, followed by all the gluon indices. The complete list of public member functions is given in Table 9 in Appendix A.

8.4 Col_functions: a library class

\(\mathtt {Col\_functions}\)  is a library class containing functions which cannot, in a natural way, be attributed to one class, or functions which act on many classes and are therefore conveniently collected into one class.

In particular, \(\mathtt {Col\_functions}\)  contains classes for evaluating scalar products, for numerical evaluation, for taking the leading \(N_c\) limit, and for describing the effect of gluon emission or gluon exchange.

8.4.1 Numerical evaluation

\(\mathtt {Col\_functions}\)  is the class which carries numerical values of \(N_c\), \(T_R\) and \(C_F\), stored in the private members \(\mathtt {Nc}\), \(\mathtt {TR}\)  and \(\mathtt {CF}\)  respectively. To numerically evaluate a \(\mathtt {Monomial}\)  to a double or a complex number (cnum) the function cnum_num or double_num is used

$$\begin{aligned}&\mathtt {Col\_functions}\mathtt {\; Col\_fun;} \nonumber \\&\mathtt {Monomial}\mathtt {\; Mon;} \nonumber \\&\mathtt {Col\_fun.cnum\_num(Mon);} \\&\mathtt {Col\_fun.double\_num(Mon);} \nonumber \end{aligned}$$
(8.15)

The syntax for numerical evaluation of Polynomials, Poly_vecs  and Poly_matrs  is identical.

8.4.2 Leading \(N_c\) evaluation

\(\mathtt {Col\_functions}\)  also contains functions for taking the leading \(N_c\) limit of the classes \(\mathtt {Polynomial}\), \(\mathtt {Poly\_vec}\)  and \(\mathtt {Poly\_matr}\). The leading \(N_c\) terms can be evaluated in two different ways, either by taking the strict \(N_c\rightarrow \infty \) limit and dropping all color suppressed terms (default), or by keeping the color suppressed terms in \(C_F=T_R(N_c^2-1)/N_c\), while dropping other color suppressed terms. For keeping the full \(C_F\) in numerical evaluations the member variable full_CF must be set to true using set_full_CF(true).

8.4.3 Scalar products

Scalar products are evaluated using the \(\mathtt {Col\_functions}\)  member functions scalar_product,

$$\begin{aligned}&\mathtt {Col\_str}\mathtt {\; Cs1("[\{1,3,4,2\}(5,6)]");} \nonumber \\&\mathtt {Col\_str}\mathtt {\; Cs2("[\{1,3,4,5,6,2\}]");} \nonumber \\&\mathtt {Col\_amp}\mathtt {\; Ca1(Cs1);} \nonumber \\&\mathtt {Col\_amp}\mathtt {\; Ca2(Cs2);} \nonumber \\&\mathtt {Col\_fun.scalar\_product(Ca1,Ca2);} \\&\mathtt {Col\_fun.scalar\_product(Cs1,Cs2);} \nonumber \end{aligned}$$
(8.16)

in both cases resulting in \(T_RN_cC_F^3\).

8.4.4 Gluon exchange and gluon emission

For soft gluon resummation, for NLO calculations, and for the cancellation of real emissions and virtual corrections in the soft limit, the color structure associated with gluon exchange plays an important role. The \(\mathtt {Col\_functions}\)  class therefore has functions for describing the effect of gluon exchange on a \(\mathtt {Col\_str}\)  or on a \(\mathtt {Col\_amp}\). For example, we may exchange a gluon between parton 3 and 6 in Cs1

$$\begin{aligned} \mathtt {Col\_fun.exchange\_gluon(Cs1,3,6);} \end{aligned}$$
(8.17)

resulting in the \(\mathtt {Col\_amp}\)

$$\begin{aligned}&\mathtt {-TR[\{1,5,6,3,4,2\}]+TR[\{1,3,5,6,4,2\}]} \\&\quad \mathtt {+TR[\{1,6,5,3,4,2\}]-TR[\{1,3,6,5,4,2\}]}. \end{aligned}$$

To understand the signs we note that each time a gluon is inserted before the emitter on a (closed or open) quark-line there is a minus sign, and each time a gluon is inserted after, there is a plus sign. We also note that in this case, the result of gluon exchange on a single color structure gave rise to a linear combination of four color structures, the maximal possible number of color structures from a single col_str  [16].

In the context of gluon exchange we also remark that \(\mathtt {Col\_functions}\)  can calculate the “color correlator”, \(\left<\mathbf {c}|\mathbf {T}_i \cdot \mathbf {T}_j|\mathbf {c}\right>\) arising when coherently emitting a gluon from parton i and j in an amplitude \(|\mathbf {c}>\), or when exchanging a gluon between the partons i and j in \(|\mathbf {c}>\). For example we can calculate the color correlator for exchanging a gluon between parton 1 and 4 in Ca1,

$$\begin{aligned} \mathtt {Col\_fun.color\_correlator(Ca1,1,4);} \end{aligned}$$
(8.18)

resulting in a \(\mathtt {Polynomial}\)  with value \(T_R^3 C_F^{2} + T_R^2 N_cC_F^3\).

Sometimes, for example in the context of a parton shower, one may be interested in the effect of gluon emission itself. Starting in a \(\mathtt {Col\_amp}\)  Ca1 and emitting a gluon, 7, from parton 3 this may be found using

$$\begin{aligned} \mathtt {Col\_fun.emit\_gluon(Ca1,3,7);} \end{aligned}$$
(8.19)

giving the \(\mathtt {Col\_amp}\)  [{1,3,7,4,2}(5,6)]-[{1,7,3,4,2}(5,6)].

8.5 Classes for color bases

Although ColorFull  may perform calculations with individual Quark_lines, Col_strs  and Col_amps, the intended usage is via the color basis classes \(\mathtt {Trace\_basis}\)  (in particular), Tree_level_gluon_basis  and Orthogonal_basis.

As these classes share much of the most important functionality, they all inherit from one base class, Col_basis. The \(\mathtt {Trace\_basis}\)  and Tree_level_gluon_basis  classes inherit from Col_basis  via Trace_type_basis, whereas Orthogonal_basis  inherits directly from Col_basis.

8.5.1 Col_basis

The Col_basis  class has a col_basis  member variable cb for containing the basis vectors,

$$\begin{aligned} \begin{array}{cc} \mathtt {Col\_basis} &{} \sim \mathtt {col\_basis} \\ &{} \mathtt {cb} \end{array}. \end{aligned}$$
(8.20)

Col_basis  also carries information about the number of quarks and the number of gluons in the public members nq and ng, and (if it has been calculated) the scalar product matrix in polynomial form, P_spm, and in double form, d_spm, as well as the leading (see Sect. 8.4.2) scalar product matrix in polynomial and double versions, leading_P_spm and leading_d_spm.

The most important Col_basis  member function is probably the scalar_product_matrix() function which calculates the matrix of scalar products between the basis vectors. In its default from, this function uses memoization, as this speeds up the calculations, but this may be circumvented in using the scalar_product_matrix_no_mem() version.

In order not to have to calculate scalar product matrices over and over again Col_basis  also has functions for reading in and writing out scalar product matrices, both in numerical and polynomial form.

Col_basis  also contains functions for reading in and writing out the basis itself. This is essential for the Orthogonal_basis  class which cannot (presently) construct the orthogonal bases, but may read them in.

The decomposition of color amplitudes into bases is done with the (virtual) decompose(\(\mathtt {Col\_amp}\)) member function, which does the decomposition by exploring the coefficients in front of traces and products of traces for \(\mathtt {Trace\_basis}\)  and Tree_level_gluon_basis  and by evaluating scalar products for the Orthogonal_basis  case.

Another important function is the color_gamma function which (using decompose) calculates the soft anomalous dimension matrix, i.e., calculates the matrix describing the effect of gluon exchange between two partons. The result is returned as a Poly_matr where component i, j gives the amplitude for ending up in vector i, if starting in vector j, see also Sect. 6. A list of public members and functions for Col_basis  is found in Table 11.

8.5.2 Trace_type_basis

Trace_type_basis  is a small helper class for keeping track of functions which are similar for \(\mathtt {Trace\_basis}\)  and Tree_level_gluon_basis. It inherits from Col_basis  and is inherited from by \(\mathtt {Trace\_basis}\)  and Tree_level_gluon_basis. Most importantly, this is where decompose is implemented for these two classes, see Table 12.

8.5.3 Trace_basis

Although the observation that each color amplitude may be decomposed into products of open and closed quark-lines is a guiding principle for ColorFull, the \(\mathtt {Trace\_basis}\)  class itself is rather small, containing mainly functions for creating bases.

A trace basis is created by first contracting all \(q\overline{q}\)-pairs in all \(N_q!\) ways, and then attaching gluons to these closed quark-lines, and to additional closed quark-lines, such that at least two gluons are attached to each closed quark-line.

This can be done either directly using a constructor

$$\begin{aligned} \mathtt {Trace\_basis}\; \mathtt {Tb(2,2);} \end{aligned}$$
(8.21)

or as

$$\begin{aligned}&\mathtt {Trace\_basis}\; \mathtt {Tb;} \nonumber \\&\mathtt {Tb.create\_basis(2,2)}; \end{aligned}$$
(8.22)

The result, which can be written out to a user given or default file (write_out_Col_basis) or to cout (using \(\mathtt{<<}\)) has the basis vectors

$$\begin{aligned}&\mathtt {0} \ \mathtt {[\{1,5,6,2\}\{3,4\}]} \nonumber \\&\mathtt {1} \ \mathtt {[\{1,5,6,4\}\{3,2\}]} \nonumber \\&\mathtt {2} \ \mathtt {[\{1,6,5,2\}\{3,4\}]} \nonumber \\&\mathtt {3} \ \mathtt {[\{1,6,5,4\}\{3,2\}]} \nonumber \\&\mathtt {4} \ \mathtt {[\{3,5,6,2\}\{1,4\}]} \nonumber \\&\mathtt {5} \ \mathtt {[\{3,5,6,4\}\{1,2\}]} \nonumber \\&\mathtt {6} \ \mathtt {[\{3,6,5,2\}\{1,4\}]} \\&\mathtt {7} \ \mathtt {[\{3,6,5,4\}\{1,2\}]} \nonumber \\&\mathtt {8} \ \mathtt {[\{1,5,2\}\{3,6,4\}]} \nonumber \\&\mathtt {9} \ \mathtt {[\{1,5,4\}\{3,6,2\}]} \nonumber \\&\mathtt {10} \ \mathtt {[\{1,6,2\}\{3,5,4\}]} \nonumber \\&\mathtt {11} \ \mathtt {[\{1,6,4\}\{3,5,2\}]} \nonumber \\&\mathtt {12} \ \mathtt {[\{1,2\}\{3,4\}(5,6)]} \nonumber \\&\mathtt {13} \ \mathtt {[\{1,4\}\{3,2\}(5,6)]} \nonumber \end{aligned}$$
(8.23)

At tree-level, in pure QCD, the last two basis vectors vanish. To create a basis which is only valid up to order n_loop in pure QCD, we may use the create_basis(n_quark, n_gluon, n_loop) member function. See Table 13 for member functions.

8.5.4 Tree_level_gluon_basis

In the case of gluon-only color structures, charge conjugation implies that each trace must appear with its conjugate, in linear combinations of the form \(\text{ tr }[t^{g1}t^{g2}\ldots t^{gn}] + (-1)^{N_g}\text{ tr }[t^{gn}\ldots t^{g2}t^{g1}]\). In the trace type basis class Tree_level_gluon_basis  this is used to reduce the number of basis vectors and speed up calculations. More information can be found in Table 14.

8.5.5 Orthogonal_basis

ColorFull  can not – in its present form – automatically create multiplet bases. However, orthogonal bases may be read in using the (Col_basis) function read_in_Col_basis(std::string) member function.

For dealing with orthogonal bases, ColorFull  offers special functions for calculating the matrix of scalar products and decomposing vectors. The syntax for basis reading is the same as for basis writing. Bases thus appear much as in Eq. (8.23), see Tables 11 and 15.

9 Validation

For a code with order 10,000 lines, validation is essential. For this reason ColorFull  is continuously validated using a test suite, which aims at testing all the various components. The applied tests starts with checking basic functions for reading in and writing out files, and dealing with polynomials. After this, the creation of bases is tested, and scalar products are tested by changing the order of index contraction, and by switching on and off memoization. The scalar product matrices have further been tested against ColorMath  [4] and, for processes occurring in the context of [25], also against another private Mathematica code. The functions describing gluon emission and gluon exchange are cross-checked against each other.

10 Conclusion and outlook

ColorFull, a C++ stand-alone QCD color algebra package, designed for interfacing with event generators, has been presented.

ColorFull  is based on trace bases, which can automatically be created, and color contraction is performed by repeated usage of the Fierz identity. Employing these bases, one can in principle describe any QCD process. In reality, the scalar product matrices, which may be calculated once and for all, become hard to manage for more than approximately 8 gluons plus \(q\overline{q}\)-pairs. This limitation is inherent for the trace bases, since they are non-orthogonal, and for this reason ColorFull  is written to be able to load and use orthogonal (multiplet) bases.

ColorFull  does, however, not – in its present form – perform index contraction in terms of group invariants as described in for example [18, 26]. Extending ColorFull  to inherently construct orthogonal multiplet bases and efficiently perform index contraction using 3j and 6j coefficient may speed up the treatment of QCD color space very significantly.