1 Introduction

The experimental success of the standard model (SM) of particle physics and the absence of new physics (NP) signals so far seem to hint at the presence of a mass gap between the SM degrees of freedom and the new dynamics. In this case, departures from the SM at energies much smaller than the new physics scale can be described using effective field theory (EFT) methods. The so-called standard model EFT (SMEFT) parametrizes possible deviations from the SM caused by heavy degrees of freedom in a model independent way.

The SMEFT Lagrangian is organized as an expansion in powers of \(1/\Lambda \), where \(\Lambda \) represents the new physics scale and compensates the canonical dimension of the effective operators. The leading order of the SMEFT corresponds to the renormalizable SM Lagrangian. Dominant new physics contributions to most processes of interest are expected to be encoded in the Wilson coefficients (WC) of effective operators of canonical dimension six [1].

In recent years, a non-redundant basis for the dimension-six SMEFT operators was derived [2]. This basis is currently known as the Warsaw basis. The complete one-loop anomalous dimension matrix (ADM) for the dimension-six operators has been calculated very recently in this basis [3,4,5,6]. These advances, together with simultaneous theoretical developments occurring in the field (such as in the matching of specific models to the SMEFT at one loop [7,8,9,10,11,12, 14, 15] and in the automatization of calculations within the SMEFT [13]), pave the way to the systematic use of EFT methods in the analysis of new physics models. The power of the SMEFT approach is that it allows to relate physics at disparate energy scales, in our case properties of the high-energy dynamics at the scale \(\Lambda \), with measurements that take place at low energies, while performing an expansion in \(1/\Lambda \) that allows to keep leading new physics effects in a consistent manner. Here we present DsixTools, a Mathematica Footnote 1 package that aims to facilitate such enterprise.

Given some initial conditions for the Warsaw basis at the high-energy scale \(\Lambda \), obtained from the matching of a UV model to the SMEFT, DsixTools  allows the user to perform the full one-loop renormalization group evolution (RGE) down to the electroweak scale. Furthermore, when the physics of interest lies well below the electroweak scale, it is useful to perform a matching of the dimension-six basis to a low-energy EFT in the broken electroweak phase. In the so-called weak effective theory (WET), the SM heavy degrees of freedom (top quark, Higgs, \(W^{\pm }\) and Z) have been integrated out. DsixTools  implements the tree-level matching of the Warsaw basis to \(\Delta B = \Delta S = 1,2\) and \(\Delta B = \Delta C = 1\) operators of the WET based on the results obtained in [17]. Last but not least, the relevant effects due to QCD and QED running from the electroweak scale down to the b-quark mass scale in the WET is also implemented in DsixTools, using the results in [18].

DsixTools  is structured into different modules, each of them taking care of a specific task. Their functionality is described in Sect. 2. Section 3 explains how to download and load DsixTools whereas a detailed review of DsixTools and its modules is given in Sect. 4. A summary is given in Sect. 5. Finally, this manual includes several appendices to document all the features present in DsixTools: Appendix A contains details of the conventions used for the implementation of the SMEFT, Appendix B contains the SMEFT RGEs, Appendix C describes relevant aspects of the WET, Appendix D contains a detailed description of the DsixTools routines, Appendix E is devoted to compile the SMEFT and WET parameters list and Appendix F gives results for the Baryon-number-violating operators in the fermion mass basis.

Fig. 1
figure 1

DsixTools ’ global flowchart. The user can provide input to each module or use the results obtained with the previous one

2 DsixTools in a nutshell

DsixTools is a modular package, with each module performing an independent task related to dimension-six effective operators. The different modules can be easily communicated with each other, since one module’s output can be used as input for another module. In practice, this means that a particular project with DsixTools can involve all modules or just a few, depending on the user’s goals. Figure 1 shows the global flowchart of DsixTools.

