NewAlpgenInterface < Main

Tags: , view all tags
---+!! <nolink>Alpgen Interface to CMSSW</nolink>
%COMPLETE5%

%TOC{title="Contents:"}%

---++ Introduction

[[http://mlm.home.cern.ch/mlm/alpgen/][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 [[http://mlm.home.cern.ch/mlm/alpgen/][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 [[#FrequentlyAskedQuestions][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

[[http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/GeneratorInterface/AlpgenInterface/test/testAlpgenSource_cfg.py?view=markup][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 [[https://twiki.cern.ch/twiki/bin/view/CMS/SWGuideAboutPythonConfigFile][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

[[http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/GeneratorInterface/AlpgenInterface/test/testAlpgenProducer_cfg.py?view=markup][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 [[https://twiki.cern.ch/twiki/bin/view/CMS/SWGuideAboutPythonConfigFile][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=:

<verbatim>
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')
),
</verbatim>  

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
%TWISTY{mode="div" showlink="Show instructions" hidelink="Hide instructions" remember="off" firststart="hide" showimgleft="%ICONURLPATH{toggleopen-small}%"  hideimgleft="%ICONURLPATH{toggleclose-small}%"}%
   * make your local release, for example =cmsrel CMSSW_3_1_0=
   * go to the source directory of your release: =cd CMSSW_3_1_0/src=
   * set the shell environment and cvsroot: =cmsenv; project CMSSW= 
   * check out the package directories: =addpkg !GeneratorInterface/AlpgenInterface; addpkg !GeneratorInterface/PartonShowerVeto=
   * change the code the way you see fit.
   * compile the packages: =scram b=
%ENDTWISTY%

---++Documentation
   
   * SWGuideCMSAlpgen: a repository of information about Alpgen at CMS.
   * [[http://mlm.home.cern.ch/mlm/alpgen/][Latest ALPGEN source code and documentation web page]].
   * AlpgenFAQ: Frequently Asked Questions about Alpgen. 
   * [[https://twiki.cern.ch/twiki/bin/view/Main/AlpgenTutorial][An Alpgen tutorial]]. This will show you how the produce the unweighted events for further treatment by CMSSW Alpgen.
   * [[http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/GeneratorInterface/AlpgenInterface/][The CVS repository for AlpgenInterface]].
   * [[http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/GeneratorInterface/PartonShowerVeto/][The CVS repository for PartonShowerVeto]].

#FrequentlyAskedQuestions
---++ 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 [[https://twiki.cern.ch/twiki/bin/view/CMS/WorkBookGenParticleCandidate][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 [[http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/GeneratorInterface/AlpgenInterface/src/AlpgenExtractor.cc?view=markup][AlpgenExtractor]] module, and an example of its usage is given [[http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/GeneratorInterface/AlpgenInterface/test/AlpgenExtractor_cfg.py?view=markup][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

#ReviewStatus
---++!! Review Status

| *Editor/Review and date* | *Comments* |
| -- Main.ThiagoTomei - 31 Mar 2009 | Updated documentation for 3_1_X |
| -- Main.ThiagoTomei - 26 Jan 2009 | Documentation on !AlpgenExtractor |
| -- Main.ThiagoTomei - 22 Jan 2009 | Documentation on parameters and !LHEProducts |
| -- Main.ThiagoTomei - 16 Dec 2008 | Twiki fully updated for new version |
| -- Main.ThiagoTomei - 13 Dec 2008 | page author (Filip Moortgat) |

%RESPONSIBLE% Thiago Tomei, Maurizio Pierini and (ad interim) Filip Moortgat%BR%
%REVIEW% Paolo Bartalini
Topic revision: r7 - 2009-05-25 - ThiagoTomei
antalya escort bursa escort eskisehir escort istanbul escort izmir escort