GR@PPA
GRace At Proton-Proton/Antiproton collisions

A GRACE -based event-generator framework for high energy hadron-collision interactions.

The generated events can be fed to a general-purpose event generator, PYTHIA  and HERWIG , to add initial- and final-state parton showers and the simulation of hadronization and decays.
The program has been developed as an activity of the NLO Working Group .

References
The reference to GR@PPA 2.9 is
S. Odaka, Y. Kurihara, GR@PPA 2.9: radiation matching for simulating photon production processes in hadron collisions, Comput. Phys. Commun. 232 (2018) 214; arXiv:1712.02132 [hep-ph].

The reference to GR@PPA 2.8 is
S. Odaka, Y. Kurihara, GR@PPA 2.8: initial-state jet matching for weak boson production processes at hadron collisions, Comput. Phys. Commun. 183 (2012) 1014; arXiv:1107.4467 [hep-ph],
and S. Odaka, GR@PPA 2.8.3 update, arXiv:1201.5702 [hep-ph]
for the updates.

For GR@PPA 2.7, please refer to
 S. Tsuno et al., GR@PPA 2.7 event generator for pp/ppbar collisions, Comput. Phys. Commun. 175 (2006) 665; hep-ph/0602213.
What's New
  • May 9, 2017: minor update of GR@PPA 2.9.
  • May 9, 2017: GR@PPA 2.8.6.2 update uploaded.
  • Feb. 10, 2017: GR@PPA 2.9 uploaded.
  • Jan. 20, 2017: GR@PPA 2.8.6.1 update uploaded.
  • Jan. 24, 2013: GR@PPA 2.8.4 update uploaded.
  • Dec. 27, 2011: GR@PPA 2.8.3 update released.
  • Jul. 19, 2011: GR@PPA 2.8.2 update released.
  • Apr. 27, 2011: GR@PPA 2.8.1 update released.
  • Nov. 17, 2010: GR@PPA 2.8 release.
  • Jun. 9, 2010: GR@PPA-2.8-rc3 was uploaded.
  • Jan. 18, 2010: a release-candidate of version 2.8 (GR@PPA-2.8-rc2) was uploaded.
  • Feb. 24, 2006: GR@PPA 2.76 release
Contents
  • GR@PPA 2.9: ME-PS matching for photon production processes
  • GR@PPA 2.8.6: the latest release of the GR@PPA 2.8 series (the jet matching has been extended to two jets for single weak-boson production)
  • GR@PPA 2.8: ME-PS matching of hadron-jet production in single and double weak-boson production processes
  • GR@PPA 2.7: the previous distribution including many multi-particle production processes
  • LhaExt: an interface to PYTHIA, HERWIG etc. using data files
  • GR@PPA_All: a package of GR@PPA event generators for various multi-body processes.
  • GR@PPA_4b: an event generator for the four-bottom quark production processes (the 1st product).
GR@PPA 2.9
The ME-PS matching method is applied to direct photon and diphoton production. The associated hadron-jet production is supported up to two jets as in GR@PPA 2.8.6. The collinear photon divergences are also regularized using the QED-LLL subtraction, and the PS simulation which restores the subtracted collinear components includes collinear photon radiation. The PS simulation is capable of enforcing the radiation of given number of energetic photons for efficient event generation.

The distribution package can be downloaded here. We provide sample programs for direct photon and diphoton production in 7-TeV proton-proton collisions. In these samples, the events of different subprocesses to be combined are separately generated. The generated events can be mixed when the PYTHIA simulation is applied. Such a separate generation is convenient because the generation condition and required CPU time are much different between the subprocesses.

This distribution also includes LhaExt 2.0.

References:
S. Odaka and Y. Kurihara, Consistent simulation of non-resonant diphoton production at hadron collisions with a custom-made parton shower, Phys. Rev. D 85, 114022 (2012); arXiv:1203.4038 [hep-ph]
S. Odaka and Y. Kurihara, Consistent simulation of direct-photon production in hadron collisions including associated two-jet production, Mod. Phys. Lett. A 31, 1650099 (2016); arXiv:1509.04813 [hep-ph]
S. Odaka and Y. Kurihara, Consistent simulation of nonresonant diphoton production in hadron collisions including associated jet production up to two jets, Phys. Rev. D 94, 114015 (2016); arXiv:1607.00204 [hep-ph]
GR@PPA 2.8.6
The matched jet production has been extended to two jets for single W and Z production. In addition to the collinear divergences, soft-gluon divergences have to be subtracted in order to make the two-jet production MEs finite. We have introduced a combined subtraction method to acomplish the subtraction of the two kinds of divergences simultaneously.

The distribution package can be downloaded here. We provide sample programs for W boson and Z boson production in 7-TeV proton-proton collisions. In these samples, W/Z + 0-jet, 1-jet, and 2-jet events are separately generated, and the generated events are mixed when the PYTHIA simulation is applied. Such a separate generation is convenient because the generation condition and required CPU time are much different for the three subprocesses.

This distribution includes LhaExt version 2.0, which supports the LHEF file format (*) for the event output.
(*) J. Alwall et al., A Standard format for Les Houches event files, Comput. Phys. Commun. 176, 300 (2007); arXiv:hep-ph/0609017

References:
S. Odaka, N. Watanabe and Y. Kurihara, ME–PS matching in the simulation of multi-jet production in hadron collisions using a subtraction
method, Prog. Theor. Exp. Phys. 2015, 53B04 (2015); arXiv:1409.3334 [hep-ph]
GR@PPA 2.8
A 0-jet/1-jet matching mechanism is implemented for the W and Z production processes and diboson (W+W-, ZW, ZZ) production processes. A gzipped tar file of the released package (GR@PPA-2.8.x) can be downloaded. Expand the downloaded file and move into the created directory.
    > tar zxf GR@PPA-2.8.x.tgz
    > cd GR@PPA-2.8.x
Instructions for the installation and the execution of sample programs can be found in the README file in the top directory.
Feedbacks are greatly appreciated.

References:
S. Odaka and Y. Kurihara, Initial-state parton shower kinematics for NLO event generators, Eur. Phys. J. C 51, 867 (2007); arXiv:hep-ph/0702138
S. Odaka, Simulation of Z boson pT spectrum at Tevatron by leading-order event generators, Mod. Phys. Lett. A 25, 3047 (2010); arXiv:0907.5056 [hep-ph]
S. Odaka, Y. Kurihara, GR@PPA 2.8: initial-state jet matching for weak boson production processes at hadron collisions, Comput. Phys. Commun. 183 (2012) 1014; arXiv:1107.4467 [hep-ph]
S. Odaka, GR@PPA 2.8.3 update, arXiv:1201.5702 [hep-ph]
S. Odaka, Simulation of Z-boson pT spectrum at LHC and Tevatron using GR@PPA, arXiv:1206.3398 [hep-ph]
S. Odaka, Precise simulation of the initial-state QCD activity associated with Z-boson production in hadron collisions, Mod. Phys. Lett. A 28, 1350098 (2013); arXiv:1301.5082 [hep-ph]

Updates:
2.8: official release (Nov. 17, 2010)
2.8.1: bug fix in parton shower routines (QCDPSb.f and pskini.f). In addition, the Q0 cutoff of parton showers was increased from 4.6 GeV to 5.0 GeV for safety. (Apr. 27, 2011)
2.8.2: the energy scale setting in the LLL subtraction was improved.(1) The usage of the random number generator was improved, and the random number generators themselves were replaced with more reliable ones.(2) (July 19, 2011)
2.8.3: the final-state PS kinematics was modified so that the memonta of spectator particles (e.g., weak bosons) should not be altered by the application of PS. The routine to set the QCD lambda value for PS was modified so that the derived alpha_s value should reproduce the value in PDF as precisely as possible even when there is a mismatch in the approximation order. (Dec. 27, 2011)
2.8.4: improvements established in the study of diphoton production(3), which are mainly concerned with the final-state PS, have been backported. The subroutines, scale_fsr and scale_fsub, have been added to grcpar.F of sample programs in order to define the energy scales for the final-state PS and the final-state LLL subtraction, respectively. From this update, the sample programs utilizing RBOOK can be produced from those utilizing HBOOK by executing the ./Config script in the relevant directory. (Jan. 24, 2013)

(1) It is better to take the factorization scale of the non-radiative subsystem as the energy scale in the LLL subtraction in order to achieve good matching between the ME and PS for hard radiations. Since the update 2.8.2, we provide the subroutine setscale in grcpar.F of sample programs for defining the renormalization and factorization scales, so that an identical definition can be refered to from both PDF/PS routines in non-radiative processes and LLL subtraction routines in radiative processes. In order to have this scheme work properly, we have to set the parameters ICOUP and IFACT in the subroutine GRCPAR in grcpar.F to be equal to 6 in all processes.
(2) The performance of the random number generators, DRN in BASES/SPRING and QPRAND in QCDPS, was found to be unsatisfactory for the present use in GR@PPA. These routines have been modified so that they call routines in mt19937.f and randgen.f, respectively.
(3) S. Odaka and Y. Kurihara, Consistent simulation of non-resonant diphoton production at hadron collisions with a custom-made parton shower, Phys. Rev. D 85, 114022 (2012); arXiv:1203.4038.
GR@PPA 2.7

Several multi-jet processes have been added to the previous GR@PPA_All distribution. New processes are
  • W + 4 jets,
  • Z + 3 jets and 4 jets,
  • di-boson (WW, WZ and ZZ) + 1 jet,
  • top-quark pair (6 body) + 1 jet,
  • QCD 2 jets, 3 jets and 4 jets.
Namely, processes up to seven-body productions (top-quark pair + 1 jet) can be simulated, based on ordinary Feynman diagram calculations at the tree level.

In this version, the GR@PPA framework and the process dependent matrix-element routines are separately provided. This makes it easier to add further new processes, and allows users to make a choice of processes to implement.

This version has several new features to handle complicated multi-body production processes. A systematic way to combine many subprocesses to a single base-subprocess has been introduced, and a new method has been adopted to calculate the color factors of complicated QCD processes. They speed up the calculation significantly.

Manual: S. Tsuno et al., GR@PPA 2.7 event generator for pp/ppbar collisions, Comput. Phys. Commun. 175, 665 (2006); hep-ph/0602213

Download:

Installation:

The following shows the instruction to setup the GR@PPA framework version 2.76 with the W + 1 jet and W + 2 jets matrix elements, and execute one of the example programs. The example programs generate 100 W + 1 jet events using the built-in CTEQ6L PDF. Edit the file inc/define.h beforehand in order to use an external PDF library (PDFLIB or LHAPDF). See the manual for more details.
  1. Place the downloaded tar files in a certain directory, and cd to it.
  2. tar zxvf GR@PPA-2.76.tgz
  3. cd GR@PPA-2.76
  4. tar zxvf ../matrix_w1j_v1.03.tgz
  5. tar zxvf ../matrix_w2j_v1.03.tgz
  6. ./Config.perl
  7. Edit the Makefile to setup the compiler and paths to the libraries. Example programs require some external libraries, depending on the choice of the user. Users can give their paths later by editting the Makefile to build the example program (before the step 15).
  8. make w1j
  9. make w2j
  10. make integ
  11. make kinem
  12. make install
  13. make example
  14. cd example/pythia
  15. make
  16. ./pysample

How to add matrix elements:

Assuming the downloaded file (matrix_w0j_v1.03.tgz for instance) is at the same place as the above, and the current directory is GR@PPA-2.76, do as
  1. tar zxvf ../matrix_w0j_v1.03.tgz
  2. ./Config.perl
  3. Edit the Makefile again.
  4. make w0j
  5. make integ
  6. make kinem
  7. make install
  8. make example
Edit the subroutine upinit.F in a sample-program directory as IPRUP(1) = 100, and do make there. Then, you will have an example program to generate W + 0 jet events.

See also another GR@PPA page by S. Tsuno.

LhaExt
an interface using external event data files from GR@PPA to PYTHIA, HERWIG and any other general-purpose event generators supporting the Les Houches Accord (LHA) event interface [1].

Since the event generators besed on the GR@PPA framework (e.g., GR@PPA_All) directly generate unweighted events, they can be easily enbedded in general-purpose event generators such as PYTHIA and HERWIG. The embedding uses are convenient in quick analyses where input physical parameters and/or kinematical cuts are frequently changed. However, in some environments (e.g., a mass production of events), it is more favourable to separate the jobs for the event generation by GR@PPA and those for parton showers, hadronisation, decays etc. by general-purpose generators. Generated parton-level event data are to be passed by using external data files in such uses. The LhaExt package has been made as a simple example for such uses.

Program download: questions, comments and bug reports should be sent to S. Odaka
The routines in LhaExt simply write/read the whole contents of the LHA interface commons, HEPRUP and HEPEUP, to/from a data file. They do not dedicate to GR@PPA generators, but are universal for any event generators supporting the LHA event interface in which the two interface commons are properly filled. It is very easy to implement these routines since they do not depend on any specific generator. The package is composed of "write" routines and "read" routines. Of course, "write" routines are to be used in pre-generators such as GR@PPA_All, and "read" routines in post-generators such as PYTHIA. There are two kinds of "write" routines. One is to write the run information in HEPRUP, and the other to write the event data in HEPEUP. The former is to be called once in each run after the initialisation is completed, while the latter must be called every after an event is generated. The created data file is composed of a header where the run information is recorded, and event data following it. Both ASCII-formatted and unformatted binary data can be created according to the users' choice. An example for the usage in GR@PPA_All is provided in the package.

In addition to simple "read" routines for the header (run information) and the event data, we provide some utility routines in order to realize the following features:
  • Multiple input data files are supported. The present LhaExt supports a sequential read only, though some parallel read (event mixing) schemes are specified in the Les Houches Accord.
  • The read process can skip a certain number of events at the beginning.
  • Users can choose any unweighting scheme specified in the Les Houches Accord. It can be different from the scheme determined in the "write" procedure.
  • Users can choose LUNs (Logical Unit Numbers) for the control file and the data file. They can choose an automatic assignment, as well.
An example of the usage is provided as the subroutines UPINIT and UPEVNT in the package. The above fratures become available if one replaces the dummy routines of the same names in PYTHIA or HERWIG with these examples. See the README file in the package for more details.

[1] E. Boos et al., hep-ph/0109068; see also p. 226 in the PYTHIA 6.2 manual, hep-ph/0010017.

GR@PPA_All
an event generator program package for proton-proton and proton-antiproton collider experiments, such as those at Tevatron and LHC. Calculations are all at the tree level (leading order) within the framework of the minimal Standard Model. The most recent version of GR@PPA_All supports processes to produce following final states:
  • W + jets (up to 3 jets) with the subsequent W decay to a fermion pair,
  • Z + jets (up to 2 jets) with the subsequent Z decay to a fermion pair,
  • four bottom quarks via Z and Higgs-boson mediated processes as well as those from pure QCD interactions (same as GR@PPA_4b),
  • top-quark pair with the subsequent decay to W and b, and the W decay to a fermion pair,
  • di-boson (WW, WZ and ZZ) with the subsequent W/Z decay to a fermion pair.
Note that matrix elements are evaluated for Feynman diagrams including heavy particle (W, Z and top quark) decays down to light partons (bottom quarks or lighter). Thus, we can expect that phase-space effects and decay correlations due to quantum effects are exactly reproduced. For instance, the former alter the resonance shape of W, Z and top quarks, and the latter generate a decay plane correlation in di-boson events.

