FeynRules

A (short) user manual

FeynRules is a Mathematica © based package allowing the calculation of the Feynman rules from a lagrangian.

The FeynRules model-file

The main ingredient used by FeynRules to calculate the Feynman rules from a specific lagrangian is the so-called model-file. The model-file is a text file containing all the information about a specific model (particle content, coupling constants,...) that is read by Mathematica © to initialize the calculation of the Feynman rules. Notice that the structure of the FeynRules model-file is similar to the one encountered for FeynArts. The FeynRules model-file contains in general a fourfold information,

1. the declaration of all the indices that appear inside the lagrangian.
2. a list of all the parameters that appear inside the lagrangian.
3. a list of all the gauge groups.
4. a list of all the particles appearing in the model.

The index declaration

For FeynRules to run properly, all the indices (flavor, gauge,...) have to be declared in the model-file, together with the range of value they can take, e.g.

IndexRange[ Index[Colour] ] = Range[3]

IndexRange[ Index[Gauge] ] = NoUnfold[ Range[8] ]

This declares two indices {{{ Colour }}} and {{{ Gauge }}} which range from 1 to 3 and 1 to 8 respectively. The command {{{ NoUnfold }}} is a FeynArts command that is ignored by FeynRules. Notice that four-vector indices ({{{ Lorentz }}}) and Dirac indices ({{{ Spin }}}) are predefined in FeynRules and do not need to be declared in the model-file.

The user should also tell FeynRules which symbol he should use for each symbol when writing the output (although this is not mandatory, it is strongly recommended, because it makes the output more readable). This is done by including the following lines in the model-file,

IndexFormat[ Colour, i]

IndexFormat[ Gauge, a]

telling FeynRules to print {{{ Colour }}} -indices and {{{ Gauge }}} -indices as {{{ i }}} and {{{ a }}} respectively.

The parameter declaration

The parameter declaration contains all symbols that appear inside the lagrangian and that should be treated as c-numbers, and not as fields. The parameters are entered as a list that must be called {{{ M$Parameters }}}, each element of the list corresponding to a different parameter, together with possible options,

M$Parameters = {
   param1 == { options },
   param2 == { options },
   ...
}

where {{{ options }}} is the list of options associated with each parameter, entered as a Mathematica list of replacements. FeynRules distinguishes between two types of parameters,

1. scalar parameter (e.g. coupling constants, mixing angles,...),
2. tensor parameters (e.g. CKM matrix).

The options for a scalar parameter are

• {{{

ComplexParameter }}} : This options defines whether the parameter should be treated as real ({{{ False }}}) or complex ({{{ True }}}). By default, this option is set to {{{ False }}}.

• {{{

TeX }}} : Fixes this parameter to print in {{{ TeXForm }}} as the right-hand side of the replacement rule.

• {{{

Definitions }}} : a list of replacements rules that should be applied by FeynRules before performing any calculation.

• {{{

Description }}} : a string, describing the parameter (e.g. ="Fermi Constant"=). In addition to these options, several additional options are needed when running interfaces (e.g. the numerical values of the parameters needed for the MC integration). In particular, all parameters must be declared to be either {{{ External }}} or {{{ Internal }}}: an external parameter gets its numerical value form the user , whereas the value of an internal parameter is calculated a posteriori from more fundamental parameters (external as well as internal). By default a scalar parameter is {{{ External }}}. It is important to realize that the external parameters are not necessarily independent one from each other. But the relation linking them to the true primary free parameters is complex enough to justify the use of an external software (called a Calculator in the MadGraph language) to compute them. For example, widths of SM particles are related to the SM parameters and masses but the relation is complex enough to justify the use of the SM calculator. In the other hand some parameters like $\cos(\theta_W)$ are trivially linked to external parameters (like $\sin(\theta_W)$) and should thus be defined as internal, the link relation being defined in FeynRules. One could of course use Mathematica replacement rules to get rid of internal parameters but this would in general badly affect the readability of the generated Fortran code. The full list of MG options for scalar parameters is

• {{{

ParameterType }}} : taking the values {{{ External }}} or {{{ Internal }}}, the default value being {{{ External }}}.

• {{{

OrderBlock }}} : a list which contains the LH block name of the parameter. By default, the block name is {{{ FRBlock }}}.

• {{{

Value }}} :

• for external parameters, the numerical value.
• for internal parameters, the definition in terms of more fundamental parameters (external and internal). The default value is 1 (for both external and internal).

• {{{

InteractionOrder }}} : e.g. the interaction order of $\alpha_s$ is ={QCD, 2}=.

• {{{

ParameterName }}} : The name with which the parameter should be printed in the Fortran output code.

The options for a tensor parameter are

• {{{

Indices }}} (mandatory): list of indices attached to the tensor.

• {{{

TensorClass }}} (mandatory): A name to identify all tensors belonging to the same class, e.g. all Dirac-matrices.

• {{{

Unitary }}} : defines unitary matrices ({{{ True }}} or {{{ False }}})

• {{{

Hermitian }}} : defines hermitian matrices ({{{ True }}} or {{{ False }}})

• {{{

Orthogonal }}} : defines orthogonal matrices ({{{ True }}} or {{{ False }}})

• {{{

Definitions }}} : a list of replacements rules that should be applied by FeynRules before performing any calculation. Notice that, unlike scalar parameters, tensor parameters are by default complex. Tensor parameters are by default internal (the components are in general specified by a small number os parameters, like for example mixing angles). We must thus add in the mode the definition of the components of the tensor in terms of more fundamental parameters (e.g. the CKM matrix for two quark generations can be defined by the Cabibbo angle)

• {{{

Value }}} : the definition in terms of more fundamental parameters (external and internal).

There is an additional option for tensor parameters having only one index. Let us suppose we want to write into the lagrangian a Yukawa coupling of the form %\[ y_f H \bar{\psi}f\psif\]% where {{{ f }}} is a flavor index running from 1 to 3. For FeynRules to run properly, it is necessary that all indices are connected properly, i.e. connected two by two. This of course is not satisfied by a term like this. However, it can be achieved by adding to the list of options for the one-index tensor parameter {{{ y }}} the option {{{ NoTensor -> True }}}. This option tells FeynRules to ignore the index {{{ f }}} when connecting the indices among each other.

The gauge group declaration

The declaration of the gauge groups follows similar lines as the parameter declaration,

M$GaugeGroups = {
    gaugegroup1 == { options },
    gaugegroup2 == { options },
    ...
}

The options for a gauge group are

• {{{

Abelian }}} (mandatory) : defines the gauge group to be abelian ({{{ True }}}) or not ({{{ False }}}).

• {{{

GaugeBoson }}} (mandatory) : the name of the gauge boson associated to the gauge boson (notice that this symbol must be declared during the parameter declaration).

• {{{

StructureConstant }}} (mandatory for non abelian groups) : the symbol associated to the structure constants of the group.

• {{{

Charge }}} (mandatory for abelian groups) : the symbol associated with the U(1) charge.

• {{{

CouplingConstant }}} (mandatory) : the symbol associated with the coupling constant of the gauge group (notice that this symbol must be declared during the parameter declaration)

• {{{

Representations }}} : a list with the symbols for the different representation matrices used in the lagrangian.

• {{{

Definitions }}} : a list of replacements rules that should be applied by FeynRules before performing any calculation.

The declaration of a U(1) gauge group is then for example

M$GaugeGroups ={
   ...
   U1EM == {
       Abelian -> True,
       GaugeBoson -> A,
       Charge -> Q,
       CouplingConstant -> ee},
   ...
}

Notice that this declaration defines automatically the field strength tensor associated with this gauge group. This field strength tensor can be called in Mathematica by {{{ FS[A, mu, nu] }}}, where {{{ mu }}} and {{{ nu }}} denote the Lorentz indices carried by the field strength tensor.

Similarly, the declaration of an SU(3) gauge group is

M$GaugeGroups ={
   ...
   SU3C == {
       Abelian -> False,
       GaugeBoson -> G,
       StructureConstant -> f,
       CouplingConstant -> gs,
       Representations -> {T, Colour}},
   ...
}

where {{{ T }}} is the symbol representing the SU(3) matrices in the fundamental representation, and {{{ Colour }}} is the name of the gauge index carried by the quarks. Notice that this declaration defines automatically the field strength tensor associated with this gauge group. This field strength tensor can be called in Mathematica by {{{ FS[A, mu, nu,a] }}}, where {{{ mu }}} and {{{ nu }}} denote the Lorentz indices and {{{ a }}} the (adjoint) gauge-index carried by the field strength tensor.

The particle declaration

The declaration of the particle follows similar lines as the parameter and gauge group declaration,

M$ClassesDescription = {
    particle1 == { options },
    particle2 == { options },
    ...
}