The current version of DsixTools contains three independent modules, called: SMEFTrunner, EWmatcher and WETrunner. The SMEFTrunner module implements:

  • The SM contribution to the one-loop RGEs of the SM parameters [19,20,21,22].

  • The one-loop RGEs for the dimension-six operators in the Warsaw basis from Refs. [3,4,5].Footnote 2

  • The one-loop RGEs for the dimension-six Baryon-number-violating operators using the results in [6].

The EWmatcher module implements:

  • The tree-level matching of the Warsaw basis to the \(\Delta B = \Delta S = 1,2\) and \(\Delta B = \Delta C = 1\) operators of the WET at the electroweak scale, using the results in [17].

The WETrunner module implements:

  • QCD and QED RGEs in the WET from the electroweak scale down to the low-energy scale \(\Lambda _\mathrm{IR}\). The WETrunner module fixes by default \(\Lambda _\mathrm{IR} = m_b\), the b-quark mass scale, and uses the RGEs derived in [18].

Fig. 2
figure 2

Functionality of DsixTools  modules

The functionality of the DsixTools  modules is illustrated in Fig. 2, where one can also see how they relate to the different energy ranges and effective theories. Relevant details of the SMEFT and WET implementations are given in Appendix A–Appendix C, where our conventions are also presented.

3 Downloading and loading DsixTools

DsixTools  is free software under the copyleft of the GNU General Public License. It can be downloaded from the web page [23]:

https://dsixtools.github.io

After placing the DsixTools  folder in the Applications folder of the Mathematica  base directory, the user can load DsixTools  with the command

figure a

Alternatively, the user can place the DsixTools  folder in a given directory and call the package by specifying its location via

figure b

before executing the Needs command. We also recommend to use

figure c

at the beginning of all projects with DsixTools.

Fig. 3
figure 3

SMEFTrunner module flowchart

4 Using DsixTools

In this section we describe how to use DsixTools in detail. Once the package has been loaded, the user can already execute some basic I/O functions and routines. Several global variables are also introduced at this stage. Here we list the general DsixTools routines:

  • LoadModule[moduleName]: Loads the DsixTools module moduleName.

  • MyPrint[string]: Prints the message string. It can be switched on and off by using the DsixTools routines TurnOnMessages and TurnOffMessages.

  • TurnOnMessages: Turns on the messages written by DsixTools.

  • TurnOffMessages: Turns off the messages written by DsixTools.

  • ReadInputFiles[options_file, WCsInput_ file, {SMInput_file}]: Reads all the input files. The third argument is optional and should be absent when the routine is used to read WET input.

  • WriteInputFiles[options_file, WCsInput _file, {SMInput_file},data]: Creates input files with the parameter values in data. The third argument is optional and should be absent when the routine is used to write WET input.

  • WriteAndReadInputFiles[options_file, WCsInput_file,{SMInput_file}]: Writes data into new input files and then reads them. The third argument is optional and should be absent when the routine is used to write and read WET input.

  • NewInput[parameter,newvalue,dispatch]: Replaces the current input (contained in the Mathematica dispatch dispatch) by a new one in which parameter takes the value newvalue.Footnote 3

  • NewScale[scale,newvalue]: Replaces the current value of scale by newvalue. Here scale can be either “high” or “low”.

  • H[mat]: Returns the Hermitian conjugate of the matrix mat. If the option CPV has been set to 0 then it returns the transpose.

  • CC[x]: Returns the complex conjugate of x. If the option CPV is set to 0 then it returns x.

A more detailed description of these DsixTools routines can be found in Appendix D.1. Once DsixTools is loaded the user can already perform some basic operations. However, the real power of DsixTools resides in its modules. A project with DsixTools can involve one or many modules, depending on the user’s goals. For instance, if one is interested in the running of WET operators between the electroweak scale and the b-quark mass scale, the WETrunner module suffices for the task. But if one wants to study the RGE evolution of the SMEFT operators and their matching to WET ones at the electroweak scale, both the SMEFTrunner and EWmatcher modules must be included in the project. In the following we proceed to describe the existing modules, the routines they include and how they can be combined together in a practical DsixTools project.