The program is coded within the framework of GR@PPA, an extention of the GRACE system to hadron collisions. Events are generated by BASES/SPRING included in the GRACE system. Thus, generated events are already unweighted (i.e., event weight = 1).

GR@PPA_All generates events at the parton level. Users have to feed the generated events to a suitable general-purpose event generator, if they want to have hadron-level realistic events.The present version of GR@PPA_All supports the LHA event interface [1]. Therefore, the program can be easily interfaced to widely-used general-purpose event genetators, PYTHIA 6.2 and HERWIG 6.5, which support the LHA event interface, too. Since unweighted events are directly generated, GR@PPA_All can be embedded in these general-purpose event generators. Of course, a stand-alone use is also possible. The distribution package includes aample programs for these uses.

As for the PDF library, the most popular ones, PDFLIB in CERNLIB and LHAPDF, are supported. PYTHIA built-in PDFs can be used as well when the PYTHIA-embedding mode is chosen.

Manual: An online manual is available. The concept and the basic structure of the program are same as those of GR@PPA_4b. See the GR@PPA_4b manual for the details of GR@PPA.

Program download: questions, comments and bug reports should be sent to S. Tsuno or S. Odaka .
  • version 2.65 (gzipped tar file, 1.3 MB): the first release; 13 February, 2004
Caution: The support to the LHAPDF PDF library is still preliminary in the version 2.65. The calculations are unstable on Linux PCs with the GNU g77 compiler in the combination with LHAPDF. The integrated cross sections show differences at the 4th or 5th digit from those evaluated in other environments in many processes, and the "W + 3 jets" generator gives an anomalously large cross section and error. No such problem has been found in other environments: on the same platfoem with Intel and Fujitsu compilers, and on an AIX server with an IBM compiler (xlf). This problem will be solved in the next version, which we are now preparing for the release.

[1] E. Boos et al., hep-ph/0109068; see also p. 226 in the PYTHIA 6.2 manual, hep-ph/0010017.


GR@PPA_4b
an event generator for four bottom-quark production processes.

The four bottom-quark production is an important process for detecting Higgs bosons at hadron-collider experiments, if they have large couplings to bottom quarks, as in the large tan(beta) cases of MSSM. GR@PPA_4b can generate unweighted events from all the possible processes within the framework of the Standard Model, including the most dangerous QCD background as well as the Higgs-boson and Z-boson mediated processes. The event generation is based on exact matrix elements at the tree level (lowest order).

Manual: S. Tsuno et al., GR@PPA_4b: A Four Bottom Quark Production Event Generator for pp/ppbar Collisions, Comput. Phys. Commun. 151 (2003) 216; hep-ph/0204222; KEK Preprint 2002-7

Program download: questions, comments and bug reports should be sent to S. Tsuno or S. Odaka .
Note: the present stable version is 2.01, where the default is "embedding in PYTHIA 6.2xx with the use of PYTHIA built-in PDF library". HERWIG 6.5 embedding is also supported as an option. This has become possible because GR@PPA of this version supports the "Les Houches Acord external generator interface" [1], and both PYTHIA 6.2 and HERWIG 6.5 support it. We also provide a preliminary support of the "Les Houches Acord PDF" ( LHAPDF ) in this version, in addition to PYTHIA built-in PDFs and those in PDFLIB of CERNLIB .Refer to the README file in the top directory of the GR@PPA_4b distribution package to see how to choose these options. Refer to the GR@PPA_4b Manual for the usage of the program. There is no essential change in the functionality of the internal routines from previous versions. The PYTHIA 6.1 embedding is now treated as a non-standard option, though it is internally supported. We recommend that users should choose one of the previous versions (e.g ., version 1.06) if they need to use PYTHIA 6.1.

[1] Generic User Process Interface for Event Generators , E. Boos et al., Submitted to Workshop on Physics at TeV Colliders, Les Houches, France, 21 May - 1 Jun 2001; hep-ph/0109068; See also the PYTHIA 6.2 manual for practical details.

S. Odaka, 30 October 2018