UFO 2.0: the ‘Universal Feynman Output’ format

Abstract

We present an update of the Universal FeynRules Output model format, commonly known as the UFO format, that is used by several automated matrix-element generators and high-energy physics software. We detail different features that have been proposed as extensions of the initial format during the last ten years, and collect them in the current second version of the model format that we coin the Universal Feynman Output format. Following the initial philosophy of the UFO, they consist of flexible and modular additions to address particle decays, custom propagators, form factors, the renormalisation group running of parameters and masses, and higher-order quantum corrections.

1 Introduction

During the last 25–30 years, several high-energy physics software packages have been developed to explore the electroweak scale and get information on the possible physics beyond the Standard Model (BSM). Typical examples of such programs target the simulation of events at high-energy collider, fixed-target or neutrino experiments, total and differential cross section calculations for many processes in the Standard Model (SM) and beyond it, as well as the computation of dark matter observables. These software tools generally require as input, in one form or another, the particle spectrum of the model, the list and the values of all parameters that appear in its Lagrangian, as well as the list of all interaction vertices among the different particles. Historically, each program followed its own format to input the model information, with its own conventions and restrictions on the supported structures in a Lagrangian. This severely limited the portability of a model, and consequently multiplied the workload for the implementation and validation into several tools as advocated in [1].

The UFO format [2] was proposed as a solution to this issue, by introducing a new way to pass model information to high-energy physics software. Its goal is to provide a flexible and fully generic format that goes beyond existing formats in the sense that no assumption on the supported structures appearing in the model is enforced. All the model information is stored in an abstract form, i.e. independent of the software. It is then up to the tool using the UFO model to enforce their restrictions at run time. The UFO representation of the particle physics model has been chosen to rely on Python objects defined through a set of attributes that encode physical properties so that the model could be straightforwardly accessed and parsed by any high-energy physics tool. One of the advantages of the design choices made is that the UFO is modular. Additionally the format is easily expandable to include new pieces of information not originally considered. These design choices allowed later developments that permitted the inclusion of decay width information [3], modifications of the propagators associated with any given field [4], renormalisation group running effects impacting some of the model’s parameters and masses [5], and ingredients relevant to higher-order perturbative calculations in quantum field theories [6].

With the present paper, we take the opportunity to collect all these recent developments in a single document, describe (for the first time) how to embed form factors in UFO models, and how to include missing information relevant to the automated calculations of electroweak corrections in the Sudakov approximation for collider processes. In Sect. 2, we begin with a general description of the UFO format. We provide additional details on the philosophy of the UFO format, describe the structure of how the model information is organised in several Python files, and put a particular emphasis on (optional) recommendations useful for making UFO models traceable. Section 3 is dedicated to the original UFO format, and we describe all mandatory files that should be included in a UFO model. In Sect. 4, we detail how optional components can be added to a UFO model, and describe all existing options. Finally, Sect. 5 focuses on higher-order computations and how ingredients relevant to this context could be included in the UFO format, both in general and for the specific case of electroweak corrections in the Sudakov approximation. We summarise our work in Sect. 6.

2 The UFO format

2.1 The evolution of the UFO format

The aim of this section is to provide a general overview of the UFO 2.0 format for new physics models, that we propose to call the Universal Feynman Output (UFO) format in order to distinguish it from the initial version [2] released a decade ago. In the following, we emphasise the philosophy behind the UFO format, as well as its general structure. The content of the different files included in a UFO model and the associated syntax are discussed in more detail in dedicated subsequent sections.

A UFO model consists of a set of Python files that can be used with a large class of publicly available computer packages relevant for high-energy physics calculations. The UFO format has been built around the philosophy that a model implementation should be independent of the software tool that uses it. This makes it possible to have a single model implementation working across different computer codes and platforms, making it relevant for assessing the phenomenology relevant for different classes of experiments (targeting, for instance, dark matter, high-energy collider or neutrino experiments). The UFO standard achieves this by representing the model information, namely the model’s particles, parameters and vertices, in terms of Python objects whose attributes collect their properties. It is then up to the computer code that uses the model implementation to read in these files, and to process their content correctly. In case the code has restrictions on the type of models, an exception is raised and informs the user that the implementation cannot be reliably used.

The first version of the UFO format [2] was released a decade ago. It has changed the way particle physics models in general, and theories beyond the SM in particular, are implemented in high-energy physics software. Whilst the UFO format initially targeted specifically the implementation of particle physics models in matrix element and event generators dedicated to studies at the leading-order (LO) accuracy in perturbation theory, it is currently supported by a larger list of high-energy physics software tools. This list includes Achilles  [7, 8], Comix  [9], Contur  [10], GoSam   [11, 12], Herwig 7  [13, 14], MadAnalysis 5   [15, 16], MadDM   [17,18,19], MadGraph5_aMC@NLO   [20, 21], Recola 2   [22], Sherpa   [23, 24] and Whizard  [25,26,27].

Since its inception, the UFO format underwent several extensions to accommodate the specification of additional model information which is not part of its original documentation [2], such as those mentioned above. In particular, the documentation related to automated next-to-leading order (NLO) computations has never been collected in a single document, despite being at the heart of the frameworks introduced in [6, 20, 21]. UFO models suitable for NLO calculations have in addition become standard in high-energy phenomenology during the last decade, a large variety of NLO-compatible UFO models being now available (especially from the FeynRules model database¹). Although all extensions mentioned above are already being used by several codes, there is no official documentation of the structure of the UFO format beyond the original proposal. The main purpose of this document is therefore to provide an update of the UFO documentation, which contains all the features relevant for computations beyond LO accuracy.

Before starting to discuss the general outline of a UFO model implementation, let us first make a comment about the name. Originally, the acronym UFO stood for ‘Universal FeynRules Output’. The origin of this name can be traced back to the fact that in its original conception UFO files were produced by FeynRules[28] only. For a few years now, UFO files can also be generated from a user-defined Lagrangian by other computer codes such as LanHep[29, 30] and Sarah[31, 32]. For this reason we deem it more appropriate to remove the explicit reference to FeynRules from the name of the UFO format, and the acronym UFO henceforth now stands for ‘Universal Feynman Output’.

2.2 General file structure of the UFO

In the remainder of this paper we discuss in detail the structure of the files contained in a UFO model. All the files, collected in a single directory, must be valid Python files, therefore with a file extension .py. Whereas most files are model-specific and contain the definition of the objects relevant to each model (e.g. particles and parameters), some of the files are model-independent and contain Python-code objects defining, for instance, the Python classes used in a UFO model.

The following model-specific files are mandatory in any valid UFO model directory,

• particles.py

• parameters.py

• vertices.py

• lorentz.py

• couplings.py

• coupling_orders.py

• function_library.py

These files contain the basic definitions related to a model. If a model is to be used for computations beyond LO accuracy, three extra files are mandatory and must be included,

• CT_vertices.py

• CT_couplings.py

• CT_parameters.py

Moreover, in the specific case of electroweak corrections in the high-energy (Sudakov) approximation, this list must be complemented by an additional file that is described in this document for the first time,

• CT_ewcasimirs.py

Finally, every UFO directory may contain certain optional files, which specify additional model information,

• form_factors.py

• decays.py

• propagators.py

• running.py

The content of these files is described in detail in Sect. 4, so that we limit ourselves here to highlighting some features that are common to all of them.

Each file defines a list of objects. The classes that can be used are predefined and included in the mandatory file object_library.py (see below), and only standard Python syntax is allowed. Several of the files define analytic expressions for interaction vertices or coupling constants in the theory. All standard arithmetic operations in Python can be used to write such analytic expressions in the UFO format, augmented by some special symbols whose meaning is described in subsequent sections together with the precise syntax.

Besides these model-specific files which are at the heart of every UFO implementation, there are a couple of mandatory model-independent files that need to be included in every valid UFO directory,

• object_library.py

• _ _init_ _.py

together with the optional file

• write_param_card.py

that has a specific practical use.

As already mentioned, the file object_library.py contains the definition of all classes used in a UFO model. It includes several lists providing easy access to the full content of the model within the code. In other words, all declared objects within a UFO must appear in these lists. The list all_particles collects all particle declarations (as instances of the Particle class; see Sect. 3.1), and the list all_parameters gathers all parameter declarations (as instances of the Parameter class; see Sect. 3.2). The elements required for the description of the model interactions (see Sect. 3.3) are spread over the list all_vertices that collects all vertex declarations (as instances of the Vertex class; see Sect. 3.3), the list all_couplings that collects all coupling declarations (as instances of the Coupling class), the list all_lorentz that includes all Lorentz tensors appearing in the model vertices (declared as instances of the Lorentz class), and finally the additional list all_coupling_orders that contains a list of tags allowing certain vertices of the model to be flagged (these tags being declared as instances of the CouplingOrder class). In addition, the Python file object_library.py also includes a list all_functions whose role is to gather all Function objects instantiated in the model (see Sect. 3.4).

The content of the files function_library.py and write_param_card.py is detailed in Sects. 3 and 4. We only focus here on the file _ _init_ _.py. This file identifies the content of a UFO directory as a valid Python module that can be loaded with the standard command import, and it may contain any valid Python command that should be evaluated when the model is loaded. In particular, the file _ _init_ _.py imports all other Python files relevant to the model, and it additionally allows users to add general information about the model, as shown in the following example:

The first three variables (_ _author_ _, _ _date_ _ and _ _model_version_ _) provide information on the implementation and its author(s), whereas the _ _arxiv_ _ variable enables the connection of a given UFO model to a publication released on the arXiv. Setting the variable _ _UFO_version_ _ to “2.X” indicates that the model implementation includes features documented in the present paper, and the _ _python_version_ _ variable refers to the version of Python with which the UFO is compatible (namely 2 and/or 3 at present time). While such an electronic signature of the model is not mandatory, we recommend users to include it for traceability reasons. Depending on the moment at which a UFO model has been generated and that at which it is used within a code, incompatibilities between Python versions may occur. While we suggest to update existing UFO models so that they become Python 3 compatible, it is up to the code using UFOs to make sure that Python version compatibility is addressed properly and internally. For instance, GoSam, Herwig 7 and MadGraph5_aMC@NLO convert UFO models compatible with Python 2 to their Python 3 equivalent in order to use them.

Finally, users can include information on the gauges available for the model implementation. This is achieved through the variable gauge that contains a list of integers, as for instance in

The value 0 refers to the unitarity gauge, whereas the value 1 stands for the Feynman gauge. Other integer values are allowed, provided that they are consistently defined in the UFO model, in particular through appropriate definitions in the files parameters.py (for gauge parameters like $\xi$ in the $R_\xi$ gauge) and propagators.py (for custom propagator expressions).

3 Mandatory components

The dynamics of a particle physics model at tree-level is encoded in the UFO format within a small set of mandatory files. This contains the description of the particle spectrum (particles.py), the model parameters (parameters.py) and the different interactions between the model particles (whose implementation is spread over the three files vertices.py, couplings.py and lorentz.py). In addition, two extra files are necessary. The first of them, coupling_orders.py, details tags allowing certain vertices of the model to be flagged, whereas the last one, functions_library.py, is dedicated to the implementation of user-defined functions that can be used anywhere in the UFO model. The content of all these files is described in the following subsections.

3.1 Particles

All physical particles of a model are declared as instances of the class Particle in the file particles.py. UFO models are generally defined in terms of the physical, propagating, mass eigenstates. Unphysical gauge eigenstates and non-propagating auxiliary fields are thus ignored in most implementations, with the exception of optional ghost and Goldstone fields that may be needed depending on the gauge chosen. However, it is always possible to include specific auxiliary fields in an implementation if needed (see also the end of this subsection). A Particle object is defined through various attributes specifying the particle name and properties, including its quantum numbers. As an illustration, we consider a possible UFO implementation for a heavy top quark $t'$,

The particle is identified by its name (the name attribute taken to be tp in the present example), its spin and colour representations (given as the value of the spin and color attributes), its mass and width (the value of the mass and width attributes, given in GeV) and its electric charge (given as the value of the charge attribute, in units of the proton’s electric charge). The tp symbol that appears on the left-hand side of the equality represents a unique Python identifier that is further used internally within the model to refer to that particle. It has thus to follow Python requirements for names of variables. However, this identifier will not appear within any of the lists introduced in the file object_library.py, that include instead the objects themselves. All Particle objects instantiated within a UFO model must therefore have unique name attribute values, as this is how they should be referred to within any code using UFOs, in addition to unique Python identifiers. In addition, such a constraint holds for all the other classes of objects introduced below: two instances of a given class must have different name attributes².

In the UFO conventions, the spin representation has to be provided in the $2s+1$ form where s denotes the particle spin. Whereas any s values are allowed at the UFO level, none of the tools currently employing UFO models are compliant with spins $s>2$. Moreover, setting spin = -1 identifies ghost fields. Similarly, whereas users are free to assign any colour representation for a particle in a model, tools currently making use of UFO models support at most the trivial, (anti)fundamental, (anti)sextet and adjoint representations. These choices can be made by setting the color attribute to 1, $\pm 3$, $\pm 6$ and 8.

Information on the particle mass and width are provided by referring to the corresponding model parameters. In the considered example, the mass and width attributes of the tp particle are set to MTP and WTP, that are both declared in the file parameters.py (see Sect. 3.2). Parameter declarations must consequently be imported prior to the declaration of any particle, i.e. by inserting at the beginning of the file particles.py³

The UFO conventions allow users to associate a particle with its corresponding antiparticle. This is achieved through the antiname attribute of the Particle class, which must be set to the name of the Particle object representing the antiparticle. The latter is itself declared either as above (with some of the attribute values swapped or modified) or through the more economical method anti(),

This method of the Particle class is defined in the file object_library.py, and it automatically instantiates an antiparticle from the corresponding particle object. The TeX version of the particle and antiparticle names are respectively provided as the value of the texname and antitexname attributes. In the case of a self-conjugate particle, all antiparticle attributes must be set to the same value as their particle counterparts.

Most high-energy physics programs dealing with particles often internally identify them through their Particle Data Group (PDG) identifiers [33]. In the UFO format, such an identifier is stored as the value of the pdg_code attribute of the Particle class, that has been chosen to be 8 in the $t'$ example considered. While users can technically assign any code to any particle, many programs employing UFO models have the standard identifiers provided in the PDG review [33] hard-coded for common BSM particles. Inconsistent choices may therefore lead to unexpected behaviours of these tools. We recommend users to make use of existing identifiers for particles already listed in the PDG review, and new non-used identifiers otherwise.

While all the attributes described above are mandatory, additional optional attributes (like the attribute Lepton Number in the tp example considered) can be included. The UFO format includes the five predefined attributes line, goldstone, propagating, counterterm and propagator. The first three attributes indicate how to draw the particle propagator in a Feynman diagram (the possible self-explanatory values of the attribute line being ‘dashed’, ‘dotted’, ‘straight’, ‘wavy’, ‘curly’, ‘scurly’, ‘swavy’ and ‘double’), whether the particle is a Goldstone boson (‘true’) or not (default, ‘false’), and whether it consists of a physical field that propagates (‘true’, default) or of a non-propagating auxiliary field (‘false’). Information of the last two of these predefined optional attributes, counterterm and propagator, is provided in Sects. 5 and 4.3 respectively.

Finally, any extra attribute appearing in the instantiation of a Particle object (like U(1) quantum numbers such as LeptonNumber in the above example) represents a model-dependent quantum number whose sign changes under the action of the anti() method relevant for antiparticle objects.

3.2 Parameters

Model parameters (masses, couplings, mixing matrix elements, etc.) are declared as instances of the Parameter class in the file parameters.py. The UFO syntax distinguishes external and internal parameters. The former are the free parameters for which numerical values have to be provided by the user, while the latter are derived quantities related to other parameters (internal and/or external) via algebraic relations. Accordingly, a numerical value has to be provided for an external parameter whilst an analytical formula has to be given for an internal parameter. The UFO format also includes a third class of parameters, called constant parameters, that are similar to external parameters except that their value cannot be changed by the user. Equivalently, such constant parameters could also be declared as internal parameters for which the analytical expression is equal to a numerical value. Consequently, the only possibility to modify the value of a constant parameter is to edit directly the file parameters.py.

A typical declaration of an external parameter would be

In this example, we considered the parameter $\tan \beta$ that is defined as the ratio of the vacuum expectation values of the neutral Higgs fields in two-Higgs-doublet models, and that is often taken as one of the external parameters describing the Higgs sector of the model.

The above expression declares an instance of the Parameter class called tb (the value of the name attribute being tb). The nature of this parameter is external, as indicated by the value of the nature attribute (that has been set to external). In contrast, this attribute has to be fixed to internal or constant for internal and constant parameters respectively (see below for dedicated examples). In the above instantiation, the tb parameter is imposed to be real, since external parameters must all be real numbers. This is achieved through the attribute type whose value is set to real (the other possible option being complex). Consequently, the value of the value attribute is a floating-point number (10 in the above example). In addition, the TeX version of the parameter name must be specified, as for particle names (see Sect. 3.1), by setting accordingly the texname attribute. In principle users can choose the name of the parameters of a model freely, some parameter names are reserved as lying at the heart of higher-order calculations. We refer to Sect. 5 for more information.

The last two attributes in the above declaration, namely lhablock and lhacode, refer to the way in which external parameters are organised, following conventions generalising the Supersymmetry Les Houches Accord (SLHA) format [34, 35]. In this scheme, the numerical values of all the model parameters are collected into specific blocks, and each parameter is identified inside a block by one or more integer numbers called counters. These counters consist of a single integer for scalar parameters, and in a sequence of integers for tensor parameters, the integers corresponding to the tensor indices. Moreover, all the elements of a given tensor must be part of the same Les Houches block. In the case of the $\tan \beta$ declaration above, such a Les Houches structure would correspond to

In the UFO conventions, the name of the block (‘HMIX’) is passed as the value of the lhablock attribute, while the counter ([ 2 ]) is given as an array through the value of the lhacode attribute. In the SLHA-based format, the numerical value of the parameter (1.00e+01 here) is given after the counter, followed by an optional comment (referring in the above example to the parameter name).

Whereas the user can freely choose the names of the various Les Houches blocks and how the counters are organised, the SM parameters have to be correctly identified by any tool using a UFO model. For instance, if the SM input parameters include the inverse of the electromagnetic coupling constant at the Z-pole $\alpha ^{-1}(m_Z)$, the Fermi constant $G_F$ and the strong coupling constant at the Z-pole $\alpha _s(m_Z)$, then they have to be defined as the first three entries of the SMINPUTS block, the electromagnetic and strong coupling constants $\alpha$, e and $g_s$ being in this case internal quantities.⁴ In addition, masses and widths must be assigned to the blocks MASS and DECAY, the counter being the PDG code of the particle. We refer to the FeynRules manual [28] and the description of the SLHA format [34, 35] for more information on these conventions. Finally, UFO models suitable for higher-order calculations should include the blocks LOOP and TECHNICAL, that contain specific parameters relevant for programs handling calculations beyond LO. Their role is detailed in Sect. 5.

This SLHA-like structure associated with the organisation of the external parameters is irrelevant for internal and constant parameters, so that instantiation of the latter does not require users to provide values for the lhablock and lhacode attributes. Moreover, constant and internal parameters can be complex quantities, in contrast with external parameters. This is indicated by setting the type attribute to the value complex. In the case of internal parameters, the attribute value is fixed to a valid algebraic Python expression represented by a string. This formula can depend on any external, constant or internal parameter already declared in the file parameters.py (i.e. on any parameter appearing before in the file). For constant parameters, a numerical value has to be provided instead.

As an illustrative example, we show how to define the cosine of the $\beta$ angle. It can be derived from $\tan \beta$ (defined as an external parameter earlier), and can be declared in a UFO model as

after having properly imported the math module.

3.3 Interactions

The cornerstone of the UFO format consists of the way in which interactions are implemented, following their decomposition in a colour $\otimes$ spin space. Any generic vertex ${{\mathcal {V}}}$ involving the interaction of n external particles $\varphi _i^{\ell _i a_i}(p_i)$ ($i=1, \ldots , n$) with spin indices $\ell _i$ (equivalently denoting Dirac and Lorentz indices), colour indices $a_i$ and four-momenta $p_i$, could be decomposed as

$$\begin{aligned} \begin{aligned}&{{\mathcal {V}}}^{a_1\ldots a_n, \ell _1\ldots \ell _n}(p_1,\ldots ,p_n) \\&\quad = \sum _{i,j}C_i^{a_1\ldots a_n} \ G_{ij}\times L_j^{\ell _1\ldots \ell _n}(p_1,\ldots ,p_n) . \end{aligned} \end{aligned}$$

(1)

In this expression, the vertex ${{\mathcal {V}}}$ is decomposed into a set of colour structures $C_i^{a_1\ldots a_n}$ and spin structures $L_j^{\ell _1\ldots \ell _n}(p_1,\ldots ,p_n)$, that are given as tensors in colour and spin space respectively. After considering all the model interactions, the resulting ensemble of structures defines a colour and spin basis allowing for the decomposition of any of the model vertices. Equation (1) hence underlines an economical way to define all the interactions of the model, since a given spin or colour tensor could be used in several vertices. The set of coordinates associated with a specific vertex in the colour $\otimes$ spin basis are given by the coupling strengths $G_{ij}$. In version 2.0, the UFO format only supports unbroken gauge groups that comprise a single copy of SU(3) and any number of U(1) factors, such as in the SM after electroweak symmetry breaking.

As an example, we consider the four-scalar interaction between right-handed up squarks and antisquarks of the Minimal Supersymmetric Standard Model, whose associated Feynman rule is given by:

where $c_1$ and $c_2$ (${\bar{c}}_3$ and ${\bar{c}}_4$) denote the fundamental (anti-fundamental) colour indices of the two squarks (antisquarks), a is a summed adjoint colour index, and $c_W$ is the cosine of the electroweak mixing angle. Moreover, $T^a$ stands for the SU(3) generators in the fundamental representation, and $g_s$ and e are the strong and electromagnetic coupling constant respectively. The UFO decomposition of this vertex can be written as

(2)

The colour basis ${{\mathcal {C}}} = \Big (C_i^{c_1c_2{\bar{c}}_3 \bar{c}_4}\Big )$ contains four elements,

(3)

whereas the spin basis ${{\mathcal {L}}}$ contains a single element

$$\begin{aligned} {{\mathcal {L}}} = \big (1 \big ). \end{aligned}$$

(4)

Here the coordinates ${{\mathcal {G}}}= \big (G_{ij}\big )$ are given as a $4\times 1$ matrix of coupling strengths:

$$\begin{aligned} {{\mathcal {G}}} = \bigg ( -\frac{4 i e^2}{9 c_W^2},\quad -\frac{4 i e^2}{9 c_W^2},\quad -ig_s^2,\quad -ig_s^2 \bigg )^t. \end{aligned}$$

(5)

The UFO format mimics this structure with the declaration of the model vertices as instances of the Vertex class in the file vertices.py. Each vertex is implemented following its decomposition (1), that is passed through five mandatory attributes (name, particles, color, lorentz and couplings). In the case of the four-squark vertex example considered, a possible instantiation is:

The first attribute name defines the name given to the vertex (V_1 in our example). The list of particles outgoing from the vertex is provided as an array of Particle objects through the particles attribute of the Vertex class. All employed particles must have been declared in the file particles.py, and then imported in the file vertices.py prior to the declaration of any vertex as

The four-squark example considered involves two incoming right-handed up squark (suR) and two incoming right-handed up antisquarks (suR_ _tilde_ _), the Particle objects suR and suR_ _tilde_ _ being declared in particles.py (as detailed in Sect. 3.1). The vertex decomposition (1) is finally provided through the color, lorentz and couplings attributes of the Vertex class.

Table 1 Elementary colour tensors that can be used to construct the elements of the colour basis relevant for a given UFO vertex. Fundamental, sextet, antifundamental and antisextet colour indices are denoted as i, $\alpha$, ${\bar{\imath }}$ and ${\bar{\alpha }}$, whilst a denotes an adjoint colour index

The color attribute refers to the array of elements $C_i^{a_1\ldots a_n}$ of the colour basis relevant to the vertex under consideration. Each entry in this array is a polynomial combination of the elementary colour tensors of Table 1, and the arguments of each tensor are positive or negative integer numbers. Positive integers are used to associate a colour index with one of the particles incoming to the vertex, the exact value referring to the position of the particle in the list provided through the attribute particles of the Vertex class. Negative integers must appear exactly twice in a monomial, and they correspond to contracted (i.e. summed over) indices. In the UFO conventions, the position of the first particle in the list particles corresponds to 1, in contrast to standard Python arrays. Moreover, it is up to users to verify the consistency between the colour structures appearing in a vertex definition and the representations of the particles entering this vertex, as programs processing UFO models may reject models in which the colour structures in a vertex do not match the colour representations of the particles.

Equation (2) shows that all the colour structures appearing in the four-squark vertex can be implemented by the sole use of Kronecker deltas (Identity) and fundamental representation matrices of SU(3) (T). Consequently, the elements of the basis of (3) are implemented as

$$\begin{aligned}{} & {} \delta ^{{\bar{c}}_4}{}_{c_1}\delta ^{{\bar{c}}_3}{}_{c_2} \leadsto {\texttt {'Identity(4,1)*Identity(3,2)'}}\\{} & {} \delta ^{{\bar{c}}_3}{}_{c_1}\delta ^{{\bar{c}}_4}{}_{c_2} \leadsto {\texttt {'Identity(3,1)*Identity(4,2)'}}\\{} & {} (T^a)^{{\bar{c}}_3}{}_{c_2} (T^a)^{{\bar{c}}_4}{}_{c_1} \leadsto {\texttt {'T(-1,2,3)*T(-1,1,4)'}}\\{} & {} (T^a)^{{\bar{c}}_3}{}_{c_1} (T^a)^{{\bar{c}}_4}{}_{c_2} \leadsto {\texttt {'T(-1,1,3)*T(-1,2,4)'}} \end{aligned}$$

as illustrated in the declaration of the vertex V_1 above.

Table 2 Elementary spin tensors that can be used to construct the elements of the spin basis relevant to a given UFO vertex. Spin and Lorentz indices are respectively denoted as s and $\mu$

Similarly, all spin structures $L_j^{\ell _1\ldots \ell _n}(p_1,\ldots ,p_n)$ relevant to a given vertex are collected into an array that is passed through the lorentz attribute of the Vertex class. The structures $L_j^{\ell _1\ldots \ell _n}$ are provided as Lorentz objects, instead of being directly implemented at the time of the vertex instantiation. These Lorentz objects are then defined in the file lorentz.py, and they must therefore be imported prior to the declaration of any vertex in the file vertices.py file,

A Lorentz object is instantiated (in the file lorentz.py) as in the following two examples (the first one being the only one relevant for the considered four-squark interaction vertex),

All three attributes of each Lorentz object are mandatory. The first of them (name) indicates the name of the object, the second (spins) the spins (in the $2s+1$ notation) of the particles entering the vertex and the last one (structure) the structure itself, provided as a polynomial combination of the elementary tensors of Table 2. As in the colour case, the arguments of these tensors are positive and negative integers, the positive ones being associated with the particles incoming to the vertex (with the value referring to the position of the particle in the list spins), and the negative ones appearing twice and corresponding to contracted indices (that are therefore summed over). In this context, squared momenta like $p_1^2$ can be written as P(-1,1)**2. This is interpreted exactly as P(-1,1)*P(-1,1) and allows for concise expressions of Lorentz structures in UFO. Obviously, the -1 index must appear only once in this case.

In the case of the four-scalar vertex (2), the only possible spin combination is the trivial one. This requires us to use the SSSS1 object for the instantiation of the vertex V_1. In contrast, the object VVSS1 involves two vector bosons and two scalar particles (cf. the attribute spins of the object VVSS1), and the structure of its interactions relates the two bosons through the Minkowski metric (cf. the attribute structure of the object VVSS1). The corresponding UFO implementations for the structure of the Lorentz objects SSSS1 and VVSS1 are then

$$\begin{aligned} 1&\leadsto&{\texttt {'1'}}\\ \eta ^{\mu _1\mu _2}&\leadsto&{\texttt {'Metric(1,2)'}} \end{aligned}$$

The last attribute of the Vertex class is related to the coordinates $G_{ij}$ of the vertex in the colour $\otimes$ spin basis. They are provided in the form of a Python dictionary through the couplings attribute of the Vertex class. This dictionary relates the coordinate (i, j), where i and j refer to a specific colour and spin basis element respectively, to the value of the corresponding coupling strength given as a Coupling object. The list of all Coupling objects necessary for the implementation of a given model is declared in the file couplings.py, that must therefore be imported prior to the declaration of any vertex,

When a vertex is instantiated, only the non-vanishing coordinates have to be included. In the four-squark vertex considered, this therefore gives

$$\begin{aligned} (0, 0) \leadsto {\texttt {C.GC\_1}}&\qquad \qquad&(1, 0) \leadsto {\texttt {C.GC\_1}}\\ (2, 0) \leadsto {\texttt {C.GC\_2}}&\qquad \qquad&(3, 0) \leadsto {\texttt {C.GC\_2}} \end{aligned}$$

where the integer counters follow this time a standard Python numbering for the elements of an array (the first element being thus associated with the index 0). The example above illustrates the fact that the four-squark vertex exemplified involves only two instances of the Coupling class (GC_1 and GC_2), as also depicted in (2).

The declaration of a Coupling object in the file couplings.py is very similar to that of an internal parameter declaration (see Sect. 3.2). For the two couplings GC_1 and GC_2 necessary for the four-squark vertex considered, this gives

An instance of a Coupling object is declared with three mandatory arguments, namely its name (name), the algebraic coupling definition that could depend on any of the model parameters (value), and a so-called coupling order provided in the form of a Python dictionary (order). In the case of the four-squark example considered, the coupling strengths appearing in (5) are directly provided as valid Python algebraic expressions. The last attribute of a Coupling object, order, is a Python dictionary that allows users to tag certain couplings of the model with one or more strings (i.e. tags) to which a positive integer number is associated. In the examples above, the tags QED and QCD are associated with two physical quantities, the typical strength of the electroweak and strong interactions. The couplings GC_1 and GC_2 are hence flagged as couplings with strengths proportional to two powers of the electromagnetic and strong coupling, respectively, as the integer 2 is attached with each of the two tags involved. It is not mandatory to use tags that actually refer to a physical interaction. For instance, in the vector-like quark UFO implementation of [36], a VLQ coupling order is introduced in order to identify all vertices suppressed by the mixing of a vector-like and a SM quark (which is achieved by setting order = ’VLQ:1’ in the relevant coupling declarations).

This coupling-order feature allows users to filter not only vertices, but also the resulting Feynman diagrams. This is generally achieved in practice through the introduction of criteria depending on the type of interactions involved in a vertex or a Feynman diagram. For instance, the QED and QCD tags introduced in the definition of the GC_1 and GC_2 couplings could allow users to neglect (subdominant) electroweak diagrams relative to (dominant) QCD diagrams (as numerically $\alpha _s^2 \sim \alpha$) when deriving the list of diagrams relevant to a specific hadron-collider process. Moreover, in the vector-like quark example briefly mentioned above, users could enforce the list of relevant diagrams to include at most one mixing suppression.

The tags that can be used for the instantiation of the different Coupling objects have to be declared in the file coupling_orders.py, each tag (or coupling order) being implemented as an instance of the class CouplingOrder. In our supersymmetric example (taken from [37]), the model contains two independent classes of interactions that are named QED (for interactions proportional to the electromagnetic coupling e, and therefore the weak coupling $g=e/s_W$ with $s_W$ being the sine of the electroweak mixing angle, or any of the model’s Yukawa or supersymmetry-breaking multiscalar interactions) and QCD (for QCD interactions). These tags are declared as

Whereas the examples above refer to coupling orders associated with physical interactions, they can easily be generalised to any other class of tags.

In the above example, the two CouplingOrder objects are instantiated by fixing three mandatory attributes (name, expansion_order and hierarchy), together with one optional attribute for the QCD coupling order (perturba tive_expansion). The first of the mandatory arguments, name, contains the name of the coupling order, that also consists of the tag that can be used for instantiation of Coupling objects. The second attribute, expansion_order, refers to the maximum power of the interaction that could appear in a single amplitude. This is particularly relevant for effective field theories in which amplitudes must be truncated to some power of the high effective scale. In the above examples, this attribute is fixed twice to 99, which effectively indicates that there is no limit. The last mandatory attribute, hierarchy, allows users to order the couplings according to their relative magnitude. In the above example, we enforce such a hierarchy, and we impose $\alpha _s^2 \sim \alpha$. This is achieved by assigning to the coupling orders QCD and QED the hierarchies 1 and 2 respectively. Such a piece of information is relevant for the implementation of diagram filters for a given process,⁵ allowing users to select given contributions to an amplitude according to the type of contributing interactions. Setting the attribute hierarchy to 0 indicates that the corresponding coupling order plays only a role of a tag, and that there is no connection to the relative magnitude of the associated coupling orders. In the vector-like quark model introduced above, the attribute hierarchy of the coupling order VLQ is set to 0. This coupling order can hence be used to enforce the maximum number of suppression factors due to VLQ-SM mixing that can appear in a diagram, regardless of the nature of the fundamental (QED or QCD) interactions involved.

Finally, the perturbative_expansion attribute of the QCD coupling order is set to 1 in the above example. This implies that the UFO model contains all ingredients necessary for NLO calculations in QCD (see Sect. 5). If the attribute is unspecified, a default value of perturbative_ expansion = 0 is assumed, which implies that only LO calculations in this coupling are supported.

3.4 The function library

The last mandatory component of a UFO model is the file function_library.py. It includes user-defined functions declared as instances of the Function class. The UFO format supports functions that can be defined within a single line in Python, the so-called Python lambda functions. Python lambda functions offer the advantage of being easily translatable into other programming languages, and they are consequently the only functions that can be declared within the library defined in the file function_library.py.

A Function object is defined through three mandatory attributes and two optional attributes. The mandatory attributes consist of the name of the function (name), its arguments specified as a tuple of strings (arguments), and the expression of the function itself given in terms of its arguments. The latter must be provided as a string that represents a valid Python expression, and it is given as the value of the attribute expression. By default, all the arguments of the functions are considered to be complex numbers. This behaviour can however be superseded by providing a tuple of strings through the optional attribute argstype of the Function class, which allows users to specify the type of the different arguments of the function. The supported types are real numbers (real), complex numbers (complex), and arrays of real or complex numbers (real[n] or complex[n] for an n-dimensional array, respectively, where n is an integer). The two tuples provided through the attributes arguments and argstype must have the same size. Similarly, the type of the result of the function is a complex number by default, but this behaviour can be modified by specifying the type attribute of the instantiated function, that can take the self-explanatory values real, complex, real[n] and complex[n] (with n being an integer).

Several functions are shipped by default with any UFO model. This includes in particular a series of mathematical functions for which the Python module cmath is insufficient. First, the function_library.py file contains a set of tools that facilitate the treatment of complex quantities (the real part of a complex number re, its imaginary part im, and the complex conjugation operation complexconjugate). Second, several trigonometric and cyclometric functions are implemented (the cotangent cot, the secant sec and the cosecant csc functions, together with their arcsecant asec and arccosecant acsc counterparts).

As an illustration, we provide below a function returning the real part of a complex number, as well as a function associated with the secant of a complex number. These could implemented as

Furthermore, the file function_library.py of a UFO model includes a generalised version of the Heaviside step function theta_function. It allows users to make use of a variety of piecewise functions involving a single condition, and it is implemented as a Function object relying on the one-line Python if/else statement,

With this generalised function, the familiar one-parameter Heaviside function centred on $x_0=23$,

$$\begin{aligned} \varTheta (x-23) = \left\{ \begin{array}{l} 1 \qquad \text {if }x\ge 23.\\ 0 \qquad \text {otherwise}\end{array}\right. , \end{aligned}$$

(6)

can be used through

The definition of Function objects also supports the use of the model parameters instantiated from parameters.py, as well as that of other functions. This therefore allows for more complex expressions to be defined in steps. As a complete example, we consider an elastic atomic form factor $G_{\textrm{el}}(t)$ [38],

$$\begin{aligned} G_{\textrm{el}}(t) = \left( \frac{Z_{\mathrm{nuc.}}}{1+ t/d_{\mathrm{nuc.}}} \frac{a^2_{\mathrm{nuc.}} t}{1 + a_{\mathrm{nuc.}}^2 t} \right) ^2, \end{aligned}$$

(7)

which depends on the three nuclear physics parameters $Z_\mathrm{nuc.}$, $a_{\mathrm{nuc.}}$ and $d_{\mathrm{nuc.}}$. Its implementation as a Function object Gel reads

where Z_nuc, a_nuc and d_nuc are parameters of the model defined in the file parameters.py. In this function, we imposed the arguments to be real quantities (real), instead of complex ones (complex, that is also the default) or real and complex arrays (for example real[4] or complex[4] for the four-dimensional case). Moreover, the output of the function is defined to be a real number, instead of a complex one, which is the default. We note that this output is not allowed to be a list.

The complete form factor in our example should also include an inelastic part $G_\textrm{in}(t)$ [38, 39]. The latter can be defined similarly as its elastic counterpart, namely as another Function object Gin. The full implementation of both contributions as a single Function object FF is thus

in which we illustrate how a given Function object could call other Function objects and standard Python methods.

4 Optional components

In this section, we describe optional files that can be included in a UFO model. These files allow users to provide additional information about a model, and/or equip a UFO with non-standard practical methods and functions. One of these files (write_param_card.py) defines a writer of the external model parameters in an SLHA-like text file. This file was a mandatory component in the first version of the UFO format [2] for the sole reason that all files defining a model were mandatory. As it is not strictly necessary from the point of view of the information defining a model, we benefit from the possibility of having optional files in version 2 of the UFO to update its nature. The other optional files are new and were introduced after the original release of the UFO format. They are related to the addition of custom propagators for specific particles of the model as introduced in [4] (in the file propagators.py), detail how to provide information about particle decay widths following [3] (in the file decays.py) and about the renormalisation group running of the model’s parameters as defined in [5] (in the file running.py), and enable the usage of form factors in a UFO model, which we document below for the first time. Moreover, it is now also possible to directly add custom Fortran and C++ functions in a UFO model. These functions are defined in folders Fortran and Cpp respectively, and they can be called in any algebraic expression introduced in the other files of the model. This possibility is briefly discussed in Sects. 4.2 and 5.2.

4.1 Outputting the values of the model parameters

The file write_param_card.py includes routines that write all external model parameters, together with their numerical value, into a text file following an SLHA-like format [34, 35]. In the output file, the parameters and their values are organised in Les Houches blocks and counters, as specified by the user with the parameter declarations implemented in the file parameters.py (cf. the lhablock and lhacode attributes of the different parameters; see Sect. 3.2).

The output file, named param_card.dat, is generated by issuing in a shell the command

In addition to the model external parameters and their value, the output file includes QNUMBERS blocks [40] with information on the quantum numbers of all the particles of the model, as well as all particle masses and decay widths regardless of their external/internal nature. Examples of such a write_param_card.py file can be obtained from the model database of FeynRules.⁶

4.2 Form factors

The standard UFO decomposition of an interaction vertex in a colour $\otimes$ spin space of (1) does not always suffice to properly describe an interaction. In some models, it is indeed convenient to have couplings that depend on phase space (therefore including so-called form factors), as for instance in effective theories or empirical descriptions of interactions (e.g. as for atomic form factors at low energy or for neutrino-nucleus interactions). The extension of the UFO format described in this section adopts the decomposition (1) by adding extra scalar functions ${\mathcal {F}}_{j}\,(p_1,\ldots ,p_n)$ that depend on the four-momenta of the particles incoming to the vertex,

$$\begin{aligned} \begin{aligned} {{\mathcal {V}}}^{a_1\ldots a_n, \ell _1\ldots \ell _n}&= \sum _{i,j}C_i^{a_1\ldots a_n} \ G_{ij}\\&\quad \times {\mathcal {F}}_{j}\,(p_1,\ldots ,p_n)\ L_j^{\ell _1\ldots \ell _n}(p_1,\ldots ,p_n) \ . \end{aligned}\end{aligned}$$

(8)

This expression shows that in the UFO conventions, the form factors ${\mathcal {F}}_{j}$ impact the spin dependence of the interaction vertices, while they leave the colour structure unaffected.

In practice, they are implemented as a modification of the relevant spin structure of the vertices declared in the file lorentz.py, following the replacement

$$\begin{aligned}{} & {} L_j^{\ell _1\ldots \ell _n}(p_1,\ldots ,p_n) \nonumber \\ {}{} & {} \quad \rightarrow \mathcal {F}_{j}\,(p_1,\ldots ,p_n)\ L_j^{\ell _1\ldots \ell _n}(p_1,\ldots ,p_n). \end{aligned}$$

(9)

This amounts to allow the value of the structure attribute of a Lorentz object to make use of functions defined in the file function_library.py (see Sect. 3.4), and of parameters defined in the file parameters.py (see Sect. 3.2). This obviously requires to import the list of parameters and the set of relevant functions in the preamble of the file lorentz.py.

As an example, we consider the case of a form factor given by $m_W/E$, where $m_W$ stands for the mass of the W boson (represented below by the Parameter object MW) and E is the energy scale relevant for the associated process. Such a form factor could be defined in the file function_library.py through a Function object AAA,

This form factor can then be used in the declaration of a spin structure relevant, for instance, for a vertex involving two vector bosons (of momenta $p_1$ and $p_2$ and associated Lorentz indices $\mu _1$ and $\mu _2$), and one scalar state (of momentum $p_3$),

$$\begin{aligned} \mathcal {F}\,(p_1,p_2,p_3)\ L^{\mu _1\mu _2}(p_1,p_2,p_3) = \frac{m_W\ \ \eta ^{\mu _1\mu _2} }{\sqrt{(p_1+p_2)^2}} . \end{aligned}$$

(10)

In this expression, the energy scale E appearing in the form factor is identified by $E^2 \equiv (p_1+p_2)^2$. This could be implemented as a Lorentz object VVS1 as

following the notation introduced in Table 2. In particular, we recall that negative indices are summed over, and that squares of four-vectors are allowed.

For more complicated form factor expressions, users have the possibility to nest the definition of several functions, as shown in the example given in Sect. 3.4 or in [41, 42]. For extreme cases, form factors can be provided externally, through Fortran or C++ functions as in the tau-lepton decay module of [43]. Such a construction should however be avoided as much as possible as it breaks the spirit of portability of UFO models. It may however be sometimes the only choice. In this case, we encourage authors to provide both Fortran and C++ routines for their form factors, and implement them in the Fortran file Fortran/functions.f (or Fortran/functions.f90) and C++ header and source files Cpp/functions.h and Cpp/functions.cpp respectively.

4.3 Particle propagators

In general, the propagator of a particle can be inferred from its spin, and so it is usually redundant to define propagators explicitly for each particle. There may be cases, however, where it is useful to have the possibility to redefine the propagator of a certain class of particles. This includes, for example, theories with non-standard kinetic terms, implementations featuring non-propagating auxiliary particles (in which case the propagator is simply a product of Kronecker delta functions without any momentum dependence), and models relevant for particles with a spin value $s\ge 3/2$ for which the conventions are not unique.

For a few years already, the UFO format has allowed the user to define new propagators as instances of the class Propagator, and in a given model implementation all these custom propagator definitions must be collected in the optional file propagators.py [4]. The instantiation of a Propagator object follows similar conventions as for any other UFO object, as exemplified below with the case of a massless gauge boson propagator in the Feynman gauge (instantiated as V0),

This declaration includes the two mandatory attributes of the Propagator class (name and numerator), as well as the only possible optional attribute (denominator). The attribute name provides a way to identify a given propagator object, whereas the attribute numerator includes an analytical expression for the numerator of the propagator, a global factor i excluded. The optional attribute denominator then allows users to provide an analytical expression of the denominator. If unspecified, the Feynman propagator denominator $(p^2-m^2+im\varGamma )$ is assumed for a particle of mass m, width $\varGamma$ and four-momentum $p_\mu$.

Table 3 Lorentz objects that can be used for the definition of the numerator and denominator of custom particle propagators

The analytical expressions to be provided for the propagator numerators and denominators rely on the UFO conventions detailed in Sect. 3.3 (and in Table 2 in particular), as well as on several additional quantities that are introduced in Table 3. For non-scalar propagators, the numerator involves non-contracted (spin and/or Lorentz) indices that are referred to as ‘1’ and ‘2’ in the implementation. These respectively correspond to the incoming and outgoing directions. For non-fermionic propagators, these directions are arbitrary, whereas for fermionic propagators they are crucial and must be defined from the ‘fermion flow’ associated with the corresponding diagrams [44]. In the case of a spin-2 particle, the ‘51’ and ‘52’ indices are additionally introduced for the second pair of Lorentz indices attached to the propagating state.

As shown in the example above and in Table 3, the flag id is used as the unique identifier for the propagating particle. For instance, the momentum of the propagating particle can be represented by P(1,id) and P(2,id) in the incoming and outgoing cases respectively, whereas for a fermionic propagator (of momentum p), PSlash(1,2,id) would refer to the quantity in spin space. Moreover, the mass and width of the propagating particle are identified as Mass(id) and Width(id) respectively, and the additional quantity OverMass2(id) corresponds to $1/M^2$ for a massive particle and 0 otherwise. Finally, we emphasise that as for Lorentz structure definitions, repeated negative indices are summed over.

In order to link custom propagators to particles, the Particle class is equipped with an optional attribute propagator. It allows users to refer to the specific propagator to employ through its name as defined in the file propagators.py. For example, a massless spin-1 particle with a custom propagator as given in the above example could be defined by

where the preamble of the file particles.py is assumed to include the instruction

In the case a Particle object is instantiated without any value for the attribute propagator (as in most existing UFO models), default propagators are assumed. As non trivial and existing examples, we refer to [4] and [45]. They respectively address models featuring particles with spin $s\ge 3/2$, and models in which running width effects are incorporated in the particle propagators.

Finally, some models are such that it is impossible to simultaneously diagonalise both the mass and width matrices. In this case, ‘matrix’ propagators are in order [46]. We mention as a side note that the UFO format is compliant with such a structure through the implementation of a set of two-point vertices that emulate each off-diagonal entry of the propagator matrix.

4.4 Particle decays

Many applications of calculations involving massive unstable particles require the evaluation of the total and partial decay widths of all particles of the model, together with the estimation of the decay channels that are kinematically allowed. This task is highly dependent on the mass spectrum of the model, and it requires a re-evaluation of the widths for each choice of external parameters. In order to provide a simple solution to this problem, the UFO format allows users to input analytical formulas for LO two-body decay rates associated with the particles of the model. These are all collected inside the file decays.py [3]. As two-body decays might sometimes be insufficient (when for instance higher-multiplicity decays are the dominant decay modes or when higher-order corrections are important), it is up to the code using the UFO model to decide how (and if) they should include such extra contributions in their computations.

In the special case of a two-body decay of a particle of mass M to two particles of masses $m_1$ and $m_2$, Lorentz invariance implies that the matrix element relevant for the calculation of a partial width $\varGamma$ can only depend on the masses of the external particles, and we can write

$$\begin{aligned} \varGamma = \frac{\sqrt{\lambda (M^2,m_1^2,m_2^2)}\,}{16\,\pi \,S\,|M|^3}\ |\mathcal {M}|^2 , \end{aligned}$$

(11)

where S denotes the phase-space symmetry factor, the function $\lambda (M^2,m_1^2,m_2^2)= (M^2-m_1^2-m_2^2)^2-4m_1^2m_2^2$ is the usual Källén function, and $|\mathcal {M}|^2$ stands for the average squared matrix element associated with the decay mode considered. The matrix element of this two-body decay only receives contributions from a single three-point vertex $\mathcal {V}$, so that it can be written as

$$\begin{aligned} |\mathcal {M}|^2 = \mathcal {V}_{\mu _1\mu _2\mu _3}^{a_1a_2a_3}\,\mathcal {P}^{\mu _1\mu '_1}_1 \mathcal {P}^{\mu _2\mu '_2}_2\,\mathcal {P}^{\mu _3\mu '_3}_3\,(\mathcal {V}^*)_{\mu '_1\mu '_2\mu '_3}^{a_1a_2a_3}, \end{aligned}$$

(12)

where the colour and spin indices of the particle i are generically denoted by $a_i$ and $\mu _i^{(')}$ respectively. In addition, we have introduced the polarisation tensor of the particle i, $\mathcal {P}_i$, that depends on its spin and its mass.

The content of the file decays.py contains declarations of instances of the class Decay. Each instance of this class can be thought of as a collection of LO analytic formulas of two-body partial widths of a given state (obtained from (11) and (12)). For example, the two-body partial widths of the Higgs boson in the Standard Model could be represented as

where $\varGamma _{XY}$ schematically represent the analytic formula of the partial width of the Higgs boson associated with the decay mode $H\rightarrow XY$. The syntax to be used to write these analytic formulas is identical to that introduced in the previous sections. In the above example we assume that the first two generations of fermions are massless. All possible LO two-body decays have been included, even if some of them are kinematically forbidden. The analytic formula for the two-body decays of a Higgs boson into a pair of top quarks or weak bosons are hence also present (even if not kinematically allowed for a light Higgs boson). It is then up to the high-energy physics tool to filter out at run time the kinematically allowed channels (that depend on the chosen set of external parameters), and to combine them consistently into the total width and branching ratios for a given particle. When implementing the file decays.py, it is strongly recommended to include all two-body decay channels for all the particles of the model, kinematically allowed or not, in order to prevent the code that relies on this option of the UFO format from producing incorrect results for some benchmark scenarios and correct ones for others.

The example of the Higgs boson is also a case where tree-level two-body decays are not sufficient for an accurate calculation of the total width of the particle. We should indeed include important contributions arising both from loop-induced Feynman diagrams and from three-body decays with off-shell effects, and the explicit choice of the renormalisation scale is known to impact the results strongly. We emphasise that it is not the role of the UFO model to check whether the provided formulas are enough to compute reliably the total width of a particle. The inclusion of the file decays.py in a UFO model instead only provides some analytical formula to facilitate the approximate evaluation of the particle widths.

4.5 Renormalisation group running effects

In many practical applications in particle physics, the free parameters of the Lagrangian are provided at a given input scale that could be quite different from the natural scales relevant to the physics process considered. One possibility to increase the precision of the predictions can therefore be to include renormalisation group (RG) running effects, which amounts to re-evaluating couplings and/or masses of the model at a specific scale. The UFO format has been extended [5] so that information on RG running could be provided within the optional file running.py. Following the general UFO philosophy, the UFO format only contains information on the running of the model’s parameters, and it does not provide any method allowing to handle it numerically. It is hence up to the high-energy physics software employed to handle this, and/or to rely on any existing external tools like those introduced in [31, 32, 47, 48].

In full generality, the RG equations associated with the model parameters $\{C\} = \{c_1, c_2, \ldots \}$ can be written as

$$\begin{aligned} \frac{\textrm{d} c_i(\mu )}{\textrm{d}\log \mu } = \gamma ^{(1)}_{ij}\ c_j(\mu ) + \gamma ^{(2)}_{ijk}\ \,c_j(\mu )c_k(\mu )+ \dots , \end{aligned}$$

(13)

where the anomalous dimension matrix $\gamma$ has been decomposed into a part involving a single other parameter ($\gamma ^{(1)}_{ij}$), a part involving two other parameters ($\gamma ^{(2)}_{ijk}$), and so on. The file running.py contains the values of the (non-zero) elements of the various $\gamma$ tensors appearing in the right-hand side of (13). Several of these elements can be defined simultaneously, provided that they correspond to the same analytical expression, which allows for an economical implementation. Consequently, users have the possibility to declare one Running object for each unique value of the elements of the various $\gamma$ tensors appearing in an RG equation given by (13), instead of one Running object per summand appearing in its right-hand side.

In practice, a Running object is defined as:

This declaration relies on three mandatory attributes. The first of them is the name of the object that is provided as a string (name), while the second attribute (value) refers to the analytical formula associated with the elements of the $\gamma$ tensors considered. This formula has to be provided as a valid Python expression that follows the same technical limitations as those inherent to the value attribute of the classes Parameter and Coupling (see Sects. 3.2 and 3.3). Moreover, this expression should not depend on any running parameter.

The value of the run_objects attribute contains a list in which each element is a list of external parameters (that must therefore be declared as instances of the Parameter class), with the exceptions of the standard QCD and QED couplings $\alpha _s$, $\alpha$, $g_s$ and e that could be used despite their external/internal nature. For each entry in the primary list, the first parameter corresponds to the parameter appearing on the left-hand side of (13), while all the other entries correspond to the parameters appearing on the right-hand side of that equation. In addition, a given parameter can be repeated as many times as needed to obtain a dependency on a specific power of it. The above example would correspond to

$$\begin{aligned} \begin{aligned} \frac{\textrm{d} c_1(\mu )}{\textrm{d}\log \mu }&= \frac{2}{3\pi }\ g_s c_2 + \dots , \\ \frac{\textrm{d} c_3(\mu )}{\textrm{d}\log \mu }&= \frac{2}{3\pi }\ g_s + \dots , \end{aligned} \end{aligned}$$

(14)

where the dots refer to terms not captured by the declaration of the RGE_1 object above.

5 Features pertaining to NLO

Up to this point, we have presented many aspects of the UFO format that provide the necessary information to generate tree-level matrix elements for arbitrary processes within a model. In principle, this information is also sufficient to produce matrix elements that include corrections associated with an arbitrary number of loops. In practice, however, a number of additional ingredients are necessary, mainly in the form of process-independent counterterms whose derivation is often quite involved. They should therefore ideally be supplied along with the rest of the tree-level information included in a UFO model. In this section, we describe the standard according to which this additional information is provided. We stress that this extended UFO format is not bound to one-loop corrections. However current applications only involve one-loop automatic matrix element generation, and it is therefore the case that drove our choice of syntax.

The counterterms provided in a UFO model containing the necessary information for performing computations at NLO accuracy (afterwards referred to as an NLO UFO) come in two distinct categories called $R_2$ and UV. The $R_2$ category contains rational terms of the second kind. They originate from the need of recovering contributions from the d-dimensional part of one-loop numerators that are typically computed in four dimensions by most numerical approaches [49,50,51,52,53,54,55,56]. The UV category implements the ultraviolet renormalisation of the model. This requires an analysis of the loop corrections to the vertices and two-point functions of the model, together with physically motivated choices made by the model builder (e.g. renormalisation conditions). For this reason, such counterterms are also best computed once and for all and specified in the UFO model. As it is further discussed below, an NLO UFO model is therefore suitable for one (or at most a few) particular renormalisation scheme(s).

We now present the standardised format in which these $R_2$ and UV counterterms are provided in an NLO UFO model, and that is already used by many one-loop providers (OLPs). This is however only achieved after first briefly introducing information relevant for one-loop matrix element computations in Sects. 5.1 (UV and $R_2$ counterterms) and 5.2 (the complex mass scheme). In Sect. 5.3, we focus on electroweak corrections in the Sudakov approximation and detail why additional pieces of information must be provided. As mentioned in Sect. 2.2, several additional files must be supplied in an NLO UFO model. We provide details about those files in Sect. 5.4. They consist of the file CT_vertices.py⁷ that allows for the instantiation of all CTVertex objects included in the model, the file CT_couplings.py that allows for the declaration of Coupling objects used in the counterterms, and the file CT_parameters.py that includes instantiation of all CTParameter objects needed in the counterterm couplings.

Additional information not available in any other UFO file is needed for making it possible to automatically calculate electroweak Sudakov corrections. This consists of the eigenvalues of various electroweak operators, and on how the components of the physical fields in a theory are gathered into $SU(2)_L$ multiplets. This is provided in the file CT_ewcasimirs.py through the declaration of EWOperator objects.

The objects specific to UFO NLO models can easily be accessed through generic lists included in the file object_library.py. A first list all_CTvertices collects all declared CTVertex objects, while a second list all_CTparameters is dedicated to the CTParameter objects declared by the user. On the other hand, all counterterm couplings (declared as standard Coupling objects) are available together with the other couplings of the model, through the list all_couplings. Finally, the list all_EWOperators collects additional objects relevant for the calculation of electroweak Sudakov corrections.

5.1 Counterterms

This section includes brief definitions of both the $R_2$ and UV counterterms relevant for NLO UFO models, and we additionally discuss aspects relevant to the automation of the computation of loop amplitudes.

5.1.1 $R_2$ counterterms

In d dimensions, one-loop amplitudes can be generically written as

$$\begin{aligned} \overline{A}\left( \overline{q}\right) = \frac{1}{\left( 2\pi \right) ^4}\int \textrm{d}^d\overline{q}\ \frac{\overline{N}\left( \overline{q}\right) }{\overline{D}_0\overline{D}_1\dots \overline{D}_{m-1}}, \end{aligned}$$

(15)

where $\overline{D}_i\equiv \left( \overline{q}+p_i\right) ^2-m_i^2$ are the propagator denominators with $m_i$ being the masses of the particles in the loop, q is the loop momentum and $p_i$ are linear combinations of external momenta. The bar denotes all the quantities living in d dimensions ($\overline{x}$), which can thus be split in a four-dimensional part (x) and a $d-4$ dimensional part ($\tilde{x}$) in dimensional regularisation, $\overline{x} \equiv x+{\tilde{x}}$.

Rational terms are finite contributions generated by the integration over $d-4$ pieces of the one-loop integrand. They are organised into two sets of contributions called $R_1$ and $R_2$. The rational terms $R_1$ originate from the $d-4$ component of the integrand denominators, and they can be computed similarly as the four-dimensional part of the integrand but using a different basis of scalar integrals [57]. The $R_2$ terms are instead due to the $d-4$ component of the numerator

$$\begin{aligned} R_2\equiv \lim _{\epsilon \rightarrow 0}\frac{1}{\left( 2\pi \right) ^4}\int \textrm{d}^d\overline{q}\ \frac{\tilde{N}\left( \tilde{q},q,\epsilon \right) }{\overline{D}_0\overline{D}_1\dots \overline{D}_{m-1}}, \end{aligned}$$

(16)

where $d\equiv 4-2\epsilon$ and $\tilde{N}\left( \tilde{q},q,\epsilon \right) \equiv \bar{N}(\bar{q})-N(q)$. Various schemes exist for the definition of the rational terms. For example, in the ’t Hooft–Veltman scheme [58] all the quantities involved in the loop, i.e. the loop momentum, the Dirac matrices and the metric, are taken as living in d dimensions, so that

$$\begin{aligned} \begin{aligned} \overline{\eta }^{\overline{\mu }\,\overline{\nu }}\overline{\eta }_{\overline{\mu }\,\overline{\nu }} = d\qquad \text {and}\qquad \overline{\gamma }^{\overline{\mu }} {\overline{\gamma }}_{\overline{\mu }} = d\,1\hspace{-2.5pt}\text {l}, \end{aligned}\end{aligned}$$

(17)

where $1\hspace{-2.5pt}\text {l}$ denotes the identity matrix in the Dirac space. Instead, the external momenta and the polarisation vectors live in four dimensions. Another scheme dependence is related to the choice of properties of the matrix $\gamma _5$ in d dimensions.⁸ For example, the Dirac matrices in d dimensions $\gamma _{\overline{\mu }}$ can be chosen to anti-commute with $\gamma _5$ [59,60,61]. In this case, the cyclic property of a Dirac trace has to be dropped to avoid algebraic inconsistency.

An extra scheme has to be defined when computing $R_2$ terms related to operators including more than two fermions due to the presence of evanescent operators, namely operators which are only non-vanishing in $d\ne 4$ dimensions. Any Lorentz invariant four-fermion operator can always be decomposed in a basis of four-fermion operator,

$$\begin{aligned} \bar{f_1}\varGamma _a f_2 \bar{f_3}\varGamma '_a f_4=\sum _k (b_k+a_k \varepsilon ) \bar{f_1}{{\tilde{\varGamma }}}_k f_2 \bar{f_3} {{\tilde{\varGamma }}}'_k f_4, \end{aligned}$$

(18)

where $f_i$ are fermions, $\varGamma '_a$ and $\varGamma _a$ are products of Dirac matrices that appear in the operator considered, and ${{\tilde{\varGamma }}}_k$ and ${{\tilde{\varGamma }}}'_k$ are products of Dirac matrices that define a basis of four-fermion operators in four dimensions. In the above expression, only the $b_k$ coefficients are fixed by requiring that both sides are equal in four dimensions. The determination of the coefficients $a_k$ in (18) requires extra conditions to be imposed, as for instance by requiring the equality of the trace of the Dirac structure [62]

$$\begin{aligned} \textrm{Tr} \Big ({{\tilde{\varGamma }}}_m \varGamma _a {{\tilde{\varGamma }}}'_m \varGamma '_a\Big ) = \sum _k (b_k+a_k \varepsilon ) \textrm{Tr} \Big ( {{\tilde{\varGamma }}}_m {{\tilde{\varGamma }}}_k {{\tilde{\varGamma }}}'_m {{\tilde{\varGamma }}}'_k\Big ). \end{aligned}$$

(19)

Once a scheme is fixed, the integral (16) can be evaluated from a set of process-independent Feynman rules which can be computed once and for all in a given model. The $R_2$ terms can typically not be captured by a direct four-dimensional implementation of the numerator of all possible loop integrands, and they must therefore be computed separately and analytically.

Finally, we emphasise that the $R_2$ and $R_1$ terms are not separately gauge-invariant, but only their sum is. This provides a means for a mutual check of the implementation of the model and the package employed for NLO computations, as $R_1$ and $R_2$ terms are computed independently. The former is handled by the NLO tool whilst the latter is provided in the NLO UFO model.

5.1.2 UV counterterms

In general, loop amplitudes in a quantum-field theory are not finite. One type of related divergences originates from loop-momenta with large Euclidean norm, and these divergences are usually referred to as ultraviolet divergences. They should be removed by the well-known renormalisation procedure, which reabsorbs them into a redefinition of the tadpoles, the fields and the free parameters of the model provided that the Lagrangian is renormalisable.⁹ This yields

$$\begin{aligned} \begin{aligned} t^\phi _0 \rightarrow&\ t^\phi +\delta t^\phi ,\\ \phi _0 \rightarrow&\ (1+\frac{1}{2}\delta Z_{\phi \phi })\phi + \sum _\chi \frac{1}{2} \delta Z_{\phi \chi } \chi ,\\ x_0 \rightarrow&\ x+\delta x , \end{aligned}\end{aligned}$$

(20)

where $t^\phi$ is the tadpole for the field $\phi$, i.e. the coefficient of the term linear in $\phi$ in the Lagrangian, $\phi$ and $\chi$ are physical fields with the same quantum numbers, and x is an external parameter (internal parameters being subsequently renormalised through their dependence on the external parameters). An additional zero subscript denotes the bare quantities compared to the renormalised fields or parameters, and a $\delta$ precedes the renormalisation constants. In the above expression, the wave function renormalisation constants have been expanded at one loop, and we consider that each fermion chirality is renormalised independently, as in the general case fermionic matter is chiral.

The bare Lagrangian is then the sum of a renormalised Lagrangian, depending only on renormalised quantities, and a counterterm Lagrangian at least linear in the renormalisation constants,

$$\begin{aligned} \mathcal {L}_0=\mathcal {L}+\delta \mathcal {L}. \end{aligned}$$

(21)

The UV counterterm vertices originate from the counterterm Lagrangian $\delta {{\mathcal {L}}}$, and they must be provided in an NLO UFO model. Their implementation is split within the files CT_vertices.py, CT_couplings.py and CT_parameters.py. As shown later, those vertices can be efficiently expressed in term of the renormalisation constants of the model thanks to the instantiation of the latter as CTParameters objects.

While the ultraviolet poles of the renormalisation constants are fixed by requiring the cancellation of the UV-divergences appearing in the loop amplitudes, their finite part can be chosen according to the renormalisation scheme considered. Some schemes are particularly suitable for numerical computations and make the evaluation of the loop amplitudes faster. For instance, imposing on-shell and/or complex renormalisation conditions for the derivation of the mass and wave function counterterms can avoid the computation of on-shell two-point loop Feynman diagrams on the external legs. Similarly, tadpole renormalisation allows us to ignore tadpole diagrams together with their renormalisation, as they identically cancel each other.

The renormalisation scheme used for the external parameters of the model has to be chosen adequately as well. Depending on the chosen scheme, the parameters may acquire a dependency on the renormalisation scale driven by related renormalisation group equations, and the associated running has to be included in order to guarantee formal NLO accuracy. The renormalisation of the strong coupling constant is a bit peculiar for hadronic collisions in that it must be set equal to what was used when determining the parton density functions. The other model parameters, such as for example the coefficients of higher-dimensional operators appearing in an effective field theory, can also run and mix through their renormalisation group equations, unless specific renormalisation conditions are chosen (see for example [63] for a fixed scale renormalisation of the new physics couplings without running).

Finally, we mention that special counterterms such as those related to the restoration of supersymmetry that is explicitly broken by dimensional regularisation can also be included in NLO UFO models, in a similar way as what is performed for the UV countertems of the model [37, 64].

5.2 The complex mass scheme

In order to properly treat unstable particles that appear in the S-matrix, a convenient scheme, the Complex Mass (CM) scheme, has been proposed, and it relies on the introduction of complex masses for all unstable particles [65, 66]. The generic support of the Complex Mass scheme in NLO calculations requires a careful analytic continuation of all loop integrals defining the renormalisation counterterms, a topic about which an extensive discussion can be found in [21].

5.2.1 Complex-mass and on-shell renormalisations

Imposing a renormalisation scheme leads to mass ($\delta M^2$) and wave function ($\delta Z$) renormalisation constants from the self-energy Feynman diagrams associated with the different particles. On-shell (OS) renormalisation conditions for a stable particle of (renormalised) mass M yield

$$\begin{aligned} \begin{aligned} \delta M_{\textrm{OS}}^2 =&\ \Re {[\varSigma (p^2=M^2)]},\\ \delta Z_{\textrm{OS}} =&\ -\Re {[\varSigma ^{\prime }(p^2=M^2)]}, \end{aligned}\end{aligned}$$

(22)

where the real part operator $\Re$ is only applied to the absorptive part of the self-energy function $\varSigma (p^2)$. In the CM scheme and for an unstable particle of (renormalised) mass M and width $\varGamma$, the renormalisation conditions lead to

$$\begin{aligned} \begin{aligned} \delta M_{\textrm{CM}}^2 =&\ \varSigma (p^2=M^2-i\varGamma M),\\ \delta Z_{\textrm{CM}} =&\ -\varSigma ^{\prime }(p^2=M^2-i\varGamma M). \end{aligned}\end{aligned}$$

(23)

The renormalised complex mass hence becomes

$$\begin{aligned} M^2-i\varGamma M=M_0^2-\delta M_{\textrm{CM}}^2, \end{aligned}$$

(24)

where $M_0$ is the bare mass.

One obvious distinction between the two schemes is the application of the operator $\Re$ in the OS scheme, that is absent in the CM scheme. This consideration suggests that a single UFO model compatible with both renormalisation schemes can be achieved, provided we introduce a new special function recms to be defined in the file function_library.py. This function is defined by

In addition, a switch called CMSParam is instantiated in the file parameters.py as a new internal Parameter object. Its value should be changed according to whether the complex-mass scheme is turned on or off, which is achieved for CMSParam=0.0 and CMSParam=1.0 respectively.

5.2.2 Analytic continuation

A dynamic choice of an appropriate Riemann sheet is mandatory within complex renormalisation conditions for the particle masses and wave functions, which critically depends on the mass spectrum and decay table in a model.

For example, the complex mass renormalisation constant associated with an unstable particle of mass M and width $\varGamma$ is derived from its one-loop self-energy function $\varSigma (p^2=M^2-i\varGamma M)$, as shown in (23). Let us assume that there is a contribution to this self-energy function originating from a two-point scalar function $B_0$ (depending on a single mass $M_2$ and width $\varGamma _2$),

$$\begin{aligned} \begin{aligned}&\varSigma (p^2=M^2-i\varGamma M) \\&\quad \supset B_0(p^2; 0, M_2^2-i\varGamma _2 M_2)|_{p^2=M^2-i\varGamma M}. \end{aligned}\end{aligned}$$

(25)

The analytic expressions for the $B_0$ integral in the first Riemann sheet, i.e. when the imaginary part of the momentum squared $\Im {(p^2)}\ge 0$, read [21]:

$$\begin{aligned} \begin{aligned}&\frac{1}{i\pi ^2}B_0(p^2; 0,0) = \frac{1}{\epsilon _{\textrm{UV}}} + 2 - \log {\frac{-p^2-i0}{\mu ^2}},\\&\frac{1}{i\pi ^2}B_0(p^2; 0,m^2) = \frac{1}{\epsilon _{\textrm{UV}}} + 2 + \log {\frac{\mu ^2}{m^2}} \\&\quad + \frac{m^2-p^2}{p^2}\log {\frac{m^2-p^2-i0}{m^2}},\\&\frac{1}{i\pi ^2}B_0(p^2; m_1^2,m_2^2) = \frac{1}{\epsilon _{\textrm{UV}}} + 2 - \log {\frac{p^2-i0}{\mu ^2}}\\&\quad + \sum _{i=\pm }{\left[ \gamma _i\log {\frac{\gamma _i-1}{\gamma _i}-\log {\left( \gamma _i-1\right) }}\right] }. \end{aligned}\end{aligned}$$

(26)

In these expressions, we have explicitly indicated the UV origin of the divergence (through $1/\epsilon _{\textrm{UV}}$), $\mu$ stands for the regularisation scale, and we have introduced

$$\begin{aligned} \begin{aligned}&\gamma _{\pm } = \frac{1}{2}\left( \gamma _0\pm \sqrt{\gamma _0^2-4\gamma _1}\right) ,\\&\gamma _0= 1+\frac{m_1^2}{p^2}-\frac{m_2^2}{p^2},\qquad \gamma _1= \frac{m_1^2-i0}{p^2}. \end{aligned}\end{aligned}$$

(27)

In order to properly analytically continue the $B_0$ function appearing in (25), a second Riemann sheet should be selected when the imaginary part of the momentum squared $\Im {(p^2)}<0$. This allows for a correct evaluation of the logarithm and square root functions. In our specific example, this gives

$$\begin{aligned} \begin{aligned}&\frac{1}{i\pi ^2}B_0(M^2-i\varGamma M; 0,M_2^2-i\varGamma _2M_2) = \frac{1}{\epsilon _{\textrm{UV}}}+2\\&\quad +\log {\frac{\mu ^2}{M_2^2\!-\!i\varGamma _2M_2}}+\frac{M_2^2\!-\!i\varGamma _2M_2\!-\!M^2\!+\!i\varGamma M}{M^2-i\varGamma M}\\&\quad \times \left\{ \begin{array}{l} \log _{-1}\frac{M_2^2-i \varGamma _2 M_2-M^2+i \varGamma M}{M_2^2-i\varGamma _2 M_2} \\ \qquad \qquad \text {if } M\!>\!M_2 \text { and } \varGamma M_2>\varGamma _2 M,\\ \log \frac{M_2^2-i\varGamma _2 M_2-M^2+i\varGamma M}{M_2^2-i\varGamma _2 M_2} \qquad \text {otherwise}.\\ \end{array} \right. \end{aligned}\end{aligned}$$

(28)

In the above expression, when $M>M_2$ and $\varGamma M_2>\varGamma _2 M$ we need to evaluate the logarithm in the second negative Riemann sheet,

$$\begin{aligned} \begin{aligned} \log _{-1}{z} \equiv&\ \log {z}-2\pi i,\\ \log {z} \equiv&\ \log {|z|} + i \arg {z} ~~\text {with}~ -\!\pi <\arg {z}\le \pi . \end{aligned}\end{aligned}$$

(29)

Moreover, we mention that the analytic continuation of the general $B_0$ function (i.e. $B_0(a; b,c)$ with $a\ne 0$, $b\ne 0$ and $c\ne 0$) is more involved than that achieved in the example.

In order to render a UFO model compliant with the CM scheme, we first define, for practical purpose, the finite remainder $B_{0f}$ of the function $B_0$,

$$\begin{aligned} B_{0f}(a; b,c) \equiv \frac{1}{i\pi ^2}B_0(a; b,c)-\left( \frac{1}{\epsilon _{\textrm{UV}}} \!+\! 2 \!+\! \log {\frac{\mu ^2}{c}}\right) , \end{aligned}$$

(30)

that is independent of the regularisation scale $\mu$. We then include, in the file function_library.py, the instantiation of a Function object B0F that can be used to calculate $B_{0f}(a; b,c)$ when $a\ne 0$ and $c\ne 0$.¹⁰ All other cases are simpler and could be explicitly ignored in terms of a UFO implementation, as the resulting expressions can be written in terms of $\log {}$ and $\log _{(\pm )}{}$ functions with

$$\begin{aligned} \log _{(\pm )}{z} \equiv \log {z}\pm 2\pi i \ \theta \big (-\Re {(z)}\big ) \ \theta \big (\mp \Im {(z)}\big ). \end{aligned}$$

(31)

These logarithmic functions must however be included in a UFO model, and they are thus all defined in the file function_library.py as reglog (for $\log {}$), reglogp (for $\log _{(+)}{}$) and reglogm (for $\log _{(-)}{}$). For instance, the declaration of the reglog function reads

We emphasise that an alternative and more robust method to evaluate all these two-point functions could rely on the trajectory method proposed in [21]. They should then be implemented as low-level functions, directly in the directories Fortran or Cpp of the UFO. An explicit example as implemented in the MadGraph5_aMC@NLO framework has been reported in [67], following the algorithm outlined in [21].

5.3 Electroweak Sudakov corrections

In the present section, we briefly review the formalism relevant for the evaluation of electroweak Sudakov corrections in the leading and subleading logarithmic approximation, or in other words, in the high-energy expansion of any given observable in powers of $\log \frac{s}{m^2_W}$ where s is the partonic centre-of-mass energy and $m_W$ is the mass of the W boson. A one-loop-accurate algorithmic procedure for calculations in this approximation has been available for a long time ago [68], and it has been automated in recent years for SM processes [69, 70]. Such calculations can be achieved via a few basic ingredients: the eigenvalues and eigenvectors of specific electroweak operators, and the finite but logarithmic-enhanced contributions to the parameter and wave-function renormalisation constants. Those quantities have been hard-coded, for example in the MadGraph5_aMC@NLO code [70], and their values had to be consistently matched to the conventions of the Feynman rules used in the calculations of the related amplitudes. This step can be avoided by providing the necessary additional information directly within a UFO model, using the same conventions as those used for the computation of amplitudes. Moreover, while so far the calculation of electroweak corrections has been automated for SM processes only, in the case of the Sudakov approximation it would be in principle also achievable for many BSM processes as soon as this additional information would be provided within UFO models.

It is important to bear in mind that for the calculation of electroweak corrections in the Sudakov approximation, the UFO model does not need to contain all the information necessary for the exact evaluation of NLO electroweak corrections. Within their approximate version, electroweak corrections can be extracted from the knowledge of two kinds of ingredients, namely the finite but logarithmically-enhanced contributions to the parameter and wave-function renormalisation constants, and the eigenvalues and eigenvectors of relevant electroweak operators. The latter can be derived from the content of the model in terms of gauge eigenstates and their associated representation. However, they are rarely available for an NLO UFO model expressed in terms of mass eigenstates. Consequently, this requires some addition to the NLO UFO format, that are to be implemented in the file CT_ewcasimirs.py. On the contrary, the finite but logarithmic-enhanced contributions to the parameter and wave-function renormalisation constants can be either computed once and for all from the knowledge of the bare Lagrangian and stored in the file CT_parameters.py, already described above, or they can be identified within the complete expressions of UV counterterms usually available in an NLO UFO model allowing for exact NLO EW corrections. In this second case, it is only necessary to provide additional information allowing for the selection of the finite but logarithmic-enhanced component of the correction.¹¹

In the following we briefly describe the analytical structure of the Denner-Pozzorini (DP) algorithm [68], following as much as possible the notation introduced in [70]. Practical details are provided at the end of Sect. 5.4.

We consider a process involving n external particles that we identify through the indices $i_1$, $\ldots$, $i_n$ and momenta $p_1$, $\ldots$, $p_n$. The associated tree-level amplitude is denoted by ${{\mathcal {M}}}_0^{i_1 \ldots i_n}$, and the one-loop electroweak Sudakov corrections $\delta {{\mathcal {M}}}^{i_1 \ldots i_n}$ can be written as

$$\begin{aligned} \delta {{\mathcal {M}}}^{i_1 \ldots i_n}=\delta ^{\textrm{EW}}_{i'_1 i_1 \ldots i'_n i_n} {{\mathcal {M}}}_0^{i'_1 \ldots i'_n}. \end{aligned}$$

(32)

In this expression, the matrix elements ${{\mathcal {M}}}_0^{i'_1 \ldots i'_n}$ are tree-level amplitudes associated with processes with n external particles that include up to two particles different from these of the original process. In addition, $\delta ^{\textrm{EW}}_{i'_1 i_1 \ldots i'_n i_n}$ collects contributions involving logarithms or double logarithms of kinematic invariants of the process, and of the squared mass of the W boson ($m^2_W$) and Z boson ($m^2_Z$).

The contributions to $\delta ^{\textrm{EW}}$ can be classified as

$$\begin{aligned} \delta ^{\textrm{EW}} = \delta ^{\textrm{LSC}} + \delta ^{\textrm{SSC}} + \delta ^{\textrm{C}} + \delta ^{\textrm{PR}} . \end{aligned}$$

(33)

In this expression, we have organised the corrections in their leading ($\delta ^{\textrm{LSC}}$) and subleading ($\delta ^{\textrm{SSC}}$) soft-collinear logarithmic contributions, the purely collinear logarithmic terms ($\delta ^{\textrm{C}}$), and the logarithms originating from parameter renormalisation ($\delta ^{\textrm{PR}}$).

The leading soft-collinear terms can be expressed as a sum over all external legs,

$$\begin{aligned} \delta ^{\textrm{LSC}} {{\mathcal {M}}}^{i_1 \ldots i_n} = \sum _{k=1}^n \delta ^{\textrm{LSC}}_{i'_k i_k}(k) {{\mathcal {M}}}^{i_1 \ldots i_k' \ldots i_n}, \end{aligned}$$

(34)

where the correction factors $\delta ^{\textrm{LSC}}_{i'_k i_k}$ depend on the properties of all possible pairs of states $i_k$ and $i_k'$ that can couple via $SU(2)_L\times U(1)_Y$ interactions. These read [71, 72]

$$\begin{aligned} \delta ^{\textrm{LSC}}_{i'_k i_k}= & {} -\frac{\alpha }{8\pi } \bigg [ \delta _{i'_k i_k} Q^2_k L^{\textrm{EM}} + C^{\textrm{EW}}_{i'_k i_k} \log ^2\frac{s}{m_W^2} \nonumber \\{} & {} \quad - 2 \big (I^Z_{i'_k i_k}\big )^2 \log \frac{m_Z^2}{m_W^2}\log \frac{s}{m_W^2} \bigg ], \end{aligned}$$

(35)

where $L^{\textrm{EM}}$ collects all logarithms of purely electromagnetic origin below the $m_W$ scale, and $Q_k$ is the electric charge of the state $i_k$. The $\delta ^{\textrm{LSC}}$ factor can thus be automatically derived, for any given process in any given model, once the eigenvalues of the effective Casimir operator matrix $C^{\textrm{EW}}$ and these of the $I^Z$ operator matrix are known, together with information on how the different states couple via electroweak interactions.

The subleading soft-collinear contributions are given as a double sum over the pairs of external states that can couple via electroweak interactions, each term in the sum featuring the exchange of a specific neutral or charged electroweak vector boson $V=A, Z, W^\pm$. They read

$$\begin{aligned} \delta ^{\textrm{SSC}} {{\mathcal {M}}}^{i_1 \ldots i_n} = \sum _{k=1}^n \sum _{\ell <k} \sum _V \delta ^{V, \mathrm SSC}_{i'_k i_k i'_\ell i_\ell } {{\mathcal {M}}}^{i_1 \ldots i_k' \ldots i_\ell ' \ldots i_n}, \end{aligned}$$

(36)

where the individual photon, Z and W boson corrections are respectively given by [70]

$$\begin{aligned} \begin{aligned} \delta ^{A, \mathrm SSC}_{i'_k i_k i'_\ell i_\ell }&= \frac{\alpha }{2\pi } \log \frac{s}{Q^2} \left( \log \frac{|r_{k\ell }|}{s}-i \pi \varTheta (r_{k\ell })\right) I^A_{i'_k i_k} I^A_{i'_\ell i_\ell },\\ \delta ^{Z, \mathrm SSC}_{i'_k i_k i'_\ell i_\ell }&= \frac{\alpha }{2\pi } \log \frac{s}{m_W^2} \left( \log \frac{|r_{k\ell }|}{s}-i \pi \varTheta (r_{k\ell })\right) I^Z_{i'_k i_k} I^Z_{i'_\ell i_\ell }\,,\\ \delta ^{W^\pm , \mathrm SSC}_{i'_k i_k i'_\ell i_\ell }&= \frac{\alpha }{2\pi } \log \frac{s}{m_W^2} \left( \log \frac{|r_{k\ell }|}{s}-i \pi \varTheta (r_{k\ell })\right) I^\pm _{i'_k i_k} I^\mp _{i'_\ell i_\ell }. \end{aligned}\end{aligned}$$

(37)

Here, we have neglected the terms denoted as $\varDelta ^{s\rightarrow r_{k\ell }}$ in [70], since they are not relevant for the present discussion. Moreover, the scale Q is the regularisation scale related to photon infrared divergences (we assume $Q^2\sim s$), $r_{kl} = (p_k + p_\ell )^2$ and $\varTheta$ denotes the usual Heaviside step function. As for the leading logarithms, the correction factors are hence generically known for any process in any model as soon as the eigenvalues of the $I^A$, $I^Z$ and $I^\pm$ operator matrices are provided.

We now turn to the single logarithmic contributions arising from the soft or collinear regime. These are written as a single sum over the external legs of the process,

$$\begin{aligned} \delta ^{\textrm{C}} {{\mathcal {M}}}^{i_1 \ldots i_n} = \sum _{k=1}^n \Big [ \delta ^{\textrm{coll}}_{i'_k i_k} + \frac{1}{2} \delta Z_{i'_k i_k}\Big ]\mathcal{M}^{i_1 \ldots i_k' \ldots i_n}. \end{aligned}$$

(38)

Such corrections are derived from the wave-function renormalisation constants relevant to all external legs in the process (possibly involving mixing with fields sharing the same quantum numbers), as well as from the mass-singular loop diagram contributions that respectively read, for bosons and fermions [73],

$$\begin{aligned} \begin{aligned} \delta ^{\textrm{B, coll}}_{i'_k i_k}&=\ \frac{\alpha }{4 \pi } C^\textrm{EW}_{i'_k i_k}\log \frac{Q^2}{m_W^2},\\ \delta ^{\textrm{F, coll}}_{i'_k i_k}&=\ \frac{\alpha }{2 \pi } \bigg [ C^{\textrm{EW}}_{i'_k i_k}\log \frac{Q^2}{m_W^2} + Q_k^2 \log \frac{m_W^2}{m_k^2} \bigg ] . \end{aligned}\end{aligned}$$

(39)

In these equations, $m_k$ and $Q_k$ are respectively the mass and the electric charge of the (fermionic) state k, while Q stands for the regularisation scale. The $\delta ^{\textrm{C}}$ corrections can hence be evaluated generically for any process in any model once the eigenvalues and eigenvectors of the electroweak effective Casimir operator $C^{\textrm{EW}}$ and the finite but logarithmic-enhanced component of the wave-functions renormalisation constants $\delta Z_{i'_k i_k}$ are known.

The last contributions in (33) arise from the renormalisation of the input parameters of the model, like $\alpha$ (or $G_F$), $m_W$, $m_Z$ and the masses of the Higgs boson and of the top quark. These logarithmic corrections are analogous to those associated with the wave-function renormalisation constants in (38), and include the finite but logarithmically-enhanced component of the parameter renormalisation constants. In both cases these have to be calculated externally, and they must be then provided as instances of the CTParameter and CTVertex classes.

5.4 Counterterm implementation

We reviewed in Sect. 5.1 the origin of the UV and $R_2$ counterterms that are relevant for numerical NLO calculations, and how they should be defined in order to obtain correct results from an NLO UFO model. In this section, we discuss the details of the format in which such counterterms are explicitly specified. One particular difficulty that an OLP faces when making use of UFO counterterms is to ensure that their selection is consistent with the loop diagrams contributing to the loop amplitude considered. This task can indeed be complicated by the fact that OLP users are often given the freedom to filter out any gauge-invariant selection of loop diagrams. It is therefore desirable that the OLP is able to enforce a strict correspondence between the loop diagrams generated and the associated counterterm.

For this reason, an NLO UFO model offers the possibility to group counterterms originating from a given subset of loop diagrams. A specific counterterm is then identified by a few properties that include the list of particles attached to the loop, the non-repeating set of particles running in the loop(s) ‘corresponding’ to this counterterm, the cumulative coupling orders (see Sect. 3.3) appearing in the loop vertices, and a keyword identifying the nature of the counterterm as well as how it is intended to be matched to the contributing loops.

We start our discussion of these properties with the example of the QCD $R_2$ counterterm for the triple-gluon vertex, encoded in the class CTVertex, that therefore features a few new attributes relative to the class Vertex previously introduced:

The triple nested structure of the loop_particles attribute allows users to group together similar contributions, while retaining the correct counterterm multiplicity in the case where only a subset of particles is selected at the level of the OLP. In this example, the $R_2$ counterterms stemming from each fermion species are all equal to the coupling R2_3Gq labelled by the key (0,0,0) in the couplings attribute. Here, the third index refers to the position in the loop_particles list while the first two indices refer to the particular colour and Lorentz structure considered (as for standard vertices in a UFO model; see Sect. 3.3).

The type of the counterterm encodes not only its nature but also how the OLP should match it to the loop diagrams present in the computation. $R_2$ counterterms are specified by setting the attribute type to the value R2. By construction and for a given set of external particles, one such counterterm must be included for each possible loop in the model, i.e. for each loop with the specific external particles considered that has given particles running in it, and with given cumulative coupling orders. Counterterms with the attribute type set to the value UVmass take their name from the mass renormalisation constants, and they feature a similar one-to-one correspondence to the (two-point) loop diagrams generated by the OLP. Their matching is therefore performed exactly like for counterterms of type R2, the type keyword serving to encode this time the UV nature of the counterterm. On the other hand, counterterms for which type attribute is fixed to the value UVloop (or UV) should not be considered by the matching procedure. The loop_particles attribute is in this case only used to discard the counterterm if any of its specified loop particles appears as having been globally excluded from the process definition by the user. Finally, counterterms for which the attribute type is set to UVtree do not have a direct correlation to any particular loop diagram, and as such they should be constructed independently. Their contribution must be built exactly like that of tree-level diagrams, while however enforcing the presence of exactly one such counterterm vertex per diagram. This type of counterterm is for example well suited to implement counterterms restoring supersymmetry when it is explicitly broken by dimensional regularisation.

The need for a distinction between the types UVmass and UVloop may seem unnecessary at first, so we illustrate its use-case with the UV QCD counterterm $Z_{gd\bar{d}}$ of the vertex $gd\bar{d}$. Such a counterterm is defined by

$$\begin{aligned} Z_{gd\bar{d}} \equiv Z_{\alpha _s}^{\frac{1}{2}} Z_{g}^{\frac{1}{2}} Z_{d}^{\frac{1}{2}} Z_{\bar{d}}^\frac{1}{2}\,, \end{aligned}$$

(40)

which depends on the wave function renormalisation constants associated with the particles incoming to the vertex and with that of the relevant coupling. This highlights the fact that the loop particles associated with the counterterm $Z_{gd\bar{d}}$ are not directly related to the corresponding loop diagrams, but rather to the loop particles originating from the explicit calculation of the involved renormalisation constants. This leads to a lack of direct correspondence between a vertex counterterm and its corresponding loop corrections. The listed loop_particles cannot thus be matched directly to the particle content of the contributing diagrams, and they only represent an overall list of allowed particles in the process. According to the UFO standard, this counterterm is defined with type UV $\equiv$ UVloop,

A more detailed and technical description of the vertex renormalisation and loop particle matching procedure can be found in eqs. (2.80)–(2.87) in [20].

We now discuss the implementation of the couplings assigned to CTVertex instances. The main difference with respect to tree-level couplings already used in LO-only UFO is the necessity of supplying them in the form of terms of a Laurent series in the dimensional regulator $\epsilon$. This is achieved by allowing for the specification of an expansion dictionary as the value of the coupling,¹²

$$\begin{aligned} \frac{A}{\epsilon ^2} + \frac{B}{\epsilon } + C \leadsto \mathtt{\{-2:A, -1:B, 0:C\}} \end{aligned}$$

(41)

Given the omnipresence of wave function renormalisation constants in all vertex counterterms (see (40)), it is desirable to be able to define counterterm-related parameters which are themselves expansions in $\epsilon$. This is allowed in the NLO UFO format, and taken advantage of, for example when writing the coupling UV_GQQt appearing in the definition of the CTVertex UV_GQQt,

where the new cond function, implemented in the file function_library.py, is a shortcut function designed to support the cases of both zero and finite top mass. When the first argument of the cond function is equal to 0, then the second argument of the cond function is returned. Otherwise, the third argument is returned. Moreover, the coupling order in this example is QCD=3, which corresponds to the cumulative coupling orders of the loop corrections to that vertex. It is important that this coupling order is correctly set, as it may be used in the OLP matching procedure when building the counterterm contributions.

The introduction of the CTParameter object named G_UVt is convenient (though not necessary), as it will appear in the counterterms associated with many QCD vertices. In order to facilitate the usage and import of the model, there are a few limitations to writing counterterm couplings. First, the value attribute of a counterterm coupling can be either a string or an expansion dictionary. When the latter is used, the string expression of its values can only involve instances of Parameter, but not of CTParameter. Second, when writing the coupling value as a string, it must correspond to a term whose summands each contain at most k occurrences of CTparameter objects for a UFO model suitable for $\hbox {N}^{k}$LO computations. At NLO, the expression ‘2*ParamA*CTParamB + 4*CTParamE’ would be acceptable (one CTParameter instance in each of the two summands), but ‘2*CTParamA*CTParamB + 4*CTParamE’ would not (two CTParameter instances in the first term).

Additionally, the UFO 2.0 format does not explicitly differentiate the UV and infrared quantities $\epsilon _{\textrm{UV}}$ and $\epsilon _{\textrm{IR}}$ in the expansion dictionaries. The distinction between them can however be retained at NLO by using reserved parameters named epsUV and epsIR as multiplicative factors, that are defined as external parameters in a Les Houches block TECHNICAL.¹³ In addition, NLO UFO models include a LOOP block that is reserved for the renormalisation scale parameter MU_R that appear in loop integrals.

Before closing this section, we now discuss how to implement in an NLO UFO model the information necessary for the calculation of electroweak Sudakov corrections to any matrix element in the leading and subleading logarithmic approximation. As detailed in Sect. 5.3, these corrections can be generically derived for any process from the knowledge of the eigenvalues of the electroweak effective Casimir operator matrix $C^{\textrm{EW}}$, that of the photon, Z-boson and W-boson operator $I^A$, $I^Z$ and $I^\pm$, and from information on which pairs of states interact through electroweak interactions (and of course how). Additional quantities such as the coefficients of the related beta function or Dynkin operators may also be useful in this context, and can be further added to this list (see [68]).

In the following, we first consider as an example the matrix associated with the electroweak Casimir operator when it acts on neutral weak bosons, [68]

$$\begin{aligned} C^{\textrm{EW}}_{AZ} = \frac{2}{s_w^2} \begin{pmatrix} s_w^2 &{} -s_wc_w\\ -s_wc_w &{} c_w^2\end{pmatrix}. \end{aligned}$$

(42)

In this expression, $s_w$ and $c_w$ stand for the sine and cosine of the electroweak mixing angle. The corresponding implementation in a UFO model is achieved through the declaration of an EWOperator object,

In this example, the EWOperator object considered is defined through four mandatory attributes. The first of them consists of its name (name), and the second of them, type, can either take the value ‘casimir’ (for the eigenvalues of the effective electroweak Casimir operator, like in the above example) or refer to one of the electroweak bosons of the theory (for the various $I^V$ operators, as illustrated in the next example below). The value of the attribute particles is a list that provides information on the states relevant for the operator considered. This primary list includes a single list for the electroweak Casimir operator $C^{\textrm{EW}}$ and the ‘neutral’ operators $I^A$ and $I^Z$, and two lists for the ‘charged’ operators $I^\pm$ that connect different elements of the weak multiplets of the model. The (non-zero) matrix elements of the operator are finally provided through the value of the attribute elements, that contains a dictionary mapping any non-zero element of the matrix to a Parameter object (declared as detailed in Sect. 3.2).

As another example, we provide a possible implementation of the $I^+$ operator, for the case in which it acts on left-handed quarks,¹⁴

This time the attribute particles contains two lists of particles, as the $I^+$ operator relates up-type fermions (the first list, [ P.u, P.c, P.t]) and down-type ones (the second list, [ P.d, P.s, P.b]). Moreover, an optional attribute (chirality), relevant when fermions are involved, has been included in the declaration. Its value indicates that only the left-handed components of the fermions involved is concerned.

In addition to the information provided above, the derivation of all logarithmic corrections to any given matrix element shown in (33) requires to include those stemming from parameter and wave-function renormalisation. This can be achieved automatically once the renormalisation constants are computed or, in the case of a model that allows for electroweak corrections in the Sudakov approximation but not for exact NLO electroweak corrections, they have to be calculated for this purpose. In both cases, it is necessary to access directly the finite but logarithmically-enhanced component of the parameter counterterms and possibly their impact in vertex counterterms. The analytical results should therefore be provided, through declarations of CTParameter and possibly CTVertex objects relevant to the implementation of counterterms (see above).

6 Conclusion

In this paper, we have presented the current 2.0 update of the UFO format for (B)SM models, that we have coined the ‘Universal Feynman Output’ format. This new name has been adopted to distinguish the current format from its initial version, as the UFO has evolved significantly during the last decade. Moreover, the UFO is not solely connected with FeynRules anymore, but it lies at the heart of many high-energy physics software tools.

The UFO 2.0 format includes several new features that were not part of the initial proposal, thanks to the flexible and modular structure that drove the design of the UFO ten years ago, and that allows it to be easily expandable and encompass features relevant for the interest of high-energy physics software at a given time. Initially, the UFO format has been designed to include information on a model’s particles, the list and values of the parameters appearing in the model’s Lagrangian and the associated interaction vertices. In addition to such information, UFO 2.0 models can optionally include information on the particle’s decay widths, on the renormalisation group running of the model’s parameters and masses, and on ingredients relevant for automatic higher-order perturbative calculations. Moreover, users can include form factors and enforce the usage of custom propagators in their implementation. Whereas some of these features were already described in earlier publications, others have never been documented officially in any scientific article.

It was the aim of the present paper to release the most up-to-date documentation of the UFO format, collecting in a single document information about all features that could be present in a UFO model, from the initial mandatory ones to those subsequently developed during the last decade.