4.1 SMEFTrunner module

The SMEFTrunner module takes care of the one-loop RGE of the SMEFT between the high-energy scale \(\Lambda \) and the electroweak scale. The module is based on the anomalous dimension matrices computed in [3,4,5] (for the Baryon-number-conserving operators) and [6] (for the Baryon-number-violating operators). This is the list of routines implemented in this module:

  • InitializeSMEFTrunnerInput: Initializes the input for the SMEFTrunner module.

  • FindParameterSMEFT[parameter]: Returns the position in which parameter is located within the Parameters list.

  • GetBeta: Computes the SMEFT \(\beta \) functions.

  • LoadBetaFunctions: Constructs the SMEFT \(\beta \) functions or reads them from a file.

  • RunRGEsSMEFT: Runs the SMEFT RGEs.

  • ExportSMEFTrunner: Exports the SMEFTrunner results to an output file.

  • WriteSMEFTrunnerOutputFile[Output_ file,data]: Exports the SMEFTrunner results in data to Output_file.

More details about these routines can be found in Appendix D.2.

The general flowchart of the SMEFTrunner module can be seen in Fig. 3. The first step is to read the input. This not only includes the numerical values of the SMEFT WCs at the high-energy scale \(\Lambda \), but also the numerical values of the SM parameters and some options. The input and output format of DsixTools  is inspired by the Supersymmetry Les Houches Accord (SLHA) [24, 25]. A complete options card would read:

figure d

For this particular example we have chosen the default options. In fact, if a flag is not present in the options file, its value will be taken as in this example. The user defines the high-energy and electroweak scales in the first block. We see that in this example the electroweak scale is fixed to 80.385 GeV, the W-boson mass, whereas the high-energy scale is \(\Lambda = 10\) TeV. Then the user defines several options. For instance, in this case CP-violation has been switched off by setting CPV to 0, but the user can also consider complex parameters setting CPV to 1. The comments accompanying the other options are self-explanatory, but we will review them below. A sample of a typical input card for the SM parameters is as follows:

figure e

Again, the input values are distributed in blocks, each devoted to a set of parameters. For instance, the SM gauge couplings are given in the block GAUGE. We note that the Yukawa matrices (and in general any complex parameter) are given in two blocks. For the up-quark Yukawas these are GU and IMGU: the first one is used for the real parts and the second for the imaginary ones. By default, the SM parameters are assumed to be given at the electroweak scale, where their experimental values are known. Then, before running down from \(\Lambda \) to the electroweak scale they must be computed at \(\Lambda \). This is done by running up from the electroweak scale using pure SM RGEs, hence neglecting possible deviations caused by non-zero SMEFT WCs.Footnote 4 However, in case the user prefers to give the SM parameters directly at high-energy scale \(\Lambda \), this can be done by setting the UseRGEsSM option to 0 or, equivalently, by introducing a 0 in flag number 5 of the options file,

figure f

This choice is recommended when the user wants to use the First leading log method to solve the RGEs, see below. Finally, a standard input card for the SMEFT WCs reads:

figure g

The notation for the operators is self-explanatory:

$$\begin{aligned}&\mathtt {Block WC1} \\&Q_G = f^{ABC} G_\mu ^{A \nu } G_\nu ^{B \rho } G_\rho ^{C \mu } \\&Q_{{\widetilde{G}}} = f^{ABC} {\widetilde{G}}_\mu ^{A \nu } G_\nu ^{B \rho } G_\rho ^{C \mu } \\&Q_W = \varepsilon ^{IJK} W_\mu ^{I \nu } W_\nu ^{J \rho } W_\rho ^{K \mu } \\&Q_{\widetilde{W}} = \varepsilon ^{IJK} {\widetilde{W}}_\mu ^{I \nu } W_\nu ^{J \rho } W_\rho ^{K \mu } \, \\&\mathtt {Block WC2} \\&Q_{\varphi } = \left( \varphi ^{\dagger } \varphi \right) ^3 \, \\&\mathtt {Block WC3} \\&Q_{\varphi \Box } = \left( \varphi ^{\dagger } \varphi \right) \Box \left( \varphi ^{\dagger } \varphi \right) \\&Q_{\varphi D} = \left( \varphi ^{\dagger } D^\mu \varphi \right) ^*\left( \varphi ^{\dagger } D_\mu \varphi \right) \\&\cdots \\&\mathtt {Block WCUPHI} \\&Q_{u \varphi }[1,1] = \left( \varphi ^{\dagger } \varphi \right) \left( \bar{q}_1 u_1 \widetilde{\varphi }\right) \\&Q_{u \varphi }[1,2] = \left( \varphi ^{\dagger } \varphi \right) \left( \bar{q}_1 u_2 \widetilde{\varphi }\right) \\&\cdots \\&Q_{u \varphi }[3,3] = \left( \varphi ^{\dagger } \varphi \right) \left( \bar{q}_3 u_3 \widetilde{\varphi }\right) \end{aligned}$$

It is important to note that all WCs are assumed to vanish by default. Therefore, it suffices to include the non-zero WCs (and only these) in the input card. The rest can be absent.

In addition to getting input values at \(\Lambda \), the SMEFTrunner module constructs the SMEFT RGEs and prepares a routine for their evaluation. There are two ways to do this: (i) to “compute” the RGEs, or (ii) to read them from a file. In the first case, DsixTools takes their saved forms and computes all flavor traces and expands over all possible indices. In the second case, DsixTools simply reads them from a file (already present in the DsixTools folder). In both cases, the command to give this step is LoadBetaFunctions. The user can choose between these two methods in the options file using flag number 2. Method (i) is more time consuming but provides nice-looking \(\beta \) functions in Mathematica format. This would be very useful for analytical studies. Moreover, the user can obtain these equations at any moment by using the routine GetBeta. Method (ii) is much faster and produces the RGEs in the format required for their immediate evaluation with the SMEFTrunner routines (in particular with RunRGEsSMEFT).

Once both the initial conditions (input values at \(\Lambda \)) and the RGEs are completely built, the user can apply the RGE to obtain the goal of SMEFTrunner: the SMEFT WCs at the electroweak scale. This is done with the RunRGEsSMEFT routine. We have implemented two different methods for the resolution of the RGEs:

  • “Exact”: This method applies the Mathematica internal command NDSolve for the numerical resolution of differential equations. Given the large number of differential equations involved in this case (several thousand), this might be time consuming, with each evaluation requiring a few (<10) seconds, the exact number depending on the particular case and computer.

  • First leading log: This approximate method might be sufficient for many phenomenological studies, in particular when \(\Lambda \) is not too far from the electroweak scale. The solution of the RGEs is obtained as

    $$\begin{aligned} C_i(\mu ) = C_i(\Lambda ) + \frac{\beta _i}{16 \pi ^2} \log \left( \frac{\mu }{\Lambda } \right) \,, \end{aligned}$$
    (4.1)

    where \(C_i\) is any of the running parameters, \(\mu \) is the renormalization scale and \(\beta _i\) is the \(\beta \) function for the \(C_i\) evaluated at \(\mu = \Lambda \). This method is much faster but neglects subleading effects.

Fig. 4
figure 4

EWmatcher module flowchart

The user chooses between these two methods by setting the global option RGEsMethod to 0 (for the NDSolve method) or 1 (for the first leading log approximate method). This is also done via flag number 3 in the options card. After running, the results are saved in the array outSMEFTrunner as a function of \(t = \log _{10} \mu \). The ordering of the parameters is the same as in the Parameters global array, see Appendix E.Footnote 5 Moreover, two important values of t are predefined: tLOW (\(=\log _{10} \mu _\mathrm{EW}\)) and tHIGH (\(=\log _{10} \Lambda \)). Therefore, for instance, one can obtain the value of the \(\left[ C_{e \varphi } \right] _{12}\) at the electroweak scale by evaluating

figure h

Finally, the output of SMEFTrunner can be exported to a text file. This is done by running ExportSMEFTrunner. The file Output_SMEFTrunner.dat is then generated, also with an SLHA format, completely analogous to the SMEFT WCs input card.

4.2 EWmatcher module

The EWmatcher module applies the tree-level matching of the Warsaw basis of the SMEFT to the \(\Delta B = \Delta S = 1,2\) and \(\Delta B = \Delta C = 1\) operators of the WET. For this purpose we make use of the analytical results obtained in [17]. This is the list of routines implemented in this module:

  • InitializeEWmatcherInput: Initializes the input for the EWmatcher module.

  • FindParameterWET[parameter]: Returns the position where parameter is located within the WETParameters list.

  • Biunitary[mat,dim]: Applies a biunitary transformation that diagonalizes the dim \(\times \) dim matrix mat.

  • RotateToMassBasis: Transforms the SMEFT WCs to the fermion mass basis.

  • ApplyEWmatching: Matches the SMEFT WCs onto the WET WCs.

  • Match[WC]: Returns the value of the WET Wilson coefficient WC after matching it to the SMEFT.

  • MatchAnalytical[WC]: Returns the analytical expression of the WET Wilson coefficient WC after matching it to the SMEFT.

  • WriteWCsMassBasisOutputFile[Output_ file]: Exports the SMEFT 2- and 4-fermion WCs in the fermion mass basis to Output_file.

  • ExportEWmatcher: exports the EWmatcher results to an output file.

  • WriteEWmatcherOutputFile[Output_file, data]: Exports the EWmatcher results in data to Output_file.

Appendix D.3 contains more details about these routines and functions.

The EWmatcher module flowchart can be seen in Fig. 4. The first step is, as usual, to determine the input of the module. If the SMEFTrunner module has preceded the EWmatcher, the input is automatically created using the output of the former. Otherwise, the user can also provide an input file and start the DsixTools project with the EWmatcher module as first step.

In what concerns the input card, the same WCsInput.dat file that is read by the SMEFTrunner module can also be used as WCs input for the EWmatcher module. Instead of interpreting the input values as given at \(\mu = \Lambda \), the EWmatcher module will interpret them as given at \(\mu = \mu _\mathrm{EW}\).

Next, the EWmatcher transforms the SMEFT WCs to the fermion mass basis, applying the required biunitary transformations to the fermion mass matrices.Footnote 6 This necessary step is done by means of the RotateToMassBasis routine and gives, as a result, the SMEFT WCs in the fermion mass basis, generally denoted as \(\widetilde{C}_i\).Footnote 7 In case the user is particularly interested in these coefficients, they can be exported to an external text file by running

figure i

Furthermore, RotateToMassBasis also creates the replacements array ToMassBasis, which can be used to print the numerical values of the SMEFT WCs in the fermion mass basis. For example,

figure j

would print the numerical value of the coefficient \(\big [{\widetilde{C}}_{\ell \ell }\big ]_{1122}\).

The next step is the matching to the WET operators. For this the user must execute

figure k

This creates the arrays BS2, BC1, BS1Hunprimed, BS1Hprimed, BS1GB, BS1SLunprimed and BS1SLprimed, containing the numerical values of the WET WCs at the electroweak scale. While BS2 and BC1 contain the results for the \(\Delta B = \Delta S = 2\) and \(\Delta B = \Delta C = 1\) coefficients, respectively, the other arrays contain the results for the \(\Delta B = \Delta S = 2\) ones, split into several sub-arrays with hadronic (H), semileptonic (SL) and magnetic, or gauge boson (GB) involving, WCs. They can also be accessed individually thanks to the function Match. For example, CBS1[e][1] // Match would print the numerical value of \(C_1^{bsee}\). If one is interested in the analytical expression after matching the function to use is MatchAnalytical, which only replaces the energy scales and the SM parameters by their numerical values.

Finally, the output of EWmatcher can be exported to a text file. This is done by running ExportEWmatcher, which generates the file Output_EWmatcher.dat with a compilation of all results obtained with this module.

4.3 WETrunner module

The WETrunner module is devoted to the RGE of the WET WCs between the electroweak scale and the infrared scale \(\Lambda _\mathrm{IR}\). In the current version of DsixTools, \(\Lambda _\mathrm{IR}\) is set by default at b-quark mass scale, \(m_b = 4.18\) GeV, and the RGE is based on the analytical results obtained in Ref. [18]. This is the list of routines implemented in this module:

  • InitializeWETrunnerInput: Initializes the input for the WETrunner module.

  • RunRGEsWET: Runs the WET RGEs.

  • ExportWETrunner: Exports the WETrunner results to an output file.

  • WriteWETrunnerOutputFile[Output_file, data,scale]: Exports the WETrunner results in data to Output_file after evaluating them at \(\mu =\) scale.

For more details about these routines see Appendix D.4.

Fig. 5
figure 5

WETrunner module flowchart

The general flowchart of the WETrunner module can be seen in Fig. 5. As for the EWmatcher module, the input for the WETrunner can be obtained directly (and automatically) from the previous module (EWmatcher in this case) if this is run before. Otherwise, the user can also provide new input values and begin a DsixTools project in this step of the chain. In this case, the input card for the WET WCs, which we will call WCsInput.dat as for the SMEFT ones, also follows a simple SLHA-inspired format:

figure l

We see that the first block gives the input value for the electroweak scale while the other blocks give the input values for the WET WCs. In this particular example the only non-vanishing WET WC is \(C_4^{sbsb} = 1\). It is important to note, however, that DsixTools must know that the input WCs are of WET type. This is done via the option inputWCsType, which must be set to 2 (the default value is 1, which indicates SMEFT WCs) before reading the input file with the ReadInputFiles routine. This option choice can also be achieved by using the flag number 9 in the options card:

figure m

Once the input has been read (or taken from the EWmatcher module) one can proceed to the RGE of the WET WCs. The WETrunner module implements an evolution matrix formalism for this step, based on the results of Ref. [18]. This can be performed with the RunRGEsWET which creates the numerical arrays BS2Low, BC1Low, BS1unprimedLow and BS1primedLow, all of them functions of \(t = \log _{10} \mu \). Therefore, in order to find the values of the WET WCs at the b-quark mass scale one can evaluate commands like

figure n

where mb is the global DsixTools variable containing the b-quark mass (in GeV). This command would print the numerical value of \(C_4^{sbsb}(m_b)\). Finally, the results can be exported to an output file with the routine ExportWETrunner. This creates the text file Output_ WETrunner.dat with the values of all WET WCs at the infrared scale.

5 Summary

We have presented DsixTools, a Mathematica package for the handling of the dimension-six SMEFT and WET. DsixTools facilitates the treatment of these two effective theories in a systematic and complete manner.

DsixTools is a modular code. In the current version, it includes three independent modules, designed for specific tasks related to the SMEFT and WET. The SMEFTrunner performs the one-loop RGE from the UV scale \(\Lambda \) to the electroweak scale, the EWmatcher matches the SMEFT Wilson coefficients to the \(\Delta B = \Delta S = 1,2\) and \(\Delta B = \Delta C = 1\) operators of the WET, and the WETrunner runs these down to an IR scale, in this case the b-quark mass scale.

The structure of DsixTools allows for an easy implementation of new modules. Therefore, the current content of the package is expected to grow substantially with future improvements, including additional tools and features. The final outcome of this endevour will be a complete and powerful framework for the systematic exploration of new physics models using the language of effective field theories.