Configuration file format#

The `[Tools]` section#

`math`#

This is the path to the math / WolframKernel executable. Do not use wolframscript as it parses command-line arguments in a different order and therefore the code will fail. If you generate the configuration file using the autotherm-config command, AutoTherm will attempt to locate the executable.

`feynrules`#

This is the path to the top-level directory of the FeynRules install. Generally, this directory is named feynrules-current:

feynrules = (...)/feynrules-current/

`feynarts` and `formcalc`#

These are the paths to the top-level files of the FeynArts and FormCalc installs. Generally, they have the form:

feynarts = (...)/FeynArts-X.YY/FeynArts.m
formcalc = (...)/FormCalc-X.YY/FormCalc.m

The `[Model]` section#

`modelpath`#

Self-explanatory. This is the path to the .fr file defining the model.

`lagrangian`#

This is the symbol representing the total Lagrangian, i.e. including the dynamics of the thermal bath and its interactions with the produced particle. For example if you included the Standard Model file the Lagrangian should contain LSM which describes the Standard Model dynamics (in the symmetric phase), that is:

In the model file:

Ltot := LSM + ...;

In the configuration file:

lagrangian = Ltot

`produced`#

The “name” of the produced particle, as written in M$ClassesDescription. In the example of graviton production in the Standard Model, this key would be:

produced = T[1]

`inbath`#

This describes the contents of the thermal bath. There are three different ways to use this key:

Assuming Standard Model thermal bath

Leave empty:

inbath =

Adding/removing particles from the Standard Model thermal bath

To add a particle, give its name with a + at the end.
To remove a particle, give its name with a - at the end.

Attention

AutoTherm treats particles and anti-particles separately. Therefore one should be careful when adding/removing particles that are not self-conjugate.

For example, in the Majorana Dark matter model, one wants to add the colored scalar S[2] to the thermal bath. The thermal bath should be given in the following way:

inbath = S[2]+ -S[2]+

Defining the thermal bath

Give all elements of the thermal bath as a space-separated list. The same remark regarding anti-particles applies here.

Take for example the QGP photon production model:

inbath = V[2] F[1] -F[1]

`assumptions`#

This is a comma-separated list of assumptions (in the Wolfram language). This is useful because Mathematica assumes all symbolic variables are complex by default, which makes the resulting expressions more complicated than they need to be.

When includeSM is set to yes, all the required assumptions for the Standard Model parameters are already defined so only the assumptions for the “new” parameters are required.

Taking the example of graviton production, we would have:

assumptions = Element[kappa,Reals]

`replacements`#

Contains a comma-separated list of replacement rules (in the Wolfram language). The rules are applied at the very end of the computation of the matrix element squared. This might be useful e.g for writing complex combinations of parameters in a shorthand form and only expanding it in the final result.

This setting does not affect the thermal mass computation.

`includeSM`#

Takes a boolean value.

Whether to include the symmetric phase Standard Model file. If set to yes, the following particles will be defined: V[1] through V[3], F[1] through F[5] and S[1]. The following parameters will also be defined: g1, g2, g3, lam, yu and ht.

`noneq`#

The symbol for the coupling between the thermal bath and the produced particle. In the example of the graviton production model, we have:

noneq = kappa

`flavorexpand`#

List of fermions that have generation-dependent Yukawa couplings, for which the matrix element squared should be computed generation by generation (this setting does not affect the thermal mass computation). Give a comma-separated list of two-element lists containing the name of the fermion and the associated generation index. As before particles and anti-particles are treated separately, so both should be added to this list.

Let us take the example of the Majorana Dark Matter model. The produced Majorana fermion $\chi$ interacts only with $u_R$ (F[4]). Therefore flavorexpand should be set this way:

flavorexpand = {F[4],Generation}, {-F[4],Generation}

We refer to the same example page for instructions on how to handle the decomposed matrix element when trying to obtain numerical results for the rate.

The `[Run]` section#

`conf`#

Takes a boolean value.

Whether to generate the configuration files for the Mathematica part of AutoTherm. Setting it to yes is generally a good idea.

`rules`#

Takes a boolean value.

Whether to generate the Feynman rules of the model. Can be set to no if the rules have already been generated and the model file has not been changed.

`proc`#

Takes a boolean value.

Whether to compute the total matrix element squared and all relevant thermal masses.

`verbose`#

Takes a boolean value.

Whether to silence all messages from FeynArts and FormCalc.

`autothermdir`#