The particles are grouped into classes having the same quantum numbers (e.g. neutrinos, charged leptons, up and down-type quarks,...). The right-hand sides of the class declaration must be of the form {{{ F[1] }}}, {{{ F[2] }}},..., {{{ V[1] }}}, {{{ V[2] }}},..., {{{ S[1] }}}, {{{ S[2] }}},..., with

• {{{

S }}} : scalar fields

• {{{

F }}} : fermion fields (Spin 1/2)

• {{{

V }}} : vector fields

• {{{

Sp2 }}} : spin 2 fields The possible options for a particle class are

• {{{

ClassName }}} (mandatory) : The symbol representing the class.

• {{{

SelfConjugate }}} (mandatory): defining whether a field is selfconjugate ({{{ True }}}) or not ({{{ False }}})

• {{{

ClassMembers }}} : a list of all members of the class. If the class contains only one members, this is by default the {{{ ClassName }}}.

• {{{

Indices }}} : a list of all possible indices carried by the field. Notice that the Lorentz-indices ({{{ Lorentz }}}, {{{ Spin }}}) are not included in this list because they are implicit in the class declaration.

• {{{

QuantumNumbers }}} : a list of all quantum numbers (charges,...) carried by the field.

• {{{

FlavorIndex }}} : The name of the index FeynRules should expand over when the {{{ FlavorExpand }}} option is turned to {{{ True }}} during the vertex calculation.

• {{{

Mass }}} : a list of all the masses for all the class members. A mass can be entered as

• the symbol that represents the mass in the lagrangian.
• a two-component list, the first element being the symbol for the mass, and the second being the numerical value.

• {{{

Unphysical }}} : declares auxiliary fields ({{{ True }}}), that should not be used for the output. The default value is {{{ False }}}. The relations of the unphysical fields to the physical ones can be obtained via the {{{ Definitions }}} option.

• {{{

Definitions }}} : a list of replacements rules that should be applied by FeynRules before performing any calculation. Notice that only those elements of {{{ M$ClassesDescription }}} are read where a {{{ ClassName }}} is defined. This allows to write very general model-files, where only those particle declarations are read in where {{{ ClassName }}} is not commented out.

The additional options for the interfaces ignored by FeynRules, are

• {{{

PropagatorLabel }}} : a list of strings by which the lines in the MG output should be labeled.

• {{{

PropagatorType }}} : the linetype, by which the corresponding MG output is drawn. Supported linetypes are:

• {{{

S }}} / {{{ Straight }}} : Straight

• {{{

D }}} / {{{ ScalarDash }}} : Dashed

• {{{

W }}} / {{{ Sine }}} : Wavy

• {{{

C }}} / {{{ Cycles }}} : Curly

• {{{

ParticleName }}} : a list of strings, corresponding to the particle names as they should appear in the {{{ particles.dat }}} file. By default, this is the same as the symbol defined for FeynRules.

• {{{

AntiParticleName }}} : a list of strings, corresponding to the anti-particle names as they should appear in the {{{ particles.dat }}} file. By default, this is the same as {{{ ParticleName }}}, with an extra =~= added.

• {{{

PDG }}} : the PDG code of the particle (or a list containing the PDG codes for each class member). An automatically generated pdg code is is assigned if this options is omitted.

• {{{

GaugeIndex }}} : the index which should be used to obtain the MG colour structure (S, T, O) of the particle. By default, the MG colour structure is S.

• {{{

FullName }}} : a string, specifyinh the full name of the particle (e.g. {{{ Electron }}}), or a list containing the names for each class member. By default {{{ FullName }}} is the same as {{{ ParticleName }}}.

A QCD-type model, containing 3 up-quark generations and a gluon would then correspond to

