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, collectively called LHE products.). It is also possible, through the use of the JetMatchingAlpgen class 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 class 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. We strongly encourage the user to look at the Alpgen documentation - many of the concepts mentioned in this documentation are fully explained there.

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 documentation of usage of the Alpgen generator in CMS.

Generating the sample

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

Using CMSSW Alpgen

Basic Example

• checkout the test subdirectory: cd CMSSW_3_1_X/src; cvs co GeneratorInterface/AlpgenInterface/test
• run the example: cd GeneratorInterface/AlpgenInterface/test; cmsRun testAlpgenComplete_cfg.py
• 100 W to electron+neutrino events should have been produced
• Check for the presence of the HepMCProduct, the LHERunInfoProduct and the LHEEventProduct in the ROOT files.

This example runs on the example input file w2j.unw (containing previously produced unweighted events) that resides in the same directory. The AlpgenSource will read in the events from this file and create the LHE products in the edm::Event. In sequence, the Pythia6HadronizerFilter will do the hadronization/showering, and will call the JetMatchingAlpgen to veto the events that don't pass the MLM procedure, according to the configurations given. Finally, the events are converted into [[HepMCFormat][HepMC format]] and an EDM ROOT output file is produced.

Using the AlpgenInterface package

This example shows how to use the AlpgenInterface package. It shows how to setup the AlpgenSource, read in events from an ALPGEN .unw file into the edm::Event, and write the events in LHE (XML) format.

The AlpgenInterface package provides a facility to format shift the events produced by Alpgen standalone (unweighted events, or UNW events for short) into CMSSW objects (LHEEventProduct). By the same token, the generation parameters (usually written in the file with ending _unw.par) are packaged into a LHERunInfoProduct. This facility is implemented as 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, configuring and using the AlpgenSource. The AlpgenSource has only one configurable setting:

name	type	description	default
fileNames	untracked vstring	Names of files containing the UNW events.	n/a

CAVEAT: although the fileNames parameter is, by construction, a vector of strings, the AlpgenSource does not accept more than one file at a time. Also, that file has to be local, i.e., it has to be accessed using the file: scheme. Finally, the file name has to be given without the .unw suffix. So, if your file is called w2j.unw, the correct setting is

fileNames = cms.untracked.vstring('file:w2j')

Using the JetMatchingAlpgen class

This example shows how to use the Pythia6HadronizerFilter module and the JetMatchingAlpgen class to perform parton shower, hadronization and matching in events produced by the AlpgenSource.

The JetMatchingAlpgen class, a component of the PartonShowerVeto package, provides an Alpgen-tailored interface to the Pythia 6 code already integrated in CMSSW. With the JetMatchingAlpgen class, it is possible to perform parton shower and hadronization in a collection of LHEEventProduct produced by AlpgenSource, all from within the CMSSW framework. The JetMatchingAlpgen class is designed as an auxiliary class to the Pythia6HadronizerFilter module, which provides the foundations for the communication in between Pythia 6 (FORTRAN code) and CMSSW (C++ code). If you want to use the JetMatchingAlpgen class as provided in CMSSW, you must prepare a configuration file as described in the CMSSW configuration file language, configuring and using the Pythia6HadronizerFilter module. The Pythia6HadronizerFilter module has the following configurable 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
comEnergy	double	Center of mass energy	(See below)
PythiaParameters	edm::ParameterSet	(See below)	(See below)
jetMatching	edm::ParameterSet	(See below)	(See below)

The comEnergy parameter is, as of the time of this writing, completely dummy. You may setup it to whatever you wish - the real center of mass energy is taken from the LHERunInfoProduct. The user is, naturally, advised to keep the values consistent.

The PythiaParameters parameter set is a wrapper around vectors of vectors of strings that are passed to Pythia 6, via PYGIVE calls. It is equivalent to the PythiaParameter commonly found in other generator interfaces. Here, it is usually used for two purposes: to setup the underlying event tunings, and to setup Pythia to work the way we want it to - full user control of processes, fragmentation and hadronization processes, etc. An example PythiaParameters:

PythiaParameters = cms.PSet(
    pythiaUESettingsBlock,
    processParameters = cms.vstring(
        'MSEL=0          ! User defined processes',
        'MSTJ(1)=1       ! Fragmentation/hadronization on or off',
        'MSTJ(11)=3      ! Choice of the fragmentation function'),
    # This is a vector of ParameterSet names to be read, in this order
    parameterSets = cms.vstring(
        'pythiaUESettings',
        'processParameters')
),

The jetMatching parameter set controls the setup of the MLM ME/PS matching procedure. It has the following configurable settings:

name	type	description	default
scheme	string	Method used for matching - don't change!	"Alpgen"
applyMatching	bool	Controls if matching is to be applied in this sample	True
exclusive	bool	Controls if matching is to be done in an exclusive way	True
etMin	double	Minimum transverse energy for matched cluster	25.0
drMin	double	deltaR for matched clusters	0.7

Compiling the CMSSW Alpgen packages

If you want to change the way CMSSW Alpgen packages work, 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 to 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_3_1_0 (initial release for the CMSSW 3 series)

Instructions for CMSSW_3_1_0

Documentation

• SWGuideCMSAlpgen: a repository of information about Alpgen at CMS.
• Latest ALPGEN source code and documentation web page.
• AlpgenFAQ: Frequently Asked Questions about Alpgen.
• An Alpgen tutorial. This will show you how the produce the unweighted events for further treatment by CMSSW Alpgen.
• The CVS repository for AlpgenInterface.
• The CVS repository for PartonShowerVeto.

FAQ

These are specific questions about CMSSW Alpgen. For general Alpgen questions, please refer to the AlpgenFAQ.

Why must I use Alpgen standalone code before using CMSSW Alpgen?

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 CMSSW Alpgen.

CMSSW Alpgen 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.

What extra information is produced by CMSSW Alpgen 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. An implementation of that functionality is given in the AlpgenExtractor module, and an example of its usage is given here.

Why was the old AlpgenInterface functionality split over two pieces (AlpgenSource and JetMatchingAlpgen)? How do I use the two pieces?

The separation was a design decision by the CMS Generators group, documented in https://twiki.cern.ch/twiki/bin/view/CMS/GeneratorMigration. The pieces are independent in the sense that they belong to different packages (AlpgenInterface and PartonShowerVeto), but they are meant to be used together. What has become possible now, thanks to this new design, is the following workflow:

1. Generate UNW events using Alpgen standalone.
2. Format shift them to LHE products, with AlpgenSource.
3. Serialize them into EDM ROOT files.
4. Load them (with a standard PoolSource), at a different time and place, back into a CMSSW job.
5. Create full fledged HepMCProduct events, with Pythia6HadronizerFilter.

Notice that, after step 2, the original UNW events are not needed anymore - the LHE products completely supersede them. That means that, from step 3 onwards, the full chain is completely contained within CMSSW, with all the advantages that situation brings.

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), Filip Moortgat (ETH) and Cristophe Saout ported, tested, validated and extended the code (e.g to keep the info of the weighted and unweighted event, extract the weights per process, the many rewritings of the interface 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 - 31 Mar 2009	Updated documentation for 3_1_X
-- ThiagoTomei - 26 Jan 2009	Documentation on AlpgenExtractor
-- ThiagoTomei - 22 Jan 2009	Documentation on parameters and LHEProducts
-- ThiagoTomei - 16 Dec 2008	Twiki fully updated for new version
-- ThiagoTomei - 13 Dec 2008	page author (Filip Moortgat)

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