Alpgen Interface to CMSSW

Complete: 5


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.
Additional information offered by the Alpgen developers team can be found in the Alpgen Home Page.

As other ME generators of interest to CMS, Alpgen itself is executed as a separate (pre-CMSSW) series of steps, to produce parton-level, unweighted Alpgen events. This step is mandatory in the Alpgen event generation process. For more detailed information on the intricacies of Alpgen, please take a look at the following materials:

To interface Alpgen output to CMSSW, the AlpgenInterface package has been written, as a part of the GeneratorInterface subsystem. It allows the user to read in unweighted Alpgen events, transform them into EDM-compatible format, and pass to it Pythia6 (or, in principle, any multi-purpose generator) to perform parton shower, optional matching, and hadronization.

In general, the AlpgenInterface package is integrated into a CMSSW release. The goals of this page are:

  • To show the user how to use the standard AlpgenInterface package as provided in the CMSSW release.
  • Introduce usage of the AlpgenSource to do the translation between Alpgen native event format and CMSSW data format.
  • Introduce usage of Pythia6 interface + JetMatchingAlpgen plugin to complete the event generation.
  • To show the user how to compile and test a different version of AlpgenInterface.
  • To show the user how to integrate AlpgenInterface with the standard CMSSW tools.
  • To provide answers to some Frequently Asked Questions.
  • To provide an entry point for the AlpgenInterface documentation.

Generating the Sample

As already stated above, the sample generation must be done with Alpgen standalone. See information on SWGuideCMSAlpgen.

Using CMSSW AlpgenInterface

In this section we will walk you through pre-fabricated AlpgenInterface examples and will point you to important details.
Please be advised that the examples shown below are hand-made rather than composed with Later in this documentation we show how to use with CMSSW AlpgenInterface to produce standard CMSSW configuration files.

Basic Example and Output Format

  • Checkout from CVS the AlpgenInterface/test subdirectory:
       cd CMSSW_7_4_15/src 
       cvs co GeneratorInterface/AlpgenInterface/test
  • Make sure you setup your CMSSW runtime environment, and run the example:
       cd GeneratorInterface/AlpgenInterface/test
  • 100 W to electron+neutrino events should have been produced.
  • Check for the presence of the LHERunInfoProduct, LHEEventProduct and HepMCProduct in the ROOT file.
       edmDumpEventContent --run test.root
       edmDumpEventContent test.root 
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: LHERunInfoProduct and LHEEventProduct.
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 HepMC format and an EDM ROOT output file is produced.

Configuring the AlpgenSource

This example shows how to:

  • configure the AlpgenSource to read in events from an Alpgen .unw file and into the edm::Event
  • use a special-purpose module, LHEWriter, which will write the parton-level events in LHE (XML) format

Remember that Alpgen itself writes out events in its own "native" format. Thus the AlpgenInterface package provides a specialized utility 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 learn more on preparing configuration files, please read materials on the CMSSW configuration file language.

The AlpgenSource has, in addition to the usual settings of an EDSource, the following configurable settings:

name type description default
fileNames untracked vstring Names of files containing the UNW events. n/a
writeAlpgenWgtFile untracked bool Option to save the weighted events as a header in the LHERunInfoProduct True
writeAlpgenParFile untracked bool Option to save the weighted generation parameters as a header in the LHERunInfoProduct True
writeExtraHeader untracked bool Option to save any text file as an extra header in the LHERunInfoProduct False
extraHeaderFileName untracked string Name of the text file that contains the extra header described above (empty string)
extraHeaderName untracked string Internal name for the extra header described above (empty string)

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') 

The writeAlpgenWgtFile and writeAlpgenParFile are options to save the contents of the Alpgen run in imode = 1 as headers in the LHERunInfoProduct, allowing one a more complete history of those events prior to their translation to the EDM format. The "extra header" options are there as a wildcard, in case you want to add even more information to the LHERunInfoProduct. The foreseen use case is when you want to add a HepML header, such that when you dump the event into LHE format, the result file is in a suitable format to upload to MCDB. This particular use case would be covered by the following configuration:

process.source = cms.Source("AlpgenSource",
                            fileNames = cms.untracked.vstring('file:w2j'),
                            writeAlpgenWgtFile = cms.untracked.bool(False),
                            writeAlpgenParFile = cms.untracked.bool(False),
                            writeExtraHeader = cms.untracked.bool(True),
                            extraHeaderFileName = cms.untracked.string('w2j.hepml'),
                            extraHeaderName = cms.untracked.string('hepml')

Using Pythia6 Interface to Process Alpgen Events

Once Alpgen parton-level events are translated, by AlpgenSource, to the EDM format, one can use a specialized Pythia6-based component, Pythia6HadronizerFilter, for parton shower and further develop the event into a fully hadronized state. The Pythia6HadronizationFilter is a part of the GeneratorInterface/Pythia6Interface package, which is described in the SWGuidePythia6Interface dedicated document.

In principle, one can use not only Pythia6-based utility to process Alpgen (or any ME) events, but any multi-purpose generator, for example, Herwig6. However, at this time Pythia6-based tools are the most widely available, while interfaces to other multi-purpose generators remain under validation. For this reason we, at present, will concentrate only on Pythia6-based tools.

We would like to offer an example application,, that demonstrates usage of Pythia6HadronizerFilter on Alpgen events. This example also employs the internal parton-shower veto tool, which will be described in the next subsection.
Configuration of the Pythia6HadronizerFilter is actually brought into this example

from a separate pre-fabricated configuration include GeneratorInterface/AlpgenInterface/python/
In general, configuring Pythia6HadronizerFilter is very similar to configuring full event generation with Pythia6 in CMSSW, as described in SWGuidePythia6Interface, but we would like to point your attention to certain details. Specifically, in the following block of the configuration cards
PythiaParameters = cms.PSet(
        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',
the processParameters contains settings for processing an Alpgen event.

Using the JetMatchingAlpgen Functionality

The above example also shows how to setup of the MLM ME/PS matching procedure.

Please note that parton-shower matching use is optional and can be activated at the run time, with the use of the jetMatching subset of parameters of Pythia6HadronizerFilter (or any similar "hadronizer"):

jetMatching = cms.untracked.PSet(
        scheme = cms.string("Alpgen"),
        applyMatching = cms.bool(True),
        exclusive = cms.bool(True),
        etMin = cms.double(25.),
        drMin = cms.double(0.7)

The table below summarizes the default 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 AlpgenInterface

In case you want to use a customized version of AlpgenInterface (a version different from the one in your release, or a customized version with extra functionality), you need to recompile the package. The AlpgenInterface package is structured as follows:

  • src: basic code for manipulation of Alpgen events in the context of CMSSW.
  • plugins: CMSSW modules related to Alpgen.
  • interface: include files.
  • python: small python files for inclusion in full-fledged CMSSW configuration files.
  • test: test CMSSW configuration files, together with a small set of Alpgen events, for simples testing of all components of the package. There is also a test shell script,, that automates the tests a bit.
To recompile the AlpgenInterface package, after making the necessary changes, you should do:
cd GeneratorInterface/AlpgenInterface
scram b clean
scram b
It is also a good idea to run the test shell script to check everything is working:

Using AlpgenInterface with to Generate Standard CMSSW Configuration Files

If you want to use AlpgenInterface with to generate standard CMSSW configuration files you can customize the configuration fragment sourceAndGenerator included in the AlpgenInterface package to suit your needs. Then you can run as usual. For instance, for a simple GEN tier run, with the standard configurations for the AlpgenSource and the Pythia6HadronizerFilter + JetMatchingAlpgen modules: GeneratorInterface/AlpgenInterface/python/ \
-s GEN \
--conditions auto:mc \
--datatier 'GEN' \
--eventcontent RAWSIM -n 100 \

Additional Documentation

Contact and Acknowledgments

The following experts have greatly contributed to the efforts: Filip Moortgat (ETH), Maurizio Pierini (CERN), Maria Spiropulu (CERN), Sergey Slabospitsky (IHEP), Filippo Ambroglini and Susanna Cucciarelli (both INFN, Perugia), Flavia Dias (SPRACE). The contacts with MLM are M. Pierini and M. Spiropulu.

AlpgenInterface FAQ

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

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.

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, by default, 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.

Review Status

Editor/Review and date Comments
-- ThiagoTomei - 06-Mar-2013 Cleaning up the legacy (CMSSW < 3_X_Y ) instructions
-- ThiagoTomei - 17-Nov-2010 Big, final cleanup. Also instructions for
-- ThiagoTomei - 25 May 2009 Preparing for CMSSW 3
-- 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: FlaviaDias
Last reviewed by: ThiagoTomei

Edit | Attach | Watch | Print version | History: r43 < r42 < r41 < r40 < r39 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r43 - 2013-03-06 - ThiagoTomei

    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CMSPublic All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback