Alpgen Interface to CMSSW

%COMPLETE5%

Introduction

Alpgen is a generator for hard multiparton processes in hadronic collisions. It produces matrix element (ME) level events which are consecutively passed to a parton shower (PS) / hadronization code (like Pythia or HERWIG) for further event development. Using the MLM ME/PS matching procedure, one can combine the matrix element calculations with parton showers while avoiding double-counting. This allows for the best Monte Carlo prediction of multi-jet final states at this moment.

To interface Alpgen to CMSSW and pass the events to Pythia, the AlpgenInterface package has been written. AlpgenInterface is a CMSSW package in the GeneratorInterface subsystem that allows the user to read in unweighted Alpgen events and generation parameters and save them in a standard format (Les Houches format) as CMSSW objects (LHEEventProduct and LHERunInfoProduct). It is also possible, through the use of the JetMatchingAlpgen module present in the PartonShowerVeto package, to perform the parton shower and hadronization steps from within CMSSW, writing a full-fledged edm::HepMCProduct in the event (edm::Event).

The set (AlpgenInterface + JetMatchingAlpgen code from PartonShowerVeto), refered hereafter as CMSSW Alpgen, is essentially equivalent to the AlpgenInterface package of the previous CMSSW versions (CMSSW 1_X_Y and 2_X_Y). It must be kept in mind, however, that CMSSW Alpgen only implements the very final step of Alpgen generation - format shift, showering, matching and hadronization. In order to use CMSSW Alpgen, the user must use the Alpgen standalone code to generate unweighted Alpgen events, which will be the input to CMSSW Alpgen. For more information on the intrincacies of Alpgen, please take a look at the FAQ. Also, we strongly encourage the user to look at the Alpgen documentation.

In general, the components of CMSSW Alpgen (AlpgenInterface and PartonShowerVeto packages) are integrated into a CMSSW release. The goals of this page are:

• To show the user how to use the standard CMSSW Alpgen as provided in the CMSSW release.
• To show the user how to checkout and compile the components of CMSSW Alpgen from source (not needed if you're running the version from the release).
• To show the user how to run the AlpgenInterface on a set of unweighted events produced by Alpgen.
• To show the user how to run the PartonShowerVeto package on a set of LHE Events produced by AlpgenInterface
• To provide answers to some Frequently Asked Questions.
• To provide an entry point for the CMSSW Alpgen documentation.

Generating the sample

The sample generation must be done with Alpgen standalone. See information on https://twiki.cern.ch/twiki/bin/view/Main/CmsAlpgen.

Using CMSSW Alpgen

Using the AlpgenInterface package

The AlpgenInterface package provides a facility to format shift the events produced by Alpgen standalone (unweighted events, UNW events for short) into CMSSW objects (LHEEventProduct). By the same token, the generation parameters (usually written in the file with suffix .unw) are made into a LHERunInfoProduct. This facility is implemented as a an EDSource, AlpgenSource, part of the AlpgenInterface package. If you want to use the standard AlpgenInterface provided in CMSSW, you must prepare a configuration file as described in the CMSSW configuration file language and use the AlpgenSource. The AlpgenSource has only one setting the following settings:

name	type	description	default
pythiaPylistVerbosity	untracked int32	Verbosity level of Pythia PYLIST calls	0
pythiaHepMCVerbosity	untracked bool	Verbosity for HepMC	false
maxEventsToPrint	untracked int32	Number of events to print, if verbose	1
fileNames	untracked vstring	Alpgen file names, minus the extensions	(Required)
PythiaParameters	edm::ParameterSet	(See below)	(See below)
GeneratorParameters	edm::ParameterSet	(See below)	(See below)

The PythiaParameters and GeneratorParameters are wrappers around vectors of strings that are passed to Pythia and Alpgen, respectively.

• The PythiaParameters must have a single parameter set, which is a vector of strings named pythia. Inside that vector of strings are the strings that are passed to Pythia via the PYGIVE call.
• The GeneratorParameters must have a single parameter set, which is a vector of strings name generator. Inside that vector of strings are the strings that are passed to Alpgen.

Some particular strings that are useful:

string	passed to	description
"MSTP(143)=1"	Pythia	Call the MLM matching routine in Alpgen. Use it if you generated your sample with ickkw=1.
"IXPAR(2)=1"	Alpgen	Set it to 1 if you're generating an exclusive sample. Set it to 0 otherwise.
"RXPAR(1)=X"	Alpgen	Choose the value of X to be the minimum cluster Et for matching.
"RXPAR(2)=X"	Alpgen	Choose the value of X to be the maximum delta R for matching.

• This example shows how to setup the AlpgenSource.

Compiling the AlpgenInterface package

If you want to change the way the AlpgenInterface works, or use a different version from the one provided in your version of CMSSW, you must checkout and/or edit the source code and compile it. There are different steps o be followed in order to do that, depending on your CMSSW version.

Setting up the environment

The environmental setup depends on the CMSSW version you're using. Currently, the following versions of CMSSW have been tested:

• CMSSW_1_6_12 (for analyzing CSA07 Monte Carlo samples)
• CMSSW_2_1_X (for analyzing Monte Carlo Samples produced with CMSSW_2_1_X) (other than 2_1_17)
• CMSSW_2_1_17 and CMSSW_2_2_X

WARNING

• The AlpgenInterface has gone through a complete refactoring in the 1_6_X to 2_1_x transition. It has undergone basic validation for a subset of the processes in Alpgen - but, as in any piece of software, bugs may still lurk around, so always check your results for consistency. New bugs discovered will be fixed as soon as possible - so always check this Twiki for updated instructions. The latest tag (V00-03-00-01) is up-to-date with the latest original Alpgen code (v213, as of the time of this writing). It has undergone basic validation for the following processes:
  • W + jets
  • Z + jets
  • ttbar + jets
  • W + QQbar + jets, where Q = charm or bottom.
  • Z + QQbar + jets, where Q = charm or bottom.
  • W + charm + jets
  • Njets
• Also, please refrain from using the EDProducer version of the code (file AlpgenProducer.cc). It is still under development, and should be ready for CMSSW 3. Use the AlpgenInterface in the "traditional" way, i.e., as a source (EDSource, file AlpgenSource.cc).

Instructions for CMSSW_1_6_12

Instructions for CMSSW_2_1_X, other than 2_1_17

Instructions for CMSSW_2_2_X and 2_1_17

Example for running the AlpgenInterface on an input Alpgen .unw file

Instructions for CMSSW_1_6_12

• checkout the test subdirectory: cd CMSSW_1_6_12/src; cvs co -r V00-02-19 GeneratorInterface/AlpgenInterface/test
• run the example: cd GeneratorInterface/AlpgenInterface/test; cmsRun Alpgen.cfg
• 100 W to electron+neutrino events should have been produced
• Check for the presence of the HepMCProduct and the AlpgenInfoProduct

Instructions for CMSSW_2_1_X and 2_2_X

• checkout the test subdirectory: cd CMSSW_2_X_Y/src; cvs co -r V00-03-00-01 GeneratorInterface/AlpgenInterface/test
• run the example: cd GeneratorInterface/AlpgenInterface/test; cmsRun Alpgen_cfg.py
• 100 W to electron+neutrino events should have been produced
• Check for the presence of the HepMCProduct, the LHERunInfoProduct and the LHEEventProduct

This example runs on the input example file alpgen.unw (containing previously produced unweighted events) that resides in the same directory. The AlpgenInterface will read in the events from this file, and use Pythia to do the hadronization/showering. Then, the matching routine will be invoked (UPVETO routine) using the parameters given in the cfg, which will veto events for which a hard, non-collinear jet is also produced in the parton shower. Finally, the events are converted into HepMC format and an EDM root output file is produced. The number of events that is run can be changed in the parameter maxEvents in the cfg file. If that parameter is set to '-1' it will run over all events of the input file.

Links

• A repository of information about Alpgen at CMS.
• A FAQ for Alpgen.
• An Alpgen tutorial. This will show you how the produce the unweighted events for further treatment by AlpgenInterface.
• See the Alpgen manual on web page http://mlm.home.cern.ch/mlm/alpgen/
• Documentation of AlpgenInfoProduct, weights etc.
• The CVS repository for AlpgenInterface.

FAQ

• You may also be interested in a FAQ for Alpgen itself:

Why must I use Alpgen standalone code before using AlpgenInterface?

Due to the structure of the Alpgen code, full integration with CMSSW is difficult. A "standard" Alpgen session involves (besides compilations) three different steps:

• Running an executable with a certain flag (imode = 1) to generate weighted events, that are saved to a .wgt file.
• Running the same executable with a different flag (imode = 2) to unweigh those events, which are then save to a .unw file.
• Running a parton shower code (like Pythia or Herwig) with subroutines (PYVETO and UPVETO) that implement the matching.

Notice that the first two steps involve full-fledged executable files, as opposed to simple code libraries. On top of that, each different process (W+jets, Z+jets, ttbar+jets, etc...) involves a different executable file. Those facts make full Alpgen integration into CMSSW very difficult at the present moment.

I don't see my particles (GenParticles / GenParticleCandidates) after using AlpgenInterface.

The AlpgenInterface delivers, as every MC Generator in CMSSW, a collection of generator-level particles in the edm::HepMCProduct format. To convert these into the more standard GenParticles / GenParticleCandidates present in the AOD, we point you to this section of the Workbook.

The last event in my Run has non-hadronized quarks and gluons.

Due to a bug in AlpgenInterface, if the last event read from the unweighted events file was vetoed by the matching, it would nonetheless stay on memory. Then it would be passed to the Framework, be converted to an edm::Event and written to disk. Tags V00-03-00-01 and above solve this problem, but only if you're using the EDSource version of the code (as opposed to the EDProducer version). Also, as a side effect, this tag solves the problem with having a large number of empty events at the end of the Run.

There is a large number of empty events at the end of my Run.

Due to a bug in AlpgenInterface, if one asks for more events to be produced by AlpgenInterface than the number that can be obtained from the unweighted events file (taking into account the matching efficiency), it will complete the production with empty events. The AlpgenEmptyEventFilter module was created to deal with this situation, discarding these empty events, and should be used with AlpgenInterface every time. Alternatively, the tags V00-03-00-01 solve this problem, but only if you're using the EDSource version of the code (as opposed to the EDProducer version).

What extra information is produced by the AlpgenInterface beyond the edm::HepMCProduct? How do I recover it?

The following information is produced:

• One LHEEventProduct per edm::Event, representing the matrix element level event produced by Alpgen.
• One LHERunInfoProduct per edm::Run, representing the information of the "generation run".

The LHERunInfoProduct has, within it, a copy of the _unw.par, .wgt and .par files, in the form of a trio of LHERunInfoProduct::Header. You can recover that information and regenerate those files. A possible use case would be to, given the .wgt and .par files, regenerate the .unw file and perform the matching again with different settings. A implementation of that functionality is given in the AlpgenExtractor module, and an example of its usage is given here.

CAVEAT This functionality depends on the EDM file being produced with AlpgenSource, tag version V00-03-00-01 or later later to work.

Contact

The AlpgenInterface package was developed by Sergey Slabospitsky. The MLM matching was initially ported and maintained by Filippo Ambroglini and Susanna Cucciarelli (INFN, Perugia). Since CMSSW Thiago Tomei (SPRACE), Maurizio Pierini, Maria Spiropulu (CERN) and Filip Moortgat (ETH) ported, tested, validated and extended the code (e.g to keep the info of the weighted and unweighted event, extract the weights per process etc). The contacts with MLM are M. Pierini and M. Spiropulu.

• Hypernews forum: https://hypernews.cern.ch/HyperNews/CMS/get/alpgen.html

Review Status

Editor/Review and date	Comments
-- ThiagoTomei - 26 Jan 2009	Documentation on AlpgenExtractor
-- ThiagoTomei - 22 Jan 2009	Documentation on parameters and LHEProducts
-- ThiagoTomei - 13 Dec 2008	page author (Filip Moortgat)
-- ThiagoTomei - 16 Dec 2008	Twiki fully updated for new version

%RESPONSIBLE% Thiago Tomei, Maurizio Pierini and (ad interim) Filip Moortgat
%REVIEW% Paolo Bartalini

-- ThiagoTomei - 30 Mar 2009