Path to the top-level directory of the AutoTherm install, that is the directory containing the pyproject.toml file.

More information on defining models#

Writing Lagrangian terms#

There are two precautions you should take when defining Lagrangian terms:

The definition of each Lagrangian term should be done using the SetDelayed operator (:=).
The indices present in the Lagrangian term should be localized using either the Block or Module function.

Let us take the example of the gauge term in the Standard Model Lagrangian. Its mathematical expression is:

\[\mathcal{L}_{\rm gauge}=-\frac{1}{4}F_{\mu\nu}F^{\mu\nu}-\frac{1}{4}W_{\mu\nu}^i W^{\mu\nu}_i-\frac{1}{4}G_{\mu\nu}^a G^{\mu\nu}_a\]

And the corresponding code for the model file reads:

LGauge := Block[{mu,nu,ii,aa},
    -1/4 FS[B,mu,nu] FS[B,mu,nu]
    -1/4 FS[Wi,mu,nu,ii] FS[Wi,mu,nu,ii]
    -1/4 FS[G,mu,nu,aa] FS[G,mu,nu,aa]
];

Note

AutoTherm will read the model file to check that each Lagrangian term is defined using the := operator, and throw a warning if it is not. For now it only checks terms whose name begins with L (e.g. LGauge).

Defining Yukawa couplings#

Yukawa couplings (vectors or matrices) are defined in two stages:

1. First, the variable that is used in the Lagrangian. Its ParameterType should be set to Internal. 2. Second, the variable containing the value of each element of the coupling vector/matrix. Its name should be the name of the internal parameter with the suffix ext. Its ParameterType should be set to External and Value should be a list of replacement rules for the elements.

For example, for the Majorana dark matter model we want to define the Yukawa vector $Y$:

\[\begin{split}Y=y\begin{pmatrix} c_1 \\ c_2 \\ c_3 \end{pmatrix},\end{split}\]

where we pulled out the $y$ factor to be able to use it as the noneq parameter later on. Note that the parameter type of y (the symbol for $y$) is Internal.

In the model file we define the internal symbol for the Yukawa vector, for use in the Lagrangian:

yyuk == {
    ParameterType -> Internal,
    Indices -> {Index[Generation]},
    Description -> "BSM yukawa"
},

With the Lagrangian term:

(*eta-uR-chi yukawa*)
LBSMyuk := Block[{sp,sp1,ii,jj,cc,ff1,ff2,ff3,yuk},
    yuk = ExpandIndices[
        - yyuk[ff1] chibar[sp].ProjP[sp,sp1].uR [sp1, ff1, cc] etabar[cc], FlavorExpand -> SU2D
    ];
    yuk+HC[yuk]
];

The definition of the external parameter is:

yyukext == {
    ParameterType -> External,
    Indices -> {Index[Generation]},
    Description -> "BSM yukawa explicit",
    Value -> {yyukext[1]->y c1 ,yyukext[2]->y c2 ,yyukext[3]->y c3}
}

Single-chirality fermions#

Fermions, defined as F[n], are treated by FeynArts as Dirac or Majorana fermions. When Weyl fermions are required (e.g. when considering particle production before the electro-weak crossover), the chirality projectors (defined as ProjP and ProjM by FeynRules) should be included explicitly.

For example in the Standard Model file, the $\ell_L$ part of the fermion kinetic term is:

\[\mathcal{L}_{\rm kin}\supset i\bar{\ell}_L\gamma^\mu D_\mu \ell_L\]

And it is implemented as:

LFermion := Block[{mu},
        I*(lLbar.Ga[mu].ProjM.DC[lL,mu]
        + ...)
];

Configuration file format#

The [Tools] section#

math#

feynrules#

feynarts and formcalc#

The [Model] section#

modelpath#

lagrangian#

produced#

inbath#

assumptions#

replacements#

includeSM#

noneq#

flavorexpand#

The [Run] section#

conf#

rules#

proc#

verbose#

autothermdir#

More information on defining models#

Writing Lagrangian terms#

Defining Yukawa couplings#

Single-chirality fermions#

This Page

The `[Tools]` section#

`math`#

`feynrules`#

`feynarts` and `formcalc`#

The `[Model]` section#

`modelpath`#

`lagrangian`#

`produced`#

`inbath`#

`assumptions`#

`replacements`#

`includeSM`#

`noneq`#

`flavorexpand`#

The `[Run]` section#

`conf`#

`rules`#

`proc`#

`verbose`#

`autothermdir`#