Particle event generator: a simple-in-use system PEGASUS version 1.0

Abstract

pegasus is a parton-level Monte-Carlo event generator designed to calculate cross sections for a wide range of hard QCD processes at high energy pp and $p\bar{p}$ collisions, which incorporates the dynamics of transverse momentum dependent (TMD) parton distributions in a proton. Being supplemented with off-shell production amplitudes for a number of partonic subprocesses and provided with necessary TMD gluon density functions, it produces weighted or unweighted event records which can be saved as a plain data file or a file in a commonly used Les Houches Event format. A distinctive feature of the pegasus is an intuitive and extremely user friendly interface, allowing one to easily implement various kinematical cuts into the calculations. Results can be also presented “on the fly” with built-in tool pegasus plotter. A short theoretical basis is presented and detailed program description is given.

1 Program summary

Title: pegasus 1.0

Computer for which the program is designed and others on which it is operable: Linux systems

Programming Language used: C++ and Fortran 77, compiled with g++ and gfortran

High-speed storage required: No

Separate documentation available: No

Keywords: QCD, BFKL and CCFM evolution equations, small-x physics, TMD parton densities, high-energy factorization

Physical problem: Theoretical description of a number of high energy processes proceeding with large momentum transfer and containing multiple hard scales needs for transverse momentum dependent (TMD) parton (quark or gluon) distributions in a proton [1,2,3,4]. These quantities encode the nonperturbative information on proton structure, including transverse momentum and polarization degrees of freedom and satisfy the Balitsky–Fadin–Kuraev–Lipatov (BFKL) [5,6,7] or Catani–Ciafaloni–Fiorani–Marchesini (CCFM) [8,9,10,11] evolution equations, which resum large logarithmic terms proportional to $\alpha _s^n \ln ^n s/\Lambda _\mathrm{QCD}^2 \sim \alpha _s^n \ln ^n 1/x$. At high energies (or, equivalently, at small x) the latter are expected to become equally (or even more) important than the conventional Dokshitzer–Gribov–Lipatov–Altarelli–Parisi (DGLAP) contributions proportional to $\alpha _s^n \ln ^n \mu ^2/\Lambda _\mathrm{QCD}^2$ [12,13,14,15]. The CCFM equation takes into account additional terms proportional to $\alpha _s^n \ln ^n 1/(1 - x)$ and, therefore, is valid at both small and large x.

Solution: Experimental investigations of hadron scattering processes at high energy colliders, such as the Large Hadron Collider (LHC), usually imply multiparticle final states and implement complex kinematical restrictions on the fiducial phase space. The multi-purpose Monte-Carlo event generators are commonly used tools for theoretical description of the collider measurements. Most of them (for example, pythia 8.2 [16], mcfm 9.0 [17], madgraph5_amc@nlo [18], sherpa 2.2 [19], herwig++ 2.7.1 [20], powheg box [21,22,23] and other) use conventional (collinear) QCD factorization, which is based on the DGLAP resummation. On the other side, the hadron-level Monte-Carlo event generator cascade [24, 25] and parton-level generator katie [26] can deal with non-zero transverse momenta of incoming off-shell partons. In particular, cascade, being supplemented with off-shell amplitudes for the hard scattering subprocesses, employs the CCFM equation for initial state gluon evolution. katie calculates the tree-level off-shell amplitudes for arbitrary processes within the Standard Model (up to four final-state particles) and uses tmdlib package [27] to access the different sets of the TMD parton densities. pegasus is a newly developed parton-level Monte-Carlo event generator designed to calculate cross sections for a wide range of hard QCD processes, which also incorporates the TMD gluon dynamics in a proton. It provides all necessary components, including off-shell (dependent on the transverse momenta) production amplitudes and grid files for TMD gluon densities, interpolated automatically. pegasus offers an intuitive and extremely user friendly interface, which allows one to easily implement various kinematical cuts into the calculations. Generated events (weighted or unweighted) can be stored in the Les Houches Event file or presented “on the fly” with convenient built-in tool pegasus plotter.

The underlying physics in cascade, katie and pegasus is basically the same. However, pegasus simplifies setting the parameters and kinematic constraints (through the menu, with no programming); it can switch between the collinear and TMD modes; it provides a choice between weighted and unweighted events; and it operates with a graphics interface, which is detached in the console version (if a long-time calculation is needed). These features make pegasus more flexible and better adjustable to the user’s needs.

Restrictions on the complexity of the physical problem: The following production amplitudes are implemented:

• $g^* + g^* \rightarrow Q + \bar{Q}$, where $Q = c$ or b

• $g^* + g^* \rightarrow \mathcal{Q} + b + \bar{c}$, where $\mathcal{Q} = B_c$ or $B_c^{(*)}$

• $g^* + g^* \rightarrow Q\bar{Q}\left[ \,^3S_1^{(1)}\right] + g \rightarrow \mathcal{Q} + g$, where $\mathcal{Q} = \psi ^\prime$, $J/\psi$ or $\Upsilon (3S)$

• $g^* + g^* \rightarrow Q\bar{Q}\left[ \,^1S_0^{(8)}, \,^3S_1^{(8)}, \, ^3P_J^{(8)}\right] \rightarrow \mathcal{Q}$, where $\mathcal{Q} = \psi ^\prime$, $J/\psi$ or $\Upsilon (3S)$

• $g^* + g^* \rightarrow Q\bar{Q}\left[ \,^3P_J^{(1)}, \,^3S_1^{(8)} \right] \rightarrow \mathcal{Q}$, where $\mathcal{Q} = \chi _{cJ}(1P)$ or $\chi _{bJ}(3P)$

• $g^* + g^* \rightarrow H^0 \rightarrow \gamma \gamma$

• $g^* + g^* \rightarrow H^0 \rightarrow ZZ^* \rightarrow 4l$

• $g^* + g^* \rightarrow H^0 \rightarrow W^+W^- \rightarrow e^{\pm }\mu ^{\mp } \nu \bar{\nu }$

• $g^* + g^* \rightarrow V + Q + \bar{Q}$, where $V = \gamma$ or $V = Z/\gamma ^*$

• $q + g \rightarrow V + q$, where $V = \gamma$ or $V = Z/\gamma ^*$

• $q + Q \rightarrow V + q + Q$, where $V = \gamma$ or $V = Z/\gamma ^*$

• $q + \bar{q} \rightarrow V + Q + \bar{Q}$, where $V = \gamma$ or $V = Z/\gamma ^*$

The standard spectroscopic notation $^{(2S+1)}L_J^{(a)}$ is used for intermediate Fock state of heavy quark pair $Q\bar{Q}$ produced with spin S, orbital angular momentum L, total angular momentum J and color representation a. In the subprocesses above, the radiative decays $\chi _{cJ}(1P) \rightarrow J/\psi + \gamma$ and $\chi _{bJ}(3P) \rightarrow \Upsilon (3S) + \gamma$ are simulated keeping the proper spin structure of the decay amplitudes. The radiative decays $\psi ^\prime \rightarrow J/\psi + \pi ^+ + \pi ^-$ or $\psi ^\prime \rightarrow J/\psi + \pi ^0 + \pi ^0$ can be generated according to the phase space. Also, the subsequent leptonic decays $J/\psi \rightarrow l^+l^-$, $\Upsilon (3S) \rightarrow l^+l^-$ and $\psi ^\prime \rightarrow l^+l^-$, $Z/\gamma ^* \rightarrow l^+l^-$ can be generated optionally.

The present version of pegasus is applicable for Fermilab Tevatron and CERN LHC processes.

Other program used: qwtplot library (version 6.1.3) [28] for histogram plotting, vegas routine [29] for multi-dimensional Monte-Carlo integration, stand-alone C++ codes from MMHT [30] and CTEQ [31] groups to provide access to the MSTW’2008, MMHT’2014, CT’14 and CTEQ6.6 parton density functions (implemented into the program package).

Download of the program:https://theory.sinp.msu.ru/dokuwiki/doku.php/pegasus/download.

2 Theoretical framework

Here we present a short review of ideas and frameworks which form the theoretical basis of pegasus. For more information we address the reader to reviews [1,2,3,4].

2.1 Kinematics and cross section formula

pegasus operates in the general framework of conventional Parton Model extended to $k_T$-factorization approach [32,33,34,35]. It employs the factorization hypothesis to calculate the cross section of a physical process through the convolution of the (TMD or collinear) parton densities and hard scattering amplitudes. By default, the $k_T$-factorization scheme is assumed and can be switched to the collinear QCD factorization for each of colliding particles.

pegasus refers to $2\rightarrow 1$, $2\rightarrow 2$ and $2\rightarrow 3$ partonic subprocesses. The initial partonic state is described with Sudakov variables, namely, the light-cone momentum fractions $x_1$ and $x_2$ and non-zero parton transverse momenta $k_{1T}$ and $k_{2T}$. The n-particle final state phase space is parameterized in terms of particle rapidities $y_i$, transverse momenta $p_{iT}$, and azimutal angles $\phi _i$, where $i = 1\,\ldots \,n$ [36]. The fully differential cross section reads

$$\begin{aligned}&\displaystyle d\sigma (p p \rightarrow p_1 \, \cdots \, p_n + X) = {\pi \over \hat{s} F} (4\pi )^{2 - 2n} \nonumber \\&\quad \times \sum _{a, b} \sum _\mathrm{spin} \sum _\mathrm{colors} |\mathcal{A}_{ab}(k_1 k_2 \rightarrow p_1 \, \cdots \,p_n)|^2 \times \nonumber \\&\quad \displaystyle \times f_a(x_1, {\mathbf {k}}_{1T}^2,\mu ^2) f_b(x_2, {\mathbf {k}}_{2T}^2,\mu ^2) d{\mathbf {k}}_{1T}^2 d{\mathbf {k}}_{2T}^2 d{\mathbf {p}}_{1T}^2 \nonumber \\&\quad \cdots d{\mathbf {p}}_{(n-1)T}^2 dy_1 \, \cdots \, dy_n {d\phi _1 \over 2\pi } \, \cdots \, {d\phi _{n-1} \over 2\pi } , \end{aligned}$$

(1)

where the 4-momenta for all particles are given in parentheses, $\hat{s}=(k_1+k_2)^2$ is the subprocess invariant energy, F is the flux factor (see below) and $\mu ^2$ is the factorization scale. The longitudinal momentum fractions $x_1$ and $x_2$ are not the integration variables; they are obtained from the energy-momentum conservation laws in the light-cone projections:

$$\begin{aligned} x_1 \sqrt{s} = \sum _{i = 1}^n m_{iT} \exp (y_{i}), \quad x_2 \sqrt{s} = \sum _{i = 1}^n m_{iT} \exp (-y_{i}), \end{aligned}$$

(2)

where $m_{iT}$ is the transverse mass of produced particle i. In the optional choice of collinear QCD factorization, we replace the TMD parton densities with conventional distributions, omit the integration over ${\mathbf {k}}_{1T}^2$ and ${\mathbf {k}}_{2T}^2$ and take the on-shell limit in the scattering amplitude $\mathcal{A}_{ab}$ as described below.

2.2 Off-shell partonic amplitudes

The calculation of partonic amplitudes follows the standard Feynman rules, with the exception that the initial gluons are off-shell.

Off-shell gluons may have nonzero transverse momentum and an admixture of longitudinal component in the polarization vector. In accordance with the $k_T$-factorization prescriptions, the initial gluon spin density matrix is taken in the form [34, 35]:

$$\begin{aligned} \sum \epsilon _g^\mu \epsilon _g^{*\nu } = k_T^\mu k_T^\nu /|k_T|^2. \end{aligned}$$

(3)

In the collinear limit, when $k_T\rightarrow 0$, this expression converges to the ordinary $\sum \epsilon _g^\mu \epsilon _g^{*\nu } = -g^{\mu \nu }/2$. This property provides continuous on-shell limit for the partonic amplitudes.

In general, off-shell initial states may cause violation of gauge invariance in the non-abelian theories. We solve this problem in a way [33]. We start with a set of “extended” diagrams, where the off-shell gluons are considered as emitted by on-shell external fields (say, quarks), so that they represent internal lines in the Feynman graphs. As all of the external lines in these graphs are on shell, the gauge invariance of the whole set is fulfilled. However, the extended gauge invariant set may contain unfactorizable diagrams that cannot be represented as a convolution of the hard scattering amplitude and gluon density functions (such as, for example, Fig. 5e, d in [33]). At the same time, we learn from [33] that the non-factorizable diagrams vanish in the particular gauge (3). Therefore, within this gauge, we are left with the usual diagrams of the Parton Model.

In fact, the prescription (3) is a remake of Equivalent Photon Approximation (EPA) in QED and DIS. Consider a photon emitted by an electron: $e(p)\rightarrow e'(p')+ \gamma (k)$. Then, taking trace over the electron line in the matrix element squared one obtains the polarization tensor

$$\begin{aligned} L^{\mu \nu }= & {} \mathrm{tr} \left[ (\hat{p}'+m_e)\,\gamma ^\mu \,(\hat{p}+m_e)\,\gamma ^\nu \right] \nonumber \\= & {} 8\,p^\mu p^\nu - 4(pk)\,g^{\mu \nu }. \end{aligned}$$

(4)

Neglecting the second term in the right hand side in the small x limit, $p\gg k$, one immediately arrives at the spin structure $\sum \epsilon ^{\mu }\epsilon ^{*\nu } \sim L^{\mu \nu }\sim p^\mu p^\nu$. It can be rewritten in the form (3) after using the Sudakov representation $k=xp+k_{T}$ and applying a gauge shift $\epsilon ^\mu \rightarrow \epsilon ^\mu -k^\mu /x$. The gauge invariance of the matrix element is correct to the accuracy of $\mathcal{O}(x)\simeq 10^{-4} - 10^{-6}$.

2.3 CCFM evolution equation

The CCFM evolution equation [8,9,10,11] for TMD gluon density resums both BFKL [5,6,7] large logarithms $\alpha _s^n \ln ^n 1/x$ and $\alpha _s^n \ln ^n 1/(1 - x)$ terms. In the limit of asymptotic energies, it is almost equivalent to BFKL, but also similar to usual DGLAP evolution [12,13,14,15] for large x. Moreover, it introduces angular ordering condition to treat correctly gluon coherence effects. In the leading logarthmic approximation (LLA), the CCFM equation for TMD gluon density $f_g(x,{\mathbf {k}}_T^2,\mu ^2)$ can be written as

$$\begin{aligned}&f_g(x,{\mathbf {k}}_T^2,\mu ^2) = f_g^{(0)}(x,{\mathbf {k}}_T^2,\mu _0^2) \Delta _s(\mu ,\mu _0)\nonumber \\&\quad + \int \frac{dz}{z}\int \frac{dq^2}{q^2}\Theta (\mu -zq)\Delta _s(\mu ,zq) \tilde{P}_{gg}(z,{\mathbf {k}}_T^2, q^2)\nonumber \\&\quad \times f_g\left( \frac{x}{z},{\mathbf {k}}^{\prime \, 2}_T,q^2\right) , \end{aligned}$$

(5)

where ${\mathbf {k}}_T^\prime = {\mathbf {q}}(1 - z) + {\mathbf {k}}_T$ and $\tilde{P}_{gg}(z,{\mathbf {k}}^2_T,q^2)$ is the CCFM splitting function:

$$\begin{aligned}&\displaystyle \tilde{P}_{gg}(z,{\mathbf {k}}^2_T,q^2) = \bar{\alpha }_s(q^2(1-z)^2) \left[ \frac{1}{1-z}+\frac{z(1-z)}{2}\right] +\nonumber \\&\quad \displaystyle + \bar{\alpha }_s({\mathbf {k}}_T^2)\left[ \frac{1}{z}-1+\frac{z(1-z)}{2}\right] \Delta _{ns}(z,{\mathbf {k}}^2_T,q^2). \end{aligned}$$

(6)

The Sudakov and non-Sudakov form factors read:

$$\begin{aligned} \ln \Delta _s(\mu ,\mu _0)= & {} - \int \limits _{\mu _0^2}^{\mu ^2}\frac{d\mu ^{\prime \, 2}}{\mu ^{\prime \,2}}\int \limits _0^{1-\mu _0/\mu ^{\prime }}d\zeta \,\nonumber \\&\times \frac{\bar{\alpha }_s(\mu ^{\prime \, 2}(1-\zeta )^2)}{1-\zeta }, \end{aligned}$$

(7)

$$\begin{aligned} \ln \Delta _{ns}(z,{\mathbf {k}}_T^2, {\mathbf {q}}_T^2)= & {} -\bar{\alpha }_s({\mathbf {k}}_T^2)\int \limits _0^1\frac{dz^\prime }{z^\prime }\int \frac{dq^2}{q^2}\nonumber \\&\times \Theta ({\mathbf {k}}_T^2-q^2)\Theta (q^2-z^{\prime \,2} {\mathbf {q}}^2_T). \end{aligned}$$

(8)

where $\bar{\alpha }_s = 3 \alpha _s/\pi$. The first term in the CCFM equation is the initial TMD gluon density $f_g^{(0)}(x,{\mathbf {k}}_T^2,\mu _0^2)$ multiplied by the Sudakov form factor, decribing the contribution of non-resolvable branchings between the starting scale $\mu _0^2$ and scale $\mu ^2$. The second term represents the details of the QCD evolution expressed by the convolution of the CCFM gluon splitting function $\tilde{P}_{gg}(z,{\mathbf {k}}^2_T,q^2)$ with the gluon density and Sudakov form factor. The angular ordering condition is introduced with the theta function, so the evolution scale $\mu ^2$ is defined by the maximum allowed angle for any gluon emission [8,9,10,11]. The main advantage of this approach is the implicit including of higher-order radiative corrections (namely, a part of NLO + NNLO + $\cdots$ terms corresponding to the initial state real gluon emissions). Some details can be found, for example, in reviews [2,3,4].

A similar equation can be also written [37] for TMD valence quark densities with replacement of the gluon splitting function by the quark one.¹ One usually takes the initial TMD gluon and valence quark distributions as

$$\begin{aligned} f_g^{(0)}(x, {\mathbf {k}}_T^2, \mu _0^2)= & {} Nx^{-B}(1-x)^C\exp (-{\mathbf {k}}_T^2/\sigma ^2), \end{aligned}$$

(9)

$$\begin{aligned} f_{q_v}^{(0)}(x, {\mathbf {k}}_T^2, \mu _0^2)= & {} x q_v(x, \mu _0^2) \exp (-{\mathbf {k}}_T^2/\sigma ^2)/\sigma ^2, \end{aligned}$$

(10)

where $\sigma =\mu _0/\sqrt{2}$ and $q_{v}(x,\mu ^2)$ is the conventional (collinear) quark density function. The parameters N, B and C can be fitted from collider data (see [37]).

The TMD (valence) quark densities for CCFM approach are not available in the current version of the pegasus.

2.4 Parton Branching approach

The Parton Branching (PB) method [39, 40] allows one to solve the DGLAP equations iteratively. It gives a possibility to take into account simultaneously soft-gluon emission at $z \rightarrow 1$ and transverse momentum $\mathbf {q}_T$ recoils in the parton branchings along the QCD cascade. The latter leads to a natural determination of TMD density functions for both gluons and quarks. A soft-gluon resolution scale $z_M$ is introduced to separate resolvable and non-resolvable emissions, which are treated via the DGLAP splitting functions $P_{ab}(\alpha _s, z)$ and Sudakov form-factors, respectively. The PB equations for TMD parton densities read:

$$\begin{aligned}&\displaystyle f_a(x,{\mathbf {k}}_T^2,\mu ^2) = f_a^{(0)}(x,{\mathbf {k}}_T^2,\mu _0^2)\Delta _a(z_M,\mu ^2,\mu ^2_0) \nonumber \\&\quad + \sum _b\int \limits _x^{z_M}dz\int \frac{d^2\mathbf {q}}{\pi \mathbf {q}^2}\Theta (\mu ^2- \mathbf {q}^2) \times \nonumber \\&\quad \displaystyle \times \Theta (\mathbf {q}^2-\mu _0^2) \frac{\Delta _a(z_M,\mu ^2,\mu ^2_0)}{\Delta _a(z_M,\mathbf {q}^2,\mu ^2_0)} P_{ab}^{(R)}(\alpha _s(\mathbf {q}^2), z)\nonumber \\&\quad \times f_b\left( \frac{x}{z},{\mathbf {k}}_T^{\prime \,2},q^2\right) , \end{aligned}$$

(11)

where $a = q$ or g and ${\mathbf {k}}_T^\prime = {\mathbf {q}}(1 - z) + {\mathbf {k}}_T$. The Sudakov form factors are defined as

$$\begin{aligned} \ln \Delta _a(z_M,\mu ^2,\mu ^2_0){= -}\sum _b\int \limits _{\mu _0^2}^{\mu ^2}\frac{d\mu ^{\prime \, 2}}{\mu ^{\prime \,2}}\int \limits _0^{z_M}d\zeta \,\zeta \,P_{ba}^{(R)}(\alpha _s(\mu ^{\prime \, 2}),\zeta ). \end{aligned}$$

(12)

The real-emission branching probabilities $P_{ab}^{(R)}$ are obtained from splitting functions $P_{ab}$ by eliminating $\delta (1-z)$-terms and substituting $1/(1-z)_+\rightarrow 1/(1-z)$. The evolution scale $\mu ^2$ can be connected with the emission angle with respect to the beam direction, that leads to the angular ordering condition $\mu = |{\mathbf {q}}_T|/(1 - z)$. The dependence on the $z_M$ dissapears when this angular ordering condition is applied and $z_M$ is large enough. The initial TMD parton distributions are taken in a factorized form as a product of conventional quark and gluon densities and intrinsic transverse momentum distributions (taken in gaussian form [18, 24, 25]), where all the parameters can be fitted from the collider data. Unlike the CCFM, the PB densities have the strong normalization property:

$$\begin{aligned} \int \limits _0^{\mu ^2} f_a(x, {\mathbf {k}}_T^2,\mu ^2) d{\mathbf {k}}_T^2 = xa(x,\mu ^2), \end{aligned}$$

(13)

where $a = q$ or g and $xa(x,\mu ^2)$ are the conventional parton density functions (PDFs). The PB equations can be solved numerically by an iterative Monte-Carlo method with the leading order (LO) or next-to-leading order (NLO) accuracy. The solution results in a steep decline of the parton densities at ${\mathbf {k}}_T^2 > \mu ^2$. It contrasts the CCFM evolution, where the transverse momentum is allowed to be larger than the scale $\mu ^2$, corresponding to an effective taking into account higher-order contributions.²

2.5 Kimber–Martin–Ryskin approach

The Kimber-Martin-Ryskin (KMR) approach [42, 43] provides a technique to construct TMD gluon and quark densities from conventional ones by loosing the DGLAP strong ordering condition at the last evolution step, that results in $k_T$ dependence of the parton distributions. This procedure is believed to take into account effectively the major part of next-to-leading logarithmic (NLL) terms $\alpha _s (\alpha _s \ln \mu ^2)^{n-1}$ compared to the LLA, where terms proportional to $\alpha _s^n \ln ^n \mu ^2$ are taken into account.

At the LO, the KMR method, defined for ${\mathbf {k}}_T^2 \ge \mu _0^2 \sim 1$ GeV$^2$, results in expressions for TMD quark and gluon distributions [42, 43]:

$$\begin{aligned}&\displaystyle f_q(x, {\mathbf {k}}_T^2,\mu ^2) = T_q({\mathbf {k}}_T^2,\mu ^2)\frac{\alpha _s({\mathbf {k}}_T^2)}{2\pi }\nonumber \\&\quad \times \displaystyle \int \limits _x^1dz\left[ P_{qq}^\mathrm{LO}(z)\frac{x}{z}q\left( \frac{x}{z},{\mathbf {k}}_T^2\right) \Theta \left( \Delta -z\right) +P_{qg}^\mathrm{LO}(z)\frac{x}{z}g\left( \frac{x}{z},{\mathbf {k}}_T^2\right) \right] ,\nonumber \\ \end{aligned}$$

(14)

$$\begin{aligned}&\displaystyle f_g(x, {\mathbf {k}}_T^2,\mu ^2) = T_g({\mathbf {k}}_T^2,\mu ^2)\frac{\alpha _s({\mathbf {k}}_T^2)}{2\pi }\nonumber \\&\quad \times \displaystyle \int \limits _x^1dz\left[ \sum _qP_{gq}^\mathrm{LO}(z)\frac{x}{z}q\left( \frac{x}{z},{\mathbf {k}}_T^2\right) +P_{gg}^\mathrm{LO}(z)\frac{x}{z}g\left( \frac{x}{z},\mathbf{k}_T^2\right) \Theta \left( \Delta -z\right) \right] ,\nonumber \\ \end{aligned}$$

(15)

where $P_{ab}^\mathrm{LO}(z)$ are the usual DGLAP splitting functions at LO and $\mu _0^2$ is the minimum scale for which DGLAP evolution is valid. The theta functions introduce the specific ordering conditions in the last evolution step, thus regulating the soft gluon singularities. The cut-off parameter $\Delta$ usually has one of two forms, $\Delta = \mu /(\mu + |{\mathbf {k}}_T|)$ or $\Delta = |{\mathbf {k}}_T|/\mu$, that reflects the angular or strong ordering conditions, respectively. In the case of angular ordering, the parton densities are extended into the ${\mathbf {k}}_T^2 > \mu ^2$ region, whereas the strong ordering condition leads to a steep drop of the parton distributions beyond the scale $\mu ^2$. At low ${\mathbf {k}}_T^2 < \mu _0^2$ the behaviour of the TMD parton densities has to be modelled [42, 43]. Usually it is assumed to be flat under strong normalization condition (9).

The Sudakov form factors allow one to include logarithmic virtual (loop) corrections, they take the form:

$$\begin{aligned} T_q({\mathbf {k}}_T^2,\mu ^2)= & {} \exp \left[ -\int \limits _{{\mathbf {k}}_T^2}^{\mu ^2} \frac{d{\mathbf {q}}_T^2}{{\mathbf {q}}_T^2}\frac{\alpha _s({\mathbf {q}}_T^2)}{2\pi } \int \limits _0^{z_\text {max}}d\zeta \,P_{qq}^\text {LO}(\zeta )\right] , \end{aligned}$$

(16)

$$\begin{aligned} T_g({\mathbf {k}}_T^2,\mu ^2)= & {} \exp \left[ -\int \limits _{{\mathbf {k}}_T^2}^{\mu ^2} \frac{d{\mathbf {q}}_T^2}{{\mathbf {q}}_T^2}\frac{\alpha _s({\mathbf {q}}_T^2)}{2\pi }\right. \nonumber \\&\quad \times \left. \left( \int \limits _{z_\text {min}}^{z_\text {max}}d\zeta \,\zeta P_{gg}^\text {LO}(\zeta ) +n_f\int \limits _0^1d\zeta \,P_{gq}^\text {LO}(\zeta )\right) \right] , \end{aligned}$$

(17)

with $z_\text {max}=1-z_\text {min}=\mu /(\mu +|{\mathbf {q}}_T|)$. These form factors give the probability of evolving from a scale ${\mathbf {k}}_T^2$ to a scale $\mu ^2$ without parton emission. At the NLO, the TMD parton densities can be written as [40]:

$$\begin{aligned}&f_a(x,{\mathbf {k}}_T^2,\mu ^2)=\int \limits _0^1dz\,T_a({\mathbf {p}}_T^2,\mu ^2) \frac{\alpha _s({\mathbf {p}}_T^2)}{2\pi }\nonumber \\&\quad \times \sum _{b=q,g}P_{ab}^\text {NLO}(z)\frac{x}{z}b\left( \frac{x}{z},{\mathbf {p}}_T^2\right) \Theta (\Delta - z), \end{aligned}$$

(18)

where ${\mathbf {p}}_T^2={\mathbf {k}}_T^2/(1-z)$. Note that both DGLAP splitting functions and conventional parton distributions should be taken with NLO accuracy. The Sudakov form factors at NLO read:

$$\begin{aligned} T_q({\mathbf {k}}_T^2,\mu ^2)= & {} \exp \left[ -\int \limits _{{\mathbf {k}}_T^2}^{\mu ^2} \frac{d{\mathbf {q}}_T^2}{{\mathbf {q}}_T^2}\frac{\alpha _s({\mathbf {q}}_T^2)}{2\pi } \int \limits _0^1d\zeta \,\zeta \right. \nonumber \\&\quad \times \left. (P_{qq}^\text {NLO}(\zeta ) +P_{gq}^\text {NLO}(\zeta )) \right] , \end{aligned}$$

(19)

$$\begin{aligned} T_g({\mathbf {k}}_T^2,\mu ^2)= & {} \exp \left[ -\int \limits _{{\mathbf {k}}_T^2}^{\mu ^2} \frac{d{\mathbf {q}}_T^2}{{\mathbf {q}}_T^2}\frac{\alpha _s({\mathbf {q}}_T^2)}{2\pi } \int \limits _0^1d\zeta \,\zeta \right. \nonumber \\&\quad \times \left. (P_{gg}^\text {NLO}(\zeta )+2n_fP_{qg}^\text {NLO}(\zeta )) \right] . \end{aligned}$$

(20)

However, it was demonstrated that the NLO prescription, with a good accuracy, can be significantly simplified to keep only the LO splitting functions [44] while the main effect is related to the Sudakov form factors.

2.6 Flux factor

The choice of the flux factor is another peculiarity of off-shell calculations. The definition of the flux, which is the velocity of an off-shell particle, is highly disputable and is not clear. By default, we accepted the analytic continuation of the general textbook definition [36]:

$$\begin{aligned} F = 2 \lambda ^{1/2}(\hat{s}, k_1^2, k_2^2). \end{aligned}$$

(21)

Our choice is supported by a numerical experiment [45], where we have considered the production of $\chi _{cJ}$ states in a two photon process, $e + e\rightarrow \chi _{cJ} + e'{+}e'$ and made a comparison between the prompt calculation of this $2\rightarrow 3$ process and calculation based on EPA, $\gamma + \gamma \rightarrow \chi _{cJ}$ with $J = 0$, 1 or 2. We find that the flux taken in the form (21) provides a sensibly better fit to the exact calcualtion. The fact that the exact calculation disagrees with the factorized (collinear) calculation indicates that the conditions for the factorization theorem are yet not fulfilled. In such a situation, our choice of the flux can be regarded as a phenomenological correction for non-factorizable contributions. The same definition of the flux is adopted, for example, in [26]. However, the user can optionally choose the conventional definition $F = 2 x_1 x_2 s$, as it is explained below.

Fig. 1

pegasus main window. Here one can select factorization scheme (TMD or collinear one) for each of the colliding particles, choose corresponding parton density function and set the parameters, important for further Monte-Carlo simulation: number of iterations and number of simulated events per iteration

3 Calculations using PEGASUS

pegasus has an intuitive and extremely user friendly interface. The calcualtions using pegasus include a few general steps common for all of the processes. So, when pegasus is running, one can select the colliding particles, pp or $p\bar{p}$, and set their center-of-mass energy $\sqrt{s}$. The default setting corresponds to the LHC Run II setup. Then one can select factorization scheme (TMD or collinear one) for each of the colliding particles, choose corresponding parton density function and set the parameters, important for further Monte-Carlo simulation, namely, number of iterations and number of simulated events per iteration (see Fig. 1). Next steps could be as follows (note that all these steps do not depend on each other and can be done in different order):

• From the list of available processes one can select the necessary process and then (optionally) correct the default kinematical restrictions, hard scales, list of requested observables and corresponding binnings (see Figs. 2, 3, 4). This can be done by double clicking on the requested process or via main menu (using Edit $\rightarrow$ Task option).

• For each of the observables one can manually edit the default binning according to own wishes. As another option, the binning can be uploaded immediately from the data file. Several commonly used formats (such as .yoda, .yaml, .csv or plain data format, compatible with gnuplot [46] tool) as provided by HepData repository [47] are supported.

• The user-defined setup for any process (total center-of-mass energy, selected parton densities, kinematical restrictions, binnings etc) can be saved to a configuration file in some internal format (*.pegasus). This can be done via the main menu (using File $\rightarrow$ Save or File $\rightarrow$ Save As options) or via the popup menu available on right mouse button click or via appropriate button in the button panel. Of course, the configuration file can be loaded and a user-defined setup can be used in further applications. This can be done via main menu (with File $\rightarrow$ Open option) or via popup menu or via Open button on the button panel.

• Weighted or unweighted events can be generated. This option is available via main menu Edit $\rightarrow$ Settings $\rightarrow$ Generated events or via popup menu.

• If one needs to generate the Les Houches Event file [48], one has to mark corresponding option before the calculation starts (see Fig. 1). Note that this option affects the speed of the calculations.

• The calculation will start by choosing the corresponding option in main menu (Calculation $\rightarrow$ Start), popup menu or pressing Start button on the button panel. The numerical results for requested observables will be immediately presented “on the fly” with built-in tool pegasus plotter (see Fig. 5). The calculations can be paused or even stopped (using main menu options Calculation $\rightarrow$ Pause, Calculation $\rightarrow$ Stop, corresponding buttons on the button panel or options in popup menu). Of course, during pause in the calculations, all manipulations with accumulated results in pegasus plotter are allowed (see Sect. 4.3).

• If there are several contributing subprocesses, there is a possibility to immediately jump to the next one (via Calculation $\rightarrow$ Next option in main menu or appropriate button on button panel or popup menu) during the calculations.

Fig. 2

One can optionally correct the default kinematical restrictions, list of requested observables and corresponding binnings for any processes (part 1)

Fig. 3

One can optionally correct the default kinematical restrictions, list of requested observables and corresponding binnings for any processes (part 2)

Fig. 4

One can optionally correct the default kinematical restrictions, list of requested observables and corresponding binnings for any processes (part 3)

The generated events can be accumulated in Les Houches Event (*.lhe) file and/or presented in pegasus plotter. Using the latter, one can save the results in a some internal format (*.pplot) or as a simple plain data (compatible, for example, with gnuplot package) or export them to an image (*.pdf, *.png, *.jpg or *.bmp).

Below we give a more detailed information and explanations about the important features of pegasus.

3.1 Parton density functions in a proton

Latest sets [37] of CCFM-evolved TMD gluon distributions in a proton, JH’2013 set 1 and JH’2013 set 2, are available in the pegasus. The input parameters of JH’2013 set 1 were determined from the fit to high precision HERA data on the proton structure function $F_2(x,Q^2)$, whereas the parameters of JH’2013 set 2 gluon were extracted from combined fit on both $F_2(x,Q^2)$ and $F_2^c(x,Q^2)$ data (see [37]). The previous CCFM fits, namely, A0 and B0 sets [49], are available also and comparison between them can be found [37]. Technically, all these CCFM-evolved gluon densities are stored on a grid in $\log x$, $\log k_T$ and $\log \mu$ and a simple linear interpolation is applied to evaluated the gluon density for values in between the grid points. This interpolation proceeds automatically at the each event generation. The data files containing the grid points are supplied with the program package and read in at the beginning of each requested calculation.³

The TMD gluon and quark densities can be also evaluated in the standard DGLAP scenario using the PB and/or KMR schemes (with LO or NLO accuracy). As an input for the KMR procedure, the conventional (collinear) PDFs have to be applied. Several sets of KMR and PB-based gluon densities are currently available in pegasus. So, well known NNPDF3.1 (LO) [51] and MMHT’2014 (LO) [30] parametrizations and recent analytical expressions obtained [52,53,54] in the so-called generalized double asymptotic scaling (DAS) approximation of QCD [53, 54] were used as an input. The DAS approximation is connected to the asymptotic behaviour of the DGLAP evolution discovered many years ago [55]. Flat initial conditions for the DGLAP equations, applied in the generalized DAS scheme, lead to the Bessel-like behaviour for the proton PDFs at small x [53, 54]. The DAS LO set 1 corresponds to “frozen” treatment of the QCD strong coupling in the infrared region: $\alpha _s(\mu ^2) \rightarrow \alpha _s(\mu ^2 + m_\rho ^2)$. The DAS LO set 2 is based on the idea [56, 57] regarding the analyticity of the strong coupling at low scales. The difference between these two choices is discussed [58]. Everywhere, the cut-off parameter $\Delta$ is taken according to angular ordering condition.

Table 1 The TMD gluon densities in a proton implemented into the pegasus. The A0±, B0±, JH’2013 set 1± and JH’2013 set 2± distributions, needed to estimate the scale uncertainties of the calculations (see below), are not shown

The available TMD gluon sets with the essential parameters are listed in Table 1. We note that large variety of the TMD gluon distribution functions in a proton are collected in the tmdlib package [27], which is a C++ library providing a framework and an interface to the different parametrizations.

To perform the calculations in the collinear QCD factorization (mainly at LO or tree-level NLO for some processes) several sets of conventional PDFs are available in pegasus. These are recent MMHT’2014 (LO and NLO) [30] and CT14 (LO and NLO) [59] ones and previous sets provided by CTEQ Collaboration (CTEQ’6.6) [60], MSTW’2008 (LO and NLO) [61] and GRV’94 (LO) [62]. The standalone C++ codes from MMHT [30] and CTEQ [31] groups are implemented into the pegasus code and corresponding data files containing the grid points are supplied with the program package.

Table 2 List of the available processes. Note that exact definitions of all kinematical variables can be found, for example, in corresponding references

3.2 Simulated processes

List of processes, currently available in the pegasus, is presented in Table 2. We would like to clarify some points, which are not mentioned in the Table 2:

• Q denotes a heavy (c or b) quark, $\mathcal{Q}$ denotes $B_c$, $B_c^{(*)}$, $J/\psi$, $\psi ^\prime$, $\Upsilon (3S)$, $\chi _{cJ}(1P)$ or $\chi _{bJ}(3P)$ mesons with $J = 0$, 1 or 2, V stands for $\gamma$ or $Z/\gamma ^*$ and $l = e$ or $\mu$.

• The standard spectroscopic notation $^{(2S+1)}L_J^{(a)}$ is used for intermediate Fock state of heavy quark pair $Q\bar{Q}$ produced with spin S, orbital angular momentum L, total angular momentum J and color representation a.

• Besides the scales, listed in the Table 2, for every process some universal scales are available, namely: total energy of the partonic subprocess $\sqrt{\hat{s}}$, also $\sqrt{\hat{s}/4}$ and so-called CCFM scale $\sqrt{\hat{s}+\mathbf {Q}_T^2}$ [37, 49], where $\mathbf {Q}_T$ is the total tranverse momentum of the final partons, see Fig. 3.

• To estimate the scale uncertainties, the hard scales above can be varied around its default value by a factor of 2 or 1/2, as it often done in the pQCD calculations. This applies to any scale, except the CCFM scale. For CCFM-based gluon densities the scale uncertainties are evaluated by a change of the default gluon distribution to so-called “+” and “–” ones of the corresponding set [37, 49].

• Part of the non-logarithmic loop corrections to effective $g^* + g^* \rightarrow H^0$ vertex can be absorbed in the special K-factor [70] and optionally implemented into the calculations. As default choice, this K-factor is switched off.

• According to experimental setup, an isolation criterion is applied for prompt photon production. This criterion is the following: a photon is isolated if the amount of hadronic transverse energy $E_T^\mathrm{had}$ deposited inside a cone with aperture R centered around the photon direction in the pseudo-rapidity and azimuthal angle plane, is smaller than some value $E_T^\mathrm{max}$ (“cone isolation”). The isolation requirement significantly (up to $\sim 10$% of the visible cross section) reduces contribution from the so-called photon fragmentation mechanisms, not implemented into the pegasus. The isolation criterion and additional conditions which preserve our calculations from divergences have been specially discussed, for example, in [71] (see also references therein). The default values $R = 0.4$ and $E_T^\mathrm{max} = 4$ GeV can be changed optionally.

• At present, quark-initiated subprocesses can be calculated only within collinear QCD factorization and no TMD quark densities are implemented into the current version of pegasus. The QCD Compton subprocess is available only, if collinear factorization has been chosen, since in the $k_T$-factorization approach its contribution is taken into account by the off-shell gluon-gluon fusion (see [68, 69] for more details).

3.3 Quarkonium final states

Quarkonium production processes need additional explanations as they contain an important extra step: the formation of bound states.

The process starts with the production of a heavy quark-antiquark pair $Q \bar{Q}$ in a hard parton interaction. The produced quark pair may be either color singlet or color octet. If the $Q \bar{Q}$ state is color singlet, it can immediately convert into a meson with appropriate quantum numbers. Then the formation probability is determined by a single parameter, the radial wave function at the origin of the coordinate space, $|\mathcal{R}_S(0)|^2$ or $|\mathcal{R}'_P(0)|^2$ [72,73,74,75,76]. The values of these functions can be extracted from the measured decay widths or calculated within potential models.

The situation with color-octet states is more complicated as the transition to a color-singlet physical hadron requires the emission of extra (soft) gluons. Then, for every final state hadron h and for every intermediate $Q \bar{Q}$ state $n = \,^{2S+1}L_J$ listed in Table 2 there is a specific phenomenological long-distance matrix element (LDME) [77,78,79,80] responsible for such a transition $\langle \mathcal{O}^{h} \left[ n\right] \rangle$. Eventually, the production cross section for a hadron h in pp collisions is given by a sum over all possible singlet and octet $Q\bar{Q}$ states:

$$\begin{aligned} \sigma (pp\rightarrow h + X) = \sum _{n} \sigma \left( pp\rightarrow Q\bar{Q}\left[ n\right] \right) \langle \mathcal{O}^{h}\left[ n\right] \rangle , \end{aligned}$$

(22)

where $\sigma \left( pp\rightarrow Q\bar{Q}\left[ n\right] \right)$ is the partial partonic cross section (1) for a $Q\bar{Q}$ state n. The different states n are selected by introducing the proper projection operators in the hard scattering amplitude. The correspondence between the color singlet and color octet wave functions and respective LDMEs is given by the $\langle \mathcal{O}^{h}\left[ \,^{2S + 1}L_{J}\right] \rangle = 2N_c(2J+1)|\mathcal{R}_{S}(0)|^2/{4\pi }$ and $\langle \mathcal{O}^{h}\left[ \,^{2S + 1}L_{J}\right] \rangle = 6N_c(2J+1)|\mathcal{R}_{P}^\prime (0)|^2/{4\pi }$, respectively.

As default choice to describe the spin structure of relevant transition amplitudes, pegasus uses the model [81], where the NRQCD emission of soft gluons is considered in terms of classical multipole radiation theory. The multipole expansion is dominated by (chromo)electric dipole transitions E1. According to [81], only a single E1 transition is needed to transform a P-wave state into an S-wave state and the structure of the respective ${^3P_J^{(8)}}\rightarrow {^3S_1^{(1)}} + g$ amplitudes is taken the same as for radiative decays of $\chi _{cJ}$ mesons [82, 83]:

$$\begin{aligned}&\mathcal{A}(\,^3P_0^{(8)} \rightarrow \, ^3S_1^{(1)} + g) \sim k_\mu \, p^\mu \, \epsilon _\nu (l) \epsilon ^\nu (k), \end{aligned}$$

(23)

$$\begin{aligned}&\mathcal{A}(\,^3P_1^{(8)} \rightarrow \, ^3S_1^{(1)} + g) \sim e^{\mu \nu \alpha \beta } k_\mu \, \epsilon _\nu (p) \, \epsilon _\alpha (l) \epsilon _\beta (k), \end{aligned}$$

(24)

$$\begin{aligned}&\mathcal{A}(\,^3P_2^{(8)} \rightarrow \, ^3S_1^{(1)} + g) \sim p^\mu \, \epsilon ^{\alpha \beta }(p) \, \epsilon _\alpha (l)\nonumber \\&\quad [ k_\mu \epsilon _\beta (k) - k_\beta \epsilon _\mu (k) ], \end{aligned}$$

(25)

where p, k and $l = p - k$ are the four-momenta of the color-octet P-wave state, emitted gluon and produced color-singlet S-wave state, $\epsilon ^\mu (k)$, $\epsilon ^\mu (l)$, $\epsilon ^\mu (p)$ and $\epsilon ^{\mu \nu }(p)$ are the polarization vectors (tensor) of respective particles and $e^{\mu \nu \alpha \beta }$ is the fully antisymmetric Levi–Civita tensor. The transformation of an S-wave state into another S-wave state (such as $J/\psi$ or $\psi ^\prime$ meson) is treated as two successive E1 transitions $^3S_1^{(8)}\rightarrow \,^3P_J^{(8)}+g$, $^3P_J^{(8)}\rightarrow \,^3S_1^{(1)} + g$ proceeding via either of the three intermediate states: $^3P_0^{(8)}$, $^3P_1^{(8)}$, or $^3P_2^{(8)}$. For each of the two transitions the same effective coupling vertices (24)–(25) are exploited. In the case of $J/\psi$ or $\Upsilon (3S)$ production, the user can optionally include feed-down from the decays of upper quarkonium states ($\psi ^\prime$, $\chi _{cJ}(1P)$ or $\chi _{bJ}(3P)$, respectively) in addition to the direct production channels.

The absolute normalization of the transition amplitudes is not calculable within the theory; these numbers are taken as free adjustable parameters. However, the values of the LDMEs for the different partial contributions are not completely independent but are connected by the heavy quark spin symmetry (HQSS) relations [79, 80]. All the HQSS relations between LDMEs are implemented in the pegasus default setting, taken from [65, 66].

3.4 Strong coupling and masses of particles

In pegasus, the strong coupling $\alpha _s$ can be calculated in one-loop or two-loop approximation with respect to the number of active flavors $N_f$ and $\Lambda _\mathrm{QCD}$. The choice of $N_f$ and $\Lambda _\mathrm{QCD}$ is done automatically (according to the Table 1) with the choice of the TMD and/or conventional parton density in a proton. There is no possibility to change it manually since this setup is essential for determination of corresponding parton distributions.

The masses of all particles (quarks, gauge bosons, heavy quarkonia etc), their branching ratios and decay widths are fixed according to Particle Data Group (PDG) [84]. Any of these parameters can be easily changed using the convenient built-in particle data tool (see Fig. 5), which is available via main menu (Edit $\rightarrow$ Settings $\rightarrow$ Particle data) or popup menu or appropriate button on the button panel.

Fig. 5

Particle data tool can be launched from pegasus main window

3.5 Generation of Les Houches Event file

pegasus is supplied with a tool to construct event files in the Les Houches Event format [48]. This is a widely accepted format to present events, which is compatible with the majority of modern general purpose Monte-Carlo generators.

The Les Houche Event (LHE) file, generated by the pegasus, consists of two main blocks: the first one contains the information about the number of the recorded events, the PDFs used, the colliding hadrons and their energies. Also the total cross section is shown. The second block represents a list of events, including the data on the interacting partons, their 4-momenta and color structure of the event. We mention the basic features of the LHE file, generated by the pegasus:

• The generated events could be weighted or unweighted. In first case, the sum of all the weights is the total cross section of the subprocess.

• Polarization information is not preserved.

• A parton carries a tag according to the standard PDG numbering scheme [84].

• Conventional (collinear) parton densities in a proton are numbered according to the lhapdf scheme [85] while TMD parton distributions are numbered according to the tmdlib package [27].

The produced LHE file can then be processed with an external program to introduce some peculiar event selection, to include parton showers, to hadronize the final particles, etc. It is found to be compatible with such Monte Carlo generators as pythia [16] and cascade [24, 25].

4 Program components

4.1 Random number generator

Since all the internal variables in pegasus are declared as double precision ones, double precision random numbers have to be generated in the Monte-Carlo simulations. The random number generator ranlux [86] is well suited for these purposes. It has a long period, solid theoretical foundations and is commonly used in computational physics. This random number generator is implemented into the pegasus.

Fig. 6

Results of the calculations presented by pegasus plotter: open $b\bar{b}$ production in pp collisions at $\sqrt{s} = 13$ TeV. No kinematical cuts are applied

Fig. 7

Results of the calculations presented by pegasus plotter: inclusive Higgs production (in $W^+W^-$ decay mode) in pp collisions at $\sqrt{s} = 8$ TeV. The filled areas correspond to the scale uncertainties estimated for JH’2013 set 2 gluon density. Experimental data are from ATLAS Collaboration [87]. The kinematical cuts are exactly the same as described in ATLAS paper

4.2 Phase space integration and event generation

The multidimensional phase space integration (1) is performed with the Monte-Carlo technique and is incorporated with the routine vegas [29]. The routine vegas allows up to ten integration variables, that is enough for subprocesses considered in pegasus.

The vegas algorithm is based on a method for reducing statistical errors by using a known probability distribution function to concentrate the search in those areas of the integrand that make the greatest contribution to the final integral.

The algorithm is realised through a large number of random sample points distributed over a d-dimensional rectangular volume. The whole volume is divided into d-dimensional rectangular cells (by default, 50 divisions along each axis). The probability for a point to drop into a given cell is determined by so called sampling distribution, which is adjusted to the integrand function. The sampling distribution approximates the exact distribution by making a number of passes (iterations) over the integration region while histogramming the integrand function $d\sigma$ given by the expession (1). Each iteration is used to define a sampling distribution for the next iteration. To improve the convergence in the region of high $p_T$, the user can optionally modify the integrand function from $d\sigma$ to $(1 + p_T^4)d\sigma$, see Fig. 1. The optimization of the sample grid is made automatically and needs no care from the user.

Each sample point generated by vegas represents an event in the n-particle phase space with the coordinates of the sample point responding to the values of the physical integration variables ($p_{iT}$, $y_i$, $\phi _i$). The weight attributed to that event is given by the product of the integrand function $d\sigma$ and the d-volume of the sampling cell containing that point, $dw = d\sigma dV_\mathrm{cell}$. Unweighting algorithm for the generated events is provided also.

The typical time needed to generate one event, of course, depends on the requested subprocess; but, in general, is similar to time needed by other Monte-Carlo event generators like cascade or pythia. The output events can be plotted on a histogram (using built-in tool pegasus plotter ) or stored for further use in the form of an Les Houches Event file.

4.3 PEGASUS plotter

pegasus is supplied with a built-in tool pegasus plotter, allowing one to depict easily the produced differential cross sections and immediately compare them with experimental data. As a default setting, the accumulated results for requested observables during the calculation are shown in pegasus plotter. However, it is a quite independent tool and can be used apart from any calculations made within the pegasus. The program is very simple and intuitive. Let us briefly describe main features of the tool.

As one calls the pegasus plotter from the main menu of the pegasus (using the Tool $\rightarrow$ Plotter option, or via popup menu, or by pressing the corresponding button on button panel) an empty sheet is created. The following objects, stored in a plain data files, could be added to the sheet (by choosing Edit $\rightarrow$ Add option in the main menu or popup menu available with a right mouse button click on the sheet):

• Curve. The data file should consist of two columns, corresponding to the rows of x and y values.

• Histogram. The data file is the same, as for Curve. However, every y value should be mentioned twice, for the both borders of the corresponding bin.

• Filled area. A three-columns data file should contain for every x value lower and upper values of y.

• Text label. An arbitrary text note inside the plot sheet. Greek letters are available through the syntax {/Symbol letter}, where the letter is just the name of the greek symbol (for instance, alpha, sigma or other). Several capital greek symbols are available, namely, $\Upsilon$ ({/Symbol Upsilon}), $\Psi$ ({/Symbol Psi}) and $\Delta$ ({/Symbol Delta}). Subscripts and superscripts are available with a latex-like syntax _{subscript}, $\hat{\,}${superscript}.

• Experimental data. The data file should be in gnuplot-compatible format with 6 columns, corresponding to x, y, lower and upper x values and lower and upper y values. Alternatively, the data files in standard *.yoda or *.csv format (available from HepData repository [47]) can be uploaded.

As an object is added on the sheet, it can be selected with a left mouse button click and modified according to user own wishes either with a double click or with choosing option Edit $\rightarrow$ Plottable in the pegasus plotter main menu or via popup menu. Then the text label in the legend and appearance of the selected object (for example, color, font, size etc) can be changed. If selected object is a Histogram, the fiducial cross section (integral with respect to the x variable) is shown in the status bar. One can also set a factor to scale the depicted cross sections using Edit $\rightarrow$ Multiply by a factor option in main menu or popup menu.

The default axes setting can be changed from the main menu (Edit $\rightarrow$ Axes option) or by double clicking an axis. Besides the font, alignment and other setting one can also set the axes to be linear or logarithmic. From the main menu (Options $\rightarrow$ Plot size) or popup menu one can also adjust the size of the graph in pixels.

The plot can be saved for the future editing via main menu options File $\rightarrow$ Save or File $\rightarrow$ Save As or via popup menu in the internal format (*.pplot). The export to a gnuplot script is possible via main menu Export $\rightarrow$ Plot to Gnuplot script option or via popup menu. The figure can be also printed out or saved in *.png, *.jpg or *.bmp format. Finally, samples for all plotted curves, histograms or data point sets (or for only selected ones) can be transfered (using Options $\rightarrow$ Export) to a plain data file (which is compatible, for example, with gnuplot) for future usage in other programs.

Some typical snapshots of the pegasus plotter are presented on Figs. 6 and 7. So, here we illustrate the TMD effects in open beauty production at $\sqrt{s} = 8$ TeV (Fig. 6) and present some results for inclusive Higgs production (in $W^+W^-$ decay mode) compared with the ATLAS data [87] (Fig. 7). Note that in the latter case all the kinematical cuts applied and binnings are exactly the same as described in the ATLAS paper [87].

5 Installation and running

pegasus can be downloaded from https://theory.sinp.msu.ru/dokuwiki/doku.php/pegasus/download as a precompiled executive file for Linux machines. No special installation procedure is needed. However, please be sure that g++ and gfortran are already installed in your system (to be precise, libc.so.6, libgfortran.so.3 and libstdc++.so.6 are needed). The data files containing the necessary TMD parton densities in a proton (and conventional PDFs as well) are located inside the pegasus home directory (folder data). If there are some missing data files in data folder, pegasus will inform user about that. In this case, no calculation is allowed. Location of data folder could be easily changed via main menu option Edit $\rightarrow$ Settings $\rightarrow$ Path to data folder.

For Linux machines, the executive file can be just run from a terminal as ./PEGASUS. The program demands the qwt library (version 6.1.3) [28], so the library file libqwt.so.6 should be inside the pegasus home directory. Otherwise, the path to this file should be specified with export LD_LIBRARY_PATH=/path/to/library. If a long-time calculation is needed, one can run console version as ./cPEGASUS filename.pegasus with the user-defined setup saved to a configuration file filename.

pegasus.

The program was tested on ROSA Linux R8.1, ROSA Linux R11 and Ubuntu 16.04.