------------------------- 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``: .. code-block:: ini 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: .. code-block:: ini 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 :doc:`Standard Model file <./smfile>` the Lagrangian should contain ``LSM`` which describes the Standard Model dynamics (in the symmetric phase), that is: * In the model file: .. code-block:: Ltot := LSM + ...; * In the configuration file: .. code-block:: lagrangian = Ltot ``produced`` ------------ The "name" of the produced particle, as written in ``M$ClassesDescription``. In the example of :doc:`graviton production in the Standard Model <../examples/GWs>`, this key would be: .. code-block:: ini produced = T[1] ``inbath`` ---------- This describes the contents of the thermal bath. There are three different ways to use this key: 1. Assuming Standard Model thermal bath Leave empty: .. code-block:: ini inbath = 2. 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 :doc:`Majorana Dark matter model <../examples/chiDM>`, one wants to add the colored scalar ``S[2]`` to the thermal bath. The thermal bath should be given in the following way: .. code-block:: ini inbath = S[2]+ -S[2]+ 3. 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: .. code-block:: ini inbath = V[2] F[1] -F[1] ``assumptions`` --------------- .. From Chris' answer in https://stackoverflow.com/questions/10870719/inline-code-highlighting-in-restructuredtext .. role:: ini(code) :language: ini 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 :ini:`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 :doc:`graviton production <../examples/GWs>`, we would have: .. code-block:: ini 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 :ini:`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 :doc:`graviton production model <../examples/GWs>`, we have: .. code-block:: ini 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 :doc:`Majorana Dark Matter model <../examples/chiDM>`. The produced Majorana fermion :math:`\chi` interacts only with :math:`u_R` (``F[4]``). Therefore ``flavorexpand`` should be set this way: .. code-block:: ini 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 :ini:`yes` is generally a good idea. ``rules`` --------- Takes a boolean value. Whether to generate the Feynman rules of the model. Can be set to :ini:`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: 1. The definition of each Lagrangian term should be done using the ``SetDelayed`` operator (``:=``). 2. 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: .. math:: \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 :doc:`model file <./smfile>` reads: .. code-block:: wl 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 :doc:`Majorana dark matter model <../examples/chiDM>` we want to define the Yukawa vector :math:`Y`: .. math:: Y=y\begin{pmatrix} c_1 \\ c_2 \\ c_3 \end{pmatrix}, where we pulled out the :math:`y` factor to be able to use it as the ``noneq`` parameter later on. Note that the parameter type of ``y`` (the symbol for :math:`y`) is ``Internal``. In the model file we define the internal symbol for the Yukawa vector, for use in the Lagrangian: .. code-block:: wl yyuk == { ParameterType -> Internal, Indices -> {Index[Generation]}, Description -> "BSM yukawa" }, With the Lagrangian term: .. code-block:: wl (*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: .. code-block:: wl 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 :doc:`Standard Model file <./smfile>`, the :math:`\ell_L` part of the fermion kinetic term is: .. math:: \mathcal{L}_{\rm kin}\supset i\bar{\ell}_L\gamma^\mu D_\mu \ell_L And it is implemented as: .. code-block:: wl LFermion := Block[{mu}, I*(lLbar.Ga[mu].ProjM.DC[lL,mu] + ...) ];