001
002
003 ============
004 = WBBGEN =
005 ============
006
007 by Michelangelo L. Mangano (CERN), Mauro Moretti (Univ. of Ferrara)
008 and Roberto Pittau (Univ. of Torino)
009
010 ----------------------------------------------------------------------
011 IMPORTANT NOTICE:
012 ----------------------------------------------------------------------
013 IF YOU DOWNLOADED THE CODE FROM THE WEB, OR GOT IT FROM SOMEONE FOR
014 THE FIRST TIME, PLEASE SEND MAIL TO THE ADDRESSES AT THE END OF THIS
015 DOCUMENT, SO THAT WE CAN ADD YOU TO THE MAILING LIST AND KEEP YOU
016 UPTODATE ON NEW RELEASES OR BUG FIX NOTIFICATIONS.
017 ----------------------------------------------------------------------
018 ----------------------------------------------------------------------
019
020 This file documents the use of the package WBBGEN.
021
022
023 The WBBGEN package allows to generate partonic final states with W, a
024 heavy quark pair, and additional N jets (N=0,1,...,4). The calculation
025 includes all relevant tree-level matrix elements, and is performed
026 using the algorithm ALPHA [1], extended to handle QCD processes in
027 [2].
028
029 The parton-level generation can be extended to a full QCD shower
030 development, performed by HERWIG [3]. This can be accomplished since the
031 matrix element calculation is done keeping track of the possible
032 colour structures of the partonic system. When run in the appropriate
033 mode (see later) WBBGEN will fill the HEPEVT common block, which
034 contains all of the information necessary for HERWIG (or any other
035 standard shower MC) to develop the parton shower.
036
037 The mass of the heavy quark is kept different from 0
038 throughout the calculation. As a result no cuts on the minimum momentum
039 of the heavy quark nor on the minimum angular separation between heavy
040 quark and heavy antiquark are necessary. One can then explore the
041 contribution to the cross-section of configurations where both b and
042 bbar are close enough to belong to the same jet.
043
044
045 You first need to download from the web the file wbb.tar.gz. This can be
046 obtained from
047
048 http://home.cern.ch/mlm/wbb/wbb.html
049
050 Then follow the following steps:
051
052 1. create a subdirectory to your main directory
053 > mkdir wbbgen
054
055 2. copy wbb.tgz to this directory
056
057 3. issue the comand:
058 > tar -zxvf wbb.tar.gz
059
060 The archive will unpack itself, and create the following directory structure:
061
062 Makefile alplib/ herlib/ wbbdoc.txt wbblib/ wbbwork/
063
064 The package contains two sets of codes. The first set deals with the
065 generation of parton level events. The second set provides an
066 interface to HERWIG.
067
068 - The file wbbdoc.txt is this document
069
070 - The directory wbbwork/ contains the parts of the code which the user
071 is supposed to interact with, in order to implement her own analysis
072 cuts, etc.
073
074 - The directory alplib/ contains the parts of code which are generic to
075 the evaluation of matrix elements using the ALPHA algorithm. When
076 new processes will be added in the future, this part of the code
077 should not change.
078 The user should treat this as a black box.
079
080 - The directory herlib/ contains the partos of code relevant for the
081 shower evolution using Herwig. In addition to the Herwig source and
082 include files, this directory includes the interface between the
083 parton-level matrix elements and Herwig itself.
084 The user should treat this as a black box.
085
086 - The directory wbblib/ contains the parts of the code specific to the
087 generation of Wbb+jet events.
088 The user should treat this as a black box.
089
090
091 More in detail, here is the role of some of the most important code
092 elements:
093
094 wbbwork/wbbusr.f: contains the routines in which the user can select
095 generation mode (see later), generation parameters
096 (e.g. beam energy, PDF sets, heavy quark mass, etc) as well
097 as generation cuts (minimum pt thresholds, etc). Here the
098 user initialises the histograms, writes the analysis
099 routine, and prints out the required program output. This
100 is the only part of the code in which the user is supposed
101 to operate. The version provided as a default contains
102 already a complete running example. All remaining files can
103 be used as black boxes.
104
105 wbblib/wbb.f: contains the routines specific to the generation of
106 Wbb+jet events.
107 wbblib/wbb.inc: include file, with the necessary common blocks, for WBBGEN
108
109 alplib/alpgen.f: contains the general structure of the code, preparing
110 the input for the matrix element calculation, the
111 bookkeeping of the cross-sectin determination, etc.
112
113 alplib/alpgen.inc: include file, with the necessary common blocks.
114
115 alplib/Awbb.f , Asu3.f, Acp.f: the set of programmes
116 necessary for the calculations of the matrix element, done
117 by the alpha algorithm.
118
119 alplib/alppdf.f: contains a collection of structure function
120 parametrizations; some of them require at run time input
121 tables, which are provided as part of the package, and
122 stored in the subdirectory alplib/pdfdat/. The command file
123 wbbwork/pdfdef contains the necessary logical links to all
124 pdf data tables. As a default, we already provide the
125 logical link to the pdf set cteq5m. If you want to use
126 different pdf sets (see Appendix for the list), ensure
127 that the table file corresponding to the desired set,
128 or a link to it, is present in the run directory
129
130 alplib/alputi.f: This program unit contains a histogramming
131 package which allows to generate topdrawer files with the
132 required distributions.
133
134 The provided Makefile, edited to match the directory location for the
135 files chosen by the user, can be used to compile and link the
136 necessary code. With the default Makefile, issue the following command
137 from the top directory:
138
139 > make wbbgen
140
141 The user can edit Makefile to select her preferred compiler, options, etc.
142
143 A test run can be performed by changing directory to wbbwork, where
144 the execuatable wbbgen will now sit, and using the provided file of
145 inputs:
146
147 > wbbgen < input
148
149 A brief explanation of the code running options is given here:
150
151 The code runs in 2 possible ways. In the first way the code runs as a
152 standard stand-alone parton-level matrix element MC, generating
153 weighted parton-level events to be analysed on line. This way of
154 running is selected at run time through the option:
155
156 imode=0: weighted events are generated, and can be analised at the
157 parton level. The user who is not interested in developing
158 the full parton shower and is happy with parton-level
159 distributions can just opt for this choice. No further
160 processing is required.
161 As an output the user will find the following files (`file'
162 is the label assigned by the user at run-start time):
163 - file.stat (includes cross sections, max weight, etc)
164 - file.top (includes topdrawer plots, if requested)
165 One file required by ALPHA is generated at run time
166 (CNFG.DAT): it is not needed for the
167 analysis of the output, and will be recreated anew any time
168 the code runs, so the user should not bother about it, and
169 it can be safely deleted at any time.
170
171 During the run, the file
172 - file.mon
173 is created. It contains information on the status of the
174 run, dumped eveny 100K events. Useful to monitor the
175 progress of the run
176
177 In addition to the above, a grid is generated after the
178 optimization of the phase-space generation, and is written to
179 an ASCII data file, labeled by the unit number N selected by
180 the user (igrdW). The grid can be used for later generation
181 of further events (with the same kinematic cuts), to save
182 an extra optimization stage.
183
184
185 In the second way, a 2-step process allows to prepare a sample of
186 unweighted parton-level events which are used as inputs for HERWIG,
187 which will then perform the shower evolution. The two steps are
188 performed running wbbgen, in sequence, in the following modes:
189
190 imode=1: weighted events are generated, and are saved in a file. What
191 is saved is just a random number seed, in addition to the
192 event weight and the value of x1 (useful to check the sanity
193 of the file when it will be read for the unweighting). To
194 limit the size of the file, only events which passed a
195 pre-unweithing (based on a maximum weight which is only 5% of
196 the current maximum weight) are saved. Some statistical
197 information on the run, inclusing the total number of
198 generated events, the integral, and the overall maximum
199 weight, are saved as well in a separate file. The file with
200 weighted events is to be used for a later unweighting. The
201 random number seed will then be sufficient to regenerate the
202 full kinematical and flavour information on the event. The
203 size of each event is 20bytes. Make sure you have enough disk
204 space to write out the number of events you require.
205 As an output the user will find the following files:
206 - file.stat (includes cross sections, max weight, etc)
207 - file.top (includes topdrawer plots, if requested)
208 - file.par (run parameters (e.g. cuts, etc) and diagnostics
209 - file.wgt (unformatted file with event random number and
210 weight)
211
212 imode=2: the code scans the file containing the weighted events. A
213 comparison of the event weights with the maximum weight is
214 made, and the unweighting is performed. The kinematics of
215 each unweighted event is reconstructed from the relative
216 random number seed. The colour flow for the event is then
217 calculated, and the full event information is written to a
218 new file. This file will be the starting point for the
219 generation of the full shower, to be performed using HERWIG.
220 As an output the user will find the following files:
221 - file_unw.stat (includes cross sections, max weight, etc)
222 - file_unw.top (includes topdrawer plots, if requested)
223 - file.unw (file with event kinematics)
224
225
226 At this point one can run the HERWIG code, which has been properly
227 modified to read the hard-process events from the unweighted-event
228 file before proceeding to the shower evolution. This is achieved by
229 replacing the HERWIG call to HWEPRO (the standard routine for the
230 calculation of a hard process matrix element and setup of the hard
231 subprocess) with a call to a new routine, LOADEV, whose role is to
232 read one event from the unweighted event file, and to fill the
233 /HEPEVT/ common block. After this call the standard HERWIG calls to
234 HWBGEN etc are performed.
235
236 In addition to HERWIG itself (we provide in the package the version
237 6.1 of the code), the following files are necessary for the HERWIG
238 evolution:
239
240 herlib/hwuser.f: user initialization of the analysis. Includes standard
241 HERWIG initialization, histogram intialization, analysis
242 routines, etc. The call to the Herwig routine HWEPRO, which
243 in the standard Herwig generates the hard process, is
244 replaced by a call to a routine which reads in the hard
245 process from the event file.
246 herlib/atoher.f: this file contains all routines necessary to read in the
247 events produced by wbbgen, and fill the Herwig HEPEVT common
248 block containing all information on the hard event necessary
249 for the shower evolution. It should be treated by the user
250 as a black box.
251 herlib/herwig61.f: the herwig61 source code. herwig61.f and
252 herwig61.inc are the standard, default version 6.1 herwig
253 files [3]
254 herlib/HERWIG61.INC: herwig common blocks
255 herlib/pdfdummy.f: dummy pdf routine, required by herwig61 unless the
256 CERN library PDf sets are used
257 alplib/alputi.f: This program unit contains a histogramming
258 package which allows to generate topdrawer files with the
259 required distributions. Can be left out is user selects
260 other bookkeeping tools (e.g. HBOOK, etc)
261
262
263 They can be compiled and linked using the provided Makefile, with the
264 option
265
266 > make hwuser
267
268 As it is, this default will simply run Herwig over a set of unweighted
269 events, but no analysis is performed. The user should provide her own
270 analysis routine, by editing HWANAL in hwuser.f. One example of such
271 user routines is included in the file wbbwork/hwmlm.f This is compiled
272 and linked using
273
274 > make hwmlm
275
276 The execuatable hwmlm, contained in wbbwork/ , will run over a file of
277 unweighted events (file to be specified by the user at run time) and
278 will generated top drawer file with some reference distributions.
279 As an output the user will find the following files:
280 - file_her.stat (includes cross sections, max weight, etc)
281 - file_her.top (includes topdrawer plots, if requested)
282
283
284 INPUT PARAMETERS
285 ================
286
287 Parameters controlling the run and I/O are passed to WBBGEN through
288 the routine SETPAR. The code contains comment lines which should be
289 sufficiently self-explanatory. The kinematics of the events is defined
290 in the rest frame of the hadron-hadron collision.
291
292 Due to the high dimensionality of the final phase-space, and due to
293 the large range of possible partonic CM energies, the event weights
294 span a very large range. While several techniques have been used to
295 optimise the generation of phase-space points, a large number of
296 events is necessary before distributions become smooth. When the code
297 is run in imode=0 or 1, the option exists to generate a number of
298 events with the sole purpose of producing an optimal integration grid
299 which will reduce the event-by-event fluctuations. The information on
300 this grid can be saved, using the proper option, to a file, so that
301 later runs will not require this initialisation phase. As a rule of
302 thumb, for the generation of W+4 jet events we suggest one or two
303 initialisation iterations, with no less than 5 million events
304 each. For different jet multiplicities, we suggest a factor of 2
305 increase (reduction) for each parton extra (less).
306
307
308 TESTS
309 =====
310 Some benchmark results are provided with the package. They are
311 contained in the subdirectory tests/
312 They include the output of a series of runs generated for 3-jet final
313 states. The user can recreate them by following the instructions given
314 here:
315
316 In the directory wbbwork/, issue the comand:
317
318 > wbbgen < input
319
320 This will start a run with imode=1, 1000000 events in 2 iterations for
321 optimization, generated 10000000 weighted events written to file
322 (w3j.wgt). The kinematical cuts, PDFs etc. are those appearing as
323 defaults. Some distributions are contained in the topdrawer file
324 w3j.top. This is a readable ASCII file, containng all the
325 distributions. The user can turn it into a postscript file, if she has
326 topdrawer installed. For this example, running topdrawer on the file
327 should give the output we prodice in test/w3j.ps
328
329 To unweight the events generated in the previous run,
330 rerun the code:
331
332 > wbbgen
333
334 inputting imode=2 and w3j as file name. This leads to XXX unweighted
335 events. The same distributions as above, now limited to the set of
336 unweighted events, are contained in the topdrawer file w3j_unw.top,
337 and in a postscript file (w3j_unw.ps)
338
339 We can now process the unweighted events thorugh Herwig:
340 > hwmlm
341
342 This code develops the unweighted events selected above through the
343 HERWIG parton showers. For simplicity, in this example only the
344 perturbative radiation stage was included (no hadron formation), and
345 jets are reconstructed using the GETJET routines.
346 To generate the full hadronic shower, including hadron formation and
347 underlying event, use herlib/hwuser.f as a driver.
348
349 Some jet distributions for the XXX events are contained in the
350 topdrawer file w3j_her.top. Here quantities before and after shower
351 evolution are compared (e.g. spectra of jets, correlations in eta-phi
352 between the n-th parton and the n-th jets, etc). The plots show for
353 example that some extra jet, beyond those present at parton level, is
354 generated by the shower evolution. The plots can also be seen viewing
355 directly directly the postscript file in test/w3j_her.ps.
356
357
358 General comments, Q&A, etc.
359 ---------------------------
360 Q: why is the unweighting not done on the fly?
361 A: processes with many partons in the final state have a very large
362 range of weights. A new maximum weight can be found after a very
363 long run, and the unweighting of the previous events may have been
364 biased. Doing the unweighting at the end guarantess that the
365 maximum weight for this data set has been found. There is one more
366 reason for doing the unweighting in a second step: once the full
367 weight distribution for the generated sample is known, the
368 unweighting efficiency can be optimised by selecting a reference
369 maximum weight which is lower than the absolute maximum
370 weight. This is possible, provided it does not bias the
371 unweighting. The user can steer the unweighting procedure by
372 editing the function UNWGT, contained at the end of the WBBUSR.F
373 module.
374
375 Q: why is the HERWIG shower generated as a third step, instead of
376 taking place during the unweighting phase?
377 A: keeping the HERWIG shower generation as a separate step allows to
378 keep the two groups of codes separated. This allows a simpler
379 maintainance of the codes when either of the two evolves and is
380 updated. Furthermore, this allows to perform the shower evolution
381 using different HERWIG settings (in order, for example, to study
382 systematic effects due to a choice of shower cutoffs, underlying
383 event modeling, etc) without having to repeat the unweighting. It
384 is sufficient to rerun HERWIG on the same file of unweighted
385 events. Finally, given the larger disk-space requirements of the
386 weighted-event files, one can consider adding new statistics to the
387 unweighted-event file in subsequent steps.
388
389 Q: what is the overall normalization of the plots?
390 A: all x-sections are given in pb. Plots filled when running with
391 imode=0,1 should be rescaled at the end of the run by multiplying
392 with avgwgt/totwgt (i.e. the inverse of the total number of events
393 generated, including those rejected at the generation level because
394 of phase-space cuts etc.). Plots filled with imode=2 should be
395 rescaled by the user dividing by the total number of events which
396 were unweighted (unwev). In all cases (imode=0,1,2) these rescalings are
397 already done automatically in the provided version of the
398 histogram-finalisation routine FINHIS.
399 In the provided version, the plots normalization is pb/bin. For
400 absolute normalizations such as pb/gev, a bin-size correction
401 should be done by the user. In the version provided this can
402 be achieved directly on the topdrawer plots, by including the
403 statement SET ORDER X Y XNORM just before the string of histogram
404 points, with XNORM=1/bin-size.
405
406
407 References
408 [1] F.Caravaglios and M.Moretti, Phys.Lett.B358:332-338,1995,
409 [2] F. Caravaglios, M.L. Mangano, M. Moretti and R. Pittau,
410 Nucl.Phys.B539:215-232,1999.
411 [3] G. Marchesini and B.R. Webber, Nucl.Phys.B310:461,1988
412 G. Corcella, I.G. Knowles, G. Marchesini, S. Moretti, K. Odagiri,
413 P. Richardson, M.H. Seymour and B.R. Webber,
414 JHEP 0101:010,2001 (hep-ph/0011363)
415 G. Marchesini, B.R. Webber, G. Abbiendi, I.G. Knowles,
416 M.H. Seymour, L. Stanco, Comput.Phys.Commun.67:465-508,1992
417
418
419 Michelangelo Mangano
420 michelangelo.mangano@cern.ch
421
422 Mauro Moretti
423 moretti@fe.infn.it
424
425 Roberto Pittau
426 pittau@to.infn.it
Send problems or questions to cdfcode@fnal.gov