M$ClassesDefinitions = {
   (* Quarks (u)*)
   F[1] == {
      ClassName -> uq,
      ClassMembers -> {u, c, t},
      FlavorIndex -> Generation,
      SelfConjugate -> False,
      Indices -> {Index[Generation], Index[Colour]},
      Mass -> {{MU, 0.4}, {MC, 3}, {MT, 200}},
      Width -> {{WU, 0}, {WC, 0}, {WT,5}},
      QuantumNumbers -> { Q -> 2/3},
      PropagatorLabel -> {"u", "c", "t"},
      GaugeIndex -> Colour,
      PropagatorType -> Straight,
      PDG -> {2,4,6},
      FullName -> {"UQuark", "CQuark", "TQuark"},
   
   (* Gluons *)
   V[1] == {
      ClassName -> G,
      SelfConjugate -> True,
      Indices -> {Index[Gluon]},
      Mass -> 0,
      PropagatorLabel -> {"G"},
      GaugeIndex -> Gluon,
      PropagatorType -> Sine,
      PDG -> 21,
      FullName -> "Gluon" }
}

Running FeynRules

Before loading FeynRules, the user should tell Mathematica where to look for the package. This is done via the command

SetDirectory[ <the address of the package> ];

$FeynRulesPath = <the address of the package>;

The FeynRules package is loaded via the command

<< FeynRules`

The user can now load the model-file. First, the working directory should be set to the address of the model-file

SetDirectory[<address of the model-file>];

The model-file is loaded via the command

LoadModel[ < file > ]

Notice that for FeynRules to run properly, the extension of the model-file should be =.fr=.

After the model-file is loaded, names for the anti-particle fields are generated automatically, e.g. if {{{ e }}} denotes the electron field, {{{ ebar }}} denotes the positron field. These symbols can also be obtained via the commands

HC[ e ]
anti[ e ]

The lagrangian can be entered using standard Mathematica language. Notice that FeynRules has some predefined commands,

• {{{

del[ psi, mu ] }}} denotes the derivative of the field {{{ psi }}} with respect to the space-time coordinate {{{ x^{mu }}}.}

• {{{

Ga[ mu ] }}} denotes the Dirac-matrix with index {{{ mu }}} ({{{ mu }}} may also be 5).

• {{{

ProjP }}} and {{{ ProjM }}} denote the projectors on right and left-handed fields.

• {{{

ProjP[ mu ] }}} and {{{ ProjM[ mu ] }}} are shorthands for {{{ Ga[ mu ].ProjP }}} and {{{ Ga[ mu ].ProjM }}}.

• {{{

HC[ V ] }}} denotes the hermitian conjugate of the tensor parameter {{{ V }}}.

• {{{

right[ psi ] }}} and {{{ left[ psi ] }}} denote the right and left-handed parts of the Dirac field {{{ psi }}}.

If there is no ambiguity, indices of scalar fields and fermion fields may be omitted when writing down the lagrangian. Instead, the Mathematica {{{ Dot }}} command (=.=) must then be used, e.g. the QCD interaction term for up-type quarks can be entered in two different ways,

-gs uqbar.Ga[mu].T[a].uq G[mu, a] == -gs Ga[mu, s, r] T[a, i, j]  uqbar[s, f, i].uq[r, f, j] G[mu, a]

Notice that the anticommutation of the fermion fields is taken into account by the dot-product on the right-hand side. Notice also that by writing the QCD interaction term for up-type quarks in this way, we implicitly used the class notation. We could have entered the same interaction term as

-gs uqbar.Ga[mu].T[a].uq G[mu, a] == -gs ubar.Ga[mu].T[a].u G[mu, a] 
                                                             -gs cbar.Ga[mu].T[a].c G[mu, a] 
                                                             -gs tbar.Ga[mu].T[a].t G[mu, a] 
                                                      == -gs Ga[mu, s, r] T[a, i, j] ubar[s, i].u[r, j] G[mu, a] 
                                                            -gs Ga[mu, s, r] T[a, i, j] cbar[s, i].c[r, j] G[mu, a] 
                                                            -gs Ga[mu, s, r] T[a, i, j] tbar[s, i].t[r, j] G[mu, a] 

Notice that in the last line, the fields {{{ u }}}, {{{ c }}} and {{{ t }}} do not carry the {{{ Generation }}} -index {{{ f }}}, because we have the identification

u[s, i] == uq[s, 1, i]
c[s, i] == uq[s, 2, i]
t[s, i] == uq[s, 3, i]

The QCD lagrangian (gluons + up-type quarks) reads %\[ \begin{cal}L\end{cal} = -\frac{1}{4}\,F_{\mu\nu}^a\,F_a{\mu\nu}+i\bar u_f\gamma^{\mu\partial_\mu u_f-g_s\bar u_f\gamma}\mu T^{a u_f G_\mu}a, \]% where $f$ denotes the flavor index of the up-type quark ($f=1,2,3$). In FeynRules language, this lagrangian reads

L = -1/4 FS[G, mu, nu, a] FS[G, mu, nu, a] +I uqbar . Ga[mu] . del[uq, mu] -gs uq . Ga[mu] . T[a] . uq G[mu, a]

The Feynman rules can be obtained via the command

FeynmanRules[ L ]

The {{{ FeynmanRules }}} command has several optional arguments,

• {{{

ScreenOutput }}} : If {{{ True }}}, then the output is written on the screen, otherwise it is not. The default value is {{{ True }}}.

• {{{

TeXOutput }}} : Writes the vertices obtained by {{{ FeynmanRules }}} into a TeX-file specified on the right-hand side of the argument (e.g. {{{ TeXOutput -> < file.tex > }}}).

• {{{

FlavorExpand }}} :

• Expands over the flavor indices specified by the list at the right-hand side of the argument, e.g. {{{

FeynmanRules[ L ] }}} will only generate a single quark-gluon vertex (uq uq G), whereas =FeynmanRules[ L, FlavorExpand -> Generation ] generates three quark-gluon vertices, one for each flavor (u u G, c c G, t t G).

• {{{

FlavorExpand -> True }}} expands over all flavor indices.

• {{{

Name }}} : A string chosen by the user. The analytic expressions of the vertices are stored in {{{ Vertices[ < Name > ] }}}.

For complicated lagrangians, it may sometimes be convenient to split the lagrangian into several small pieces, e.g.,

L = LGauge + LQuarks
LGauge = -1/4 FS[G, mu, nu, a] FS[G, mu, nu, a]
LQuarks = I uqbar . Ga[mu] . del[uq, mu] -gs uq . Ga[mu] . T[a] . uq G[mu, a]

The Feynman rules can be generated separately for each piece using the {{{ FeynmanRules }}} command. Giving each piece a name via the {{{ Name }}} option allows to combine the results later, e.g. a TeX-file containing both the vertices obtained from {{{ LGauge }}} and {{{ LQuarks }}},

FeynmanRules[ LGauge, Name -> "LG" ]
FeynmanRules[ LQuarks, Name -> "LQ" ]

WriteTeXOutput[ < file.tex >, {"LG", "LQ"}]

The FeynArts interface

The FeynArts model-file is then created via

WriteFeynArtsOutput[< file.mod>, {L1, L2, L3,...}]

where {{{ L1 }}}, {{{ L2 }}}, {{{ L3 }}}, ... denote the lagrangians which should be used to calculate Feynman rules from. This creates the FeynArts model-file {{{ file.mod }}} in the current working directory.

The MadGraph interface

The model file, together with the vertices calculated by the FeynmanRules function, contain all the information needed to run a generic MC generator, so it is sufficient to read out this information.

When the model file was loaded, the following (invisible) output was produced (See {{{ FirstExample.nb }}}):

• The list of all particles, with the corresponding properties. For each class member, this list contains the following information
  • a string, representing the name of the particle (e.g. u)
  • a string, representing the name of the corresponding antiparticle (e.g. u~)
  • the spin (scalar (S), fermion (F), vector(V))
  • the way the propagator should be drawn (straight (S), dashed(D), wavy (W), curly(C))
  • a string representing the mass (ZERO if the mass is 0)
  • a string representing the width (ZERO if the width is 0)
  • the colour structure (singlet (S), triplet, (T), octet (O))
  • a string, by which the propagator should be labelled in graphical representations (by default the same as the name of the particle)
  • the pdg code of the particle (generated automatically, if omitted)
  • a string, representing the full name of the particle (by default the same as the name of the particle)
• The list of all values for the masses and the decay rates.
• The list of all parameters entering the model (apart from masses).

For each parameter this list contains

• a string, representing the name of the variable.
• a tag (Ext/Int) indicating whether the parameter is external (i.e. given by a numerical value) or internal (i.e. given via a relation to other parameters)
• the value of the parameter (numerical for Ext, symbolical for Int)
• only for Ext: the name of the LH Block (assigned automatically if omitted)
• the interaction order (e.g. QCD 1)
• A tag indicating whether the parameter is a compex number (True) or not (False).

This information , together with the vertices, can be used to write for example the corresponding MadGraph files (saved in a subdirectory of the currentworking directory).

WriteMGOutput[L1, L2, L3,...]

where {{{ L1 }}}, {{{ L2 }}}, {{{ L3 }}}, ... denote the lagrangians which should be used to calculate Feynman rules from.

Notice that there is a compatibility problem of the current interface with Mathematica6.0. This will be fixed soon. The problem does however not occur for version 5.2.

The created MadGraph-files are

coupl_check.inc
coupl_definition.inc
coupl_write.inc
coupl.inc
ident_card.dat
input.inc
interactions.dat
param_card.dat
param_read.inc
param_write.inc
particles.dat