Matchete allows for the derivation of Feynman rules for a given Lagrangian. Moreover, these Feynman rules can be exported in the form of Universal Feynman Output (UFO) [arXiv:1108.2040] [arXiv:2304.09883] files to be used with Monte Carlo event generators such as MadGraph [arXiv:1106.0522].

The core functions are:

As an example for this tutorial, we will consider the dimension-six SMEFT Lagrangian in the Warsaw basis [arXiv:1008.4884].

In the first step, we need to ensure the Matchete package is loaded in the Kernel:

The Warsaw basis Lagrangian in the unbroken electroweak phase, but including all definitions required for the symmetry breaking, can be loaded using:

This will result in a down-aligned broken phase Lagrangian after the SSB routines by default. Alternatively one can use ModelParameters option

to neglect the CKM matrix entirely. The allowed values are "DownAlignment" (default), "UpAlignment", "UnitCKM", and "NoAlignment" (keeping up and down rotations).

Note that by default the model file "SMEFT_Warsaw+breaking" drops all Baryon- or Lepton-number violating operators since these are not supported by MadGraph anyway. If one wants to keep these operators one has to use

The vacuum Lagrangian after electroweak symmetry breaking can be obtained automatically using the definition included in the model file "SMEFT_Warsaw+breaking" and applying the functions ToBrokenPhase and ImplementVacuumConditions.

where we use the option SubstituteMasses -> True to replace the coefficients of the mass terms by the canonical mass couplings of the broken phase.

For more details on the implementation of spontaneous symmetry breaking patterns see the tutorials SMEWSB and SymmetryBrekaing.

In the next step we let Matchete fix the gauge using the GaugeFixLagrangian function:

This employs the R_ξ gauge for all massless and massive vector fields. Alternatively one can use GaugeUnitary to fix the massive vectors to the unitary gauge. Note that GaugeFixLagrangian is a native Matchete function and therefore only allows for these two gauge fixing options. The more restrictive choice of Feynman gauge (ξ=1) can only be made during the UFO generation in the function calls of DefaultParamCard and ExportUFO.

Note that the automatic gauge fixing requires the gauge kinetic terms to have canonical form and hence has to be performed before introducing the electroweak input scheme shifts below (at least for the m_W scheme where the QED gauge couplings is modified).

The Feynman rules of the SMFET in the broken phase can now be derived using the FeynmanRules routine.

As example, consider the three gluon vertex. Its Feynman rule can be derived using:

The objects printed in gray brackets represent the external fields, i.e, for the vector fields shown above they are polarization vectors, whereas for fermion they are spinors, and for scalars they are simply unity and are kept to keep track of indices. Internally, external legs are represented by the head Ext . For example:

The subscripts provide a numbering for the various external fields in every vertex. The external momenta are displayed as , where the superscript indicates to which external field the momenta belongs. Internally, the external momenta are represented trough ExtMom. For example:

Similarly, the rule for the four charged-lepton vertex can be obtained by:

The complete set of Feynman rules for the Warsaw basis can be derived using:

For brevity, only display the first three Feynman rules, which are returned in the form of an association, are displayed below:

In a next step, the UFO files for the SMEFT can be generated using the ExportUFO routine.

Some preparatory manipulations are performed first.

It can be helpful to define new couplings for the Yukawa interactions of the broken phase. This is not necessary in principle, but it allows, for example, to define a massless bottom quark, which has a non-zero Yukawa coupling:

The UFO option allows to specify which names should be used in the UFO files for these parameters. Since these Yukawas are diagonal matrices in flavor space, one name per generation has to be specified. Substituting the new couplings in the Lagrangian is achieved by:

Note that we subtract and than add again the fermion mass (and kinetic) terms using FreeLag such that the replacement does not act on the mass terms itself but only on the other appearances of the mass coupling.

It is useful to define coupling orders for the UFO files to control which interaction should be considered in simulations. To that end, various different coupling orders ("QED", "QCD", "NP", ...) are defined below using DefineCouplingOrder:

This assigns "QED" order 1 to M, M, M, yMd, yMu, yMe, ℯ, gY, and gL, order -1 to v and vT, and order 2 to λ (the order is the inverse of the exponent provided above). In addition, every EFT Wilson coefficient is assigned "QED" order 2 as well. The only QCD parameter gs is assigned "QCD" order 1. Furthermore, two insertions of gs are assigned the same hierarchy as one "QED" order. Every EFT Wilson coefficient is assigned "NP" order 1 with hierarchy 99 to ensure diagrams with at least one BSM vertex are considered by default.

It can also be helpful to define an individual coupling order for every Wilson coefficient to better control which coefficients should be included in simulations. This can be achieved using:

A list of all defined coupling orders can be obtained by:

Note that this only introduces one coupling order per coefficient but not for every flavor combination separately.

The higher-dimensional SMEFT operators contribute to the processes used to extract the values of the SM parameters from experimental data. Therefore, a consistent electroweak input scheme has to be applied, to incorporate these contributions. See for example [arXiv:1706.08945] and [arXiv:2012.11343].

In this example the G_f, m_Z, m_W, m_h input scheme is considered and a new coupling is defined for the shift of every SM parameter except from the input parameters:

The shifts are introduced in the Lagrangian using:

The definition of the actual expressions for these shifts are delegated to the parameter card. For completeness, the full expressions are listed below:

The definitions of the and gauge couplings (δgL and δgY) have been included for convenience. The SMEFT contributions to the input observables read:

A template for the parameter card (excluding the explicit formulae for the shifts above) in form of a JSON file can be obtained using the function DefaultParamCard:

This generates a JSON file named "model_parameters.json" in the directory given by DirectoryUFO, which contains a minimal parametrization of all couplings in terms of a set of non-redundant parameters, exploiting the known symmetries and conjugation properties of the couplings.

Note that while this file can in principle be used to directly generate the UFO files. However, all non-redundant parameters are initialized with the value 0 (except for the ones appearing in denominators which are set to 1 to avoid divergences), which is most likely inconvenient for any application. Therefore, the parameter card file should be edited manually to include the SM input values, the definitions of the electroweak scheme shifts, the masses and widths of all particles, etc. The file can be opened, e.g., using:

Note that specifying the option DefaultValues->True for DefaultParamCard only works for simple models that do not affect the SSB breaking pattern and can therefore not be used for the SMEFT.

Optionally, one can also apply flavor symmetries to further reduce the number of free parameters in the SMEFT and thus the parameter card. This is achieved calling the function ImposeFlavorSymmetry. For example, assuming a U(3)³ flavor symmetry for the fields d, l, and e while taking a U(2)² symmetry for q and u, one can first define the corresponding global symmetry groups:

Note that one has to identify U(N)~SU(N)U(1) since Matchet only allows to define simple groups. The flavor symmetry can then be assigned to the chiral fields in terms of an association, where for every flavor its representations are specified:

Note that the Singlet entries can also be omitted and at most one non-Abelian representation is allowed per flavor, while an arbitrary number of U(1) charges can be given.

This flavor symmetry can then be assigned to a Lagrangian using

This determines for all flavored couplings present in the Lagrangian L the invariants under the flavor groups and associates these to the couplings in form of SparseArrays, which are returned in the form of an association:

One can also exclude some couplings, e.g., the Yukawas, from requiring a flavor invariant structure using the option Except->{Yu,Yd,Ye} for ImposeFlavorSymmetry, which leaves the Yukawas in their most general form. However, the unbroken phase Yukawa have been replaced by the masses anyways in the broken phase.

Note that ImposeFlavorSymmetry requires the Lagrangian L in the unbroken electroweak phase as input, since the flavor symmetry is defined on the level of the chiral fields.

The flavor invariants are then used to parametrize the couplings of the theory when calling DefaultParamCard afterwards with the option FlavorInvariants:

This produces the same parameter card as before, but all couplings forbidden by the symmetry are removed (i.e. their value is set to "ZERO" which will remove them entirely from the UFO files once ExportUFO is called), while the invariant structures are parametrized in a minimal way. The parameter card can again be inspected and modified using:

The UFO files can now be generated using the ExportUFO function:

Here, the option OutputDirectory determines where the UFO files are saved and InputFile should point to the parameter card generated before. If no InputFile is specified, the default parameter card will be used and a UI will open that allows to manually edit the parameters and inputs. In this later case, one can also use the option FlavorInvariants, as above for the call of DefaultParamCard, to provide flavor invariants if desired.
Note that for large models such as the SMEFT, it is not advisable to use this UI as it is unwieldy and rather slow.