2 <chapter name="Jet Matching">
6 This manual page describes the parton-jet matching interfaces for
7 PYTHIA8. In this approach, usually referred to as MLM matching
8 <ref>Man02, Man07</ref>, the final jets after parton-shower evolution
9 and jet clustering are matched to the original partons. The event is
10 accepted if a reasonable match is found, and rejected if not. The
11 rejection step in an approximate way introduces a Sudakov form factor
12 on to the hard processes. Notably the parton shower should not generate
13 an emission that would doublecount hard activity already included in
14 the matrix-element description. Within this general ansatz, different
15 technical solutions can be adopted. We provide two alternatives, one
16 based on the algorithm used in ALPGEN <ref>Man03</ref>, and another on
17 the one used in Madgraph <ref>Alw11</ref>, both reimplemented from
18 scratch here. The main points of these two algorithms are outlined
19 further down on this page.
21 <p/>We also allow for two alternative sources of external events,
22 one in the ALPGEN native format and one in the Madgraph LHEF-based one.
23 All four combinations of input format and matching style are
24 implemented. In the following it is therefore important to keep
25 the two aspects apart, whenever the ALPGEN and Madgraph labels
28 <p/>Currently all the files of interest are located in the
29 <code>examples/</code> subdirectory:
31 <li><code>JetMatching.h</code> contains the machinery for the
32 parton-jet matching, in the two <code>JetMatchingAlpgen</code>
33 and <code>JetMatchingMadgraph</code> classes.
35 <li><code>GeneratorInput.h</code> contains three classes for the
36 reading of ALPGEN event and parameter files, and one for the reading
37 of Madgraph parameters.
39 <li><code>CombineMatchingInput.h</code> contains three classes that
40 combine the reading of events with the matching of them.
43 <code>main32.cc, main32.cmnd</code> : a sample main program and card
44 file showing the usage of the previous files/classes.
48 <h2>Event input source</h2>
50 External sources of partons are used in the parton-jet matching
51 process. The source of the partons has been separated from the
52 implementation of the matching algorithm. By default, PYTHIA8
53 contains a machinery to process Les Houches Event Files (LHEFs)
55 <aloc href="LesHouchesAccord">Les Houches Accord</aloc>
56 and <aloc href="BeamParameters">Beam Parameters</aloc>
57 pages. Madgraph5 adheres to this format, but also contains some further
58 non-standardized information that can be used. The parsing of the native
59 ALPGEN file format is described on the
60 <aloc href="AlpgenEventInterface">Alpgen Event Interface</aloc> page.
62 <p/>Commonly, the source of external partons also contains information
63 about how a particular type of matching algorithm should be employed.
64 This information is handled by the <code>AlpgenPar</code> class for
65 ALPGEN files, and <code>MadgraphPar</code> for LHEFs.
66 The user can choose to set default matching parameters using the
67 <code><aloc href="AlpgenEventInterface">Alpgen:setMLM</aloc></code>
68 flag for ALPGEN files. For LHEFs, instead, the setting of default
69 parameters is controlled with the <code>JetMatching:setMad</code> flag:
71 <flag name="JetMatching:setMad" default="on">
72 When enabled, the merging parameters are set according to the values
73 in the LHEF header. Specifically, the header must set the
74 <code>ickkw</code>, <code>xqcut</code>, <code>maxjetflavor</code>
75 and <code>alpsfact</code> values, and <code>ickkw</code> must be nonzero.
76 Note that these labels are Madgraph-specific. For other programs
77 with LHEF output, or for Madgraph files lacking this information,
78 these parameters should be set by the user (or one can rely on the
79 default values). The following parameters (described below) must then
82 <li> <code>JetMatching:doMerge = ickkw</code>, </li>
83 <li> <code>JetMatching:qCut = xqcut</code>, </li>
84 <li> <code>JetMatching:nQmatch = maxjetflavor</code>, </li>
85 <li> <code>JetMatching:clFact = alpsfact. </code> </li>
87 With this flag on, the values from the LHEF for these parameters take
88 precedence over other values.
91 <h2> Jet Matching parameters </h2>
93 A class <code>JetMatching</code>, derived from <code>UserHooks</code>, is
94 used to define the basic structure of a parton-jet matching algorithm.
95 Two versions are implemented here, based on the FORTRAN code provided
96 by the ALPGEN and Madgraph packages, respectively:
97 <code>JetMatchingAlpgen</code> and <code>JetMatchingMadgraph</code>.
98 The matching parameters are defined with the <code>JetMatching:*</code>
101 <h3> Scheme and Usage </h3>
103 <flag name="JetMatching:merge" default="off">
104 Master switch to activate parton-jet matching.
105 When off, all external events are accepted (unless they
106 are rejected due to weighting or event processing problems).
109 <modepick name="JetMatching:scheme" default="1" min="1" max="2">
110 The parton-jet MLM-style matching scheme.
111 <option value="1"> The one inspired by the Madgraph matching code,
112 here implemented in the <code>JetMatchingMadgraph</code> class.</option>
113 <option value="2"> The one inspired by the ALPGEN matching code,
114 here implemented in the <code>JetMatchingAlpgen</code> class.</option>
117 <h3>Jet algorithm</h3>
119 The choice of jet algorithm and associated parameters can be adjusted with
120 the settings below. The PYTHIA8 internal <code>CellJet</code> and
121 <code>SlowJet</code> routines are used for jet finding. See the
122 <aloc href="EventAnalysis">Event Analysis</aloc> page for more details.
124 <modepick name="JetMatching:jetAlgorithm" default="1" min="1" max="2">
125 The choice of jet algorithm to use when merging against hard partons.
126 Currently, only <code>SlowJet</code> with the k<sub>T</sub> algorithm (and
127 <code>useStandardR = false</code>) is supported for Madgraph-style
128 matching, while there is full freedom for the ALPGEN-style matching.
129 <option value="1">The <code>CellJet</code> cone algorithm.</option>
130 <option value="2">The <code>SlowJet</code> clustering algorithm.</option>
133 <modepick name="JetMatching:slowJetPower" default="-1" min="-1" max="1">
134 The power to use in the <code>SlowJet</code> algorithm.
135 <option value="-1">The anti-k<sub>T</sub> algorithm.</option>
136 <option value="0">The Cambridge/Aachen algorithm.</option>
137 <option value="1">The k<sub>T</sub> algorithm.</option>
140 <modepick name="JetMatching:nEta" default="100" min="50">
141 Specific to the <code>CellJet</code> algorithm, the number of bins
145 <modepick name="JetMatching:nPhi" default="60" min="30">
146 Specific to the <code>CellJet</code> algorithm, the number of bins in phi.
149 <parm name="JetMatching:eTseed" default="1.5" min="0.0">
150 Specific to the <code>CellJet</code> algorithm, the minimum <ei>eT</ei>
151 for a cell to be acceptable as the trial center of a jet.
154 <parm name="JetMatching:eTthreshold" default="0.1">
155 Specific to the <code>CellJet</code> algorithm, cells with
156 <ei>eT < eTthreshold</ei> are completely neglected by the jet algorithm.
159 <h3>Merging parameters</h3>
161 The following options are the three main parameters for the merging
162 procedure. Although here they are in principle free parameters, they should
163 be heavily influenced by the hard process generation cuts.
164 These values can be set automatically based on the information in the
167 <parm name="JetMatching:eTjetMin" default="20.0" min="5.0">
168 For the <code>CellJet</code> algorithm, this gives the minimum transverse
169 energy inside a cone for a jet to be accepted. For the <code>SlowJet</code>
170 algorithm, this is instead the minimum transverse momentum required for a
171 cluster to be accepted as a jet. For Madgraph-style matching, this
172 parameter should match the <code>qCut</code> parameter described later.
175 <parm name="JetMatching:coneRadius" default="0.7" min="0.1">
176 For the <code>CellJet</code> algorithm, this gives the size of the cone
177 in <ei>(eta, phi)</ei> space drawn around the geometric center of the jet.
178 For the <code>SlowJet</code> algorithm, this gives the <ei>R</ei> parameter.
181 <parm name="JetMatching:etaJetMax" default="2.5" min="0.1">
182 For both jet algorithms, this defines the maximum pseudorapidity that
183 the detector is assumed to cover. In this context, however, it is tied
184 to the phase space region in which partons have been generated.
185 For the Alpgen-style matching, particles within
186 <ei>etaJetMax + coneRadius</ei> are passed to the jet algorithm,
187 with only jets within <ei>etaJetMax</ei> retained in the merging.
188 For the Madgraph-style matching, only particles within <ei>etaJetMax</ei>
192 <h3>Exclusive mode</h3>
194 The following settings determine whether clustered jets which do not
195 match an original hard parton are allowed. They are typically permitted
196 in the highest jet multiplicity sample, where the parton shower may
197 produce extra hard jets, without risk of double counting. Any
198 extra jet produced by the shower must be softer than any matched light
199 jet, or else the event is vetoed.
201 <modepick name="JetMatching:exclusive" default="2" min="0" max="2">
202 Exclusive or inclusive merging.
204 The merging is run in inclusive mode. All partons must match jets, but
205 additional jets are allowed, provided they are not harder than the
209 The merging is run in exclusive mode. All partons must match jets,
210 and no additional jets are allowed.
213 If <ei>nJet < nJetMax</ei>, then the merging is run in exclusive
214 mode, otherwise it is run in inclusive mode. For Madgraph-style matching,
215 this is checked on an event-by-event basis, which is useful when an LHEF
216 contains a "soup" of partonic multiplicities.
217 If <ei>nJetMax < 0</ei> or <ei>nJet < 0</ei>, then the
218 algorithm defaults to exclusive mode.
222 <modepick name="JetMatching:nJet" default="-1" min="-1">
223 When <code>JetMatching:exclusive = 2</code>, <ei>nJet</ei> indicates
224 the minimum number of additional light jets in the incoming process.
225 This value may be set automatically.
228 <modepick name="JetMatching:nJetMax" default="-1" min="-1">
229 When <code>JetMatching:exclusive = 2</code>, <ei>nJetMax</ei> is used to
230 indicate the maximum number of jets that will be matched.
233 <h3>Jet matching</h3>
235 The following parameters control the criteria for matching a clustered jet
238 <modepick name="JetMatching:jetAllow" default="1" min="1" max="2">
239 Controls which particles are clustered by the jet algorithm.
241 This option explicitly disallows top quarks, leptons and photons. All other
242 particle types are passed to the jet algorithm.
245 No extra particles are disallowed.
249 <h3> Alpgen-specific parameters </h3>
251 <modepick name="JetMatching:jetMatch" default="1" min="1" max="2">
252 Criteria for matching a clustered jet to a parton.
254 This option can be used with both the <code>CellJet</code> and
255 <code>SlowJet</code> algorithms. The <ei>delta R</ei> between each parton
256 and jet is taken, and the minimal value compared against
257 <ei>coneMatchLight * coneRadius</ei> for light jets or
258 <ei>coneMatchHeavy * coneRadiusHeavy</ei> for heavy jets.
259 Note that by default <ei>coneRadiusHeavy = coneRadius</ei>, see below.
260 If below this value, the parton and jet are considered to match.
261 With <code>CellJet</code>, the <ei>delta R</ei> measure is in
262 <ei>(eta, phi)</ei>, while with <code>SlowJet</code> it is in
266 This option can only be used with the <code>SlowJet</code> algorithm.
267 The hard partons are inserted into the parton level event as "ghost"
268 particles, but at the correct <ei>(y, phi)</ei> position. If this
269 particle is then clustered into a jet, it is considered a match.
273 <parm name="JetMatching:coneMatchLight" default="1.5" min="0.1">
274 The <ei>coneMatchLight</ei> parameter used when
275 <code>JetMatching:jetMatch = 1</code>.
278 <parm name="JetMatching:coneRadiusHeavy" default="-1.0">
279 The <ei>coneRadiusHeavy</ei> parameter used when
280 <code>JetMatching:jetMatch = 1</code>. When assigned a negative value,
281 the value of <code>JetMatching:coneRadius</code> is used.
284 <parm name="JetMatching:coneMatchHeavy" default="1.0" min="0.1">
285 The <ei>coneMatchHeavy</ei> parameter used when
286 <code>JetMatching:jetMatch = 1</code>.
289 <h3>Madgraph-specific parameters </h3>
291 <parm name="JetMatching:qCut" default="10.0" min="0.0">
292 k<sub>T</sub> scale for merging shower products into jets.
295 <modepick name="JetMatching:nQmatch" default="5" min="3" max="6">
296 Controls the treatment of heavy quarks.
298 All quarks (except top) are treated as light quarks for matching.
301 Bottom quarks are treated separately. Currently, they are unmatched.
305 <parm name="JetMatching:clFact" default="1.0">
306 The <ei>clFact</ei> parameter determines how jet-to parton matching
307 is done. A match is defined as a squared cluster scale that equals:
308 <br/><ei>|clFact| * qCut</ei> for inclusive mode,
309 <br/><ei>|clFact| * max(qCut,min(p<sub>T</sub>(parton)))</ei>
310 for exclusive mode, <ei>clFact</ei> ≥ 0, or
311 <br/><ei>|clFact| * min(k<sub>T</sub>(parton))</ei> for exclusive mode,
312 <ei>clFact</ei> < 0.
315 <h2>Alpgen-style parton-jet matching and merging</h2>
317 This section describes the Alpgen-style MLM merging algorithm for PYTHIA8.
318 The most common reference to the algorithm is <ref>Man02</ref>. In many
319 respects, however, the implementation provided in the ALPGEN package should
320 be considered the official description of the MLM merging procedure.
321 Although designed primarily to work with events generated with ALPGEN, it
322 can in principle also be used with events from a different source. This
323 should not be done without thought, however, and it is up to the user to
324 understand the details of the algorithm and the implications of using a
325 different hard process generator.
328 First, either the <code>CellJet</code> or <code>SlowJet</code> jet
329 algorithm is chosen. Both of these algorithms have an <ei>R</ei> and
330 an <ei>etaMax</ei> parameter. In addition, <code>CellJet</code> has an
331 <ei>eTmin</ei> and <code>SlowJet</code> has a <ei>pTmin</ei> parameter.
332 These are the primary three parameters of the merging procedure, and in
333 practice are set dependent on the cuts applied to the matrix element (ME)
334 generation. We stress that the merging procedure is not tied to the
335 geometry of a specific physical detector, but only to the match between
336 the original partons and the resulting jets, using standard jet algorithms
337 in the phase space region where partons have been generated.
340 ME samples with different jet multiplicities are run through the event
341 generator, and the generation interrupted after parton showers have been
342 applied, but before resonance decays and beam remnants have been
343 processed. Note in particular that top quarks will not yet be decayed,
344 which may lead to slight differences with the PYTHIA 6 interface included
345 with the ALPGEN package. In what follows, the hardness measure of
346 jets/partons is taken to be <ei>eT</ei> when <code>CellJet</code>
347 is used and <ei>pT</ei> when <code>SlowJet</code> is used. The hard
348 system (ignoring all MPI systems) is then analysed:
351 The particles in the original matrix element process are sorted into
352 light partons, heavy partons and other particles. For backwards
353 compatibility, a light parton is defined as the set <ei>(d, u, s, c,
354 b, g)</ei> with zero mass. A heavy parton is defined as the set
355 <ei>(c, b, t)</ei> with non-zero mass.
358 All particles not originating from the heavy partons or other
359 particles are passed to the jet algorithm and clustered.
362 Clustered jets are matched to the light partons in the original ME
363 process. There are two different methods which can be used:
366 Method 1: The following is done for each parton, in order
367 of decreasing hardness. The <ei>delta R</ei> between the parton
368 and all jets is calculated and the smallest value taken. If
369 this is less than the jet <ei>R</ei> parameter, possibly
370 multiplied by a constant, the jet and parton are considered to
371 match, and the jet is removed from further consideration.
372 Note that for <code>CellJet</code> the <ei>delta R</ei> measure
373 is in <ei>(eta, phi)</ei>, while for <code>SlowJet</code>, it is
374 in <ei>(y, phi)</ei>.
377 Method 2: This method is only possible when using the
378 <code>SlowJet</code> algorithm. Before the clustering is performed,
379 extremely soft "ghost" particles are added to the event at the
380 <ei>(y, phi)</ei> coordinates of the original matrix element
381 partons. If such a particle is clustered into a jet, the parton
382 and jet are considered to match. The idea of "ghost" particles
383 was originally introduced by FastJet as a way to measure jet
384 areas <ref>Cac06</ref> and should not affect clustering with an
385 infrared-safe jet algorithm.
389 If there is a light ME parton remaining which has not been matched
390 to a jet, then the event is vetoed. If all ME partons have been
391 matched to a jet, but there are still some extra jets remaining,
392 then two options are possible:
395 Exclusive mode: the event is vetoed. This is typically used when
396 there are ME samples with higher jet multiplicities, which would
397 fill in the extra jets.
400 Inclusive mode: the event is retained if the extra jets are softer
401 than the softest matched jet. This is typically used when
402 there is no ME sample with higher jet multiplicity, so the parton
403 shower should be allowed to give extra jets.
407 All particles originating from the heavy partons are passed to the
408 jet algorithm and clustered.
411 The clustered jets are again matched to the original partons, but
412 there is no requirement for a match to be present; all matched jets
413 are immediately discarded. The matching procedure is much the same
414 as for light partons, but with two differences when <ei>delta R</ei>
415 matching is used. First, a different <ei>R</ei> parameter than that
416 used by the jet algorithm may optionally be given. Second, all jets
417 that are within the given radius of the parton are matched, not
418 just the one with the smallest <ei>delta R</ei> measure. If there
419 are still extra jets remaining then in exclusive mode the event is
420 immediately vetoed, while in inclusive mode the event is retained if
421 the extra jets are softer than the softest <em>light</em> matched jet.
426 Some different options are provided, specified further above in the
427 parameters section. These are set so that, by default, the algorithm
428 closely follows the official MLM interface provided in the ALPGEN package.
431 All vetoing of events is done through the usual
432 <aloc href="UserHooks">User Hooks</aloc> machinery, and is
433 therefore already taken into account in the cross section. In the output
434 from <code><aloc href="EventStatistics">Pythia::stat()</aloc></code>,
435 the difference between the "Selected" and "Accepted" columns gives the
436 number of events that have not survived the vetoing procedure. It is
437 still the responsibility of the user to add together the results from
438 runs with different jet multiplicities. In the simplest case, when
439 ALPGEN input is used and the hard process parameters are used to guide
440 the merging procedure, it is enough to set the
441 <code>JetMatching:nJetMax</code> parameter.
443 <h2>Madgraph-style parton-jet Merging and Matching</h2>
446 This section describes the Madgraph-style parton-jet matching algorithm
450 First, the k<sub>T</sub> jet algorithm is applied using the PYTHIA8
451 <code>SlowJet</code> implementation. The <code>useStandardR = false</code>
452 is used, ie. the <ei>(delta R)^2</ei> separation is defined as
453 <ei>2 (cosh(delta y) - cos(delta phi))</ei> rather than the more common
454 <ei>(delta y)^2 + delta phi)^2</ei>. The <ei>R</ei>, <ei>etaMax</ei>,
455 and a <ei>pTmin</ei> parameters are specified. By default, <ei>R = 1</ei>
456 and <ei>pTmin = qCut </ei>. It is not recommended to change these.
457 These should match the algorithm parameters used in the Madgraph
458 Matrix Element (ME) generation.
461 ME samples with different jet multiplicities are run through the event
462 generator, and the generation is interrupted after parton showers have
463 been applied, but before resonance decays and beam remnants have been
464 processed. In what follows, the hardness measure of jets/partons is taken
465 to be <ei>k<sub>T</sub></ei> relative to <ei>qCut</ei>.
466 The hard system (ignoring all MPI systems) is analyzed:
469 The hard partons in the original matrix element process, provided by
470 the LHEF, are sorted into light partons, heavy partons and other
471 particles. A heavy parton is defined by the
472 <code>JetMatching:nQmatch</code> or by the <code>maxjetflavor</code>
473 value in the LHEF. <ei>nQmatch</ei> refers to the absolute value of
474 the quark PDG identity code.
477 All partons arising from the parton shower are sorted based on their
478 motherhood. A showered parton arising from a heavy parton or "other"
479 parton classified in the previous step is not passed to the jet
480 algorithm. All other partons are clustered into light jets.
482 <li> It is checked whether there are "too few" or "too many" light jets.
483 If the number of light jets is less than the number of light partons
484 defined by <ei>nQmatch</ei>, the event is vetoed. If the number is
485 larger, the event is vetoed only in exclusive mode (defined below).
487 <li> In exclusive mode, the number of jets matches the number of light
488 partons. In inclusive mode, the jets are re-clustered until the number
489 of jets equals the number of light partons. Next, each light hard
490 parton is clustered, one at a time, with the jets until a match is found.
491 A match is defined as a squared cluster scale that equals:
493 <li><ei>|clFact| * qCut</ei> for inclusive mode,</li>
494 <li><ei>|clFact| * max(qCut,min(p<sub>T</sub>(parton)))</ei>
495 for exclusive mode, <ei>clFact</ei> ≥ 0, or</li>
496 <li><ei>|clFact| * min(k<sub>T</sub>(parton))</ei> for exclusive
497 mode, <ei>clFact</ei> < 0.</li>
499 If no match is found, the event is vetoed. When a parton
500 matches a jet, the jet is removed from the collection, and
501 the process continues. The process terminates when all partons
502 are matched to a jet, or a parton is unmatched.
505 All particles originating from the heavy partons are not used.
508 In exclusive mode, it is expected that ME samples with higher parton
509 multiplicity are available to fill the phase space above <ei>qCut</ei>.
510 The inclusive mode is when there are no such samples, and the parton
511 shower is used to fill the phase space.
514 Some different options are provided, specified further above. These
515 are set so that, by default, the algorithm closely follows the
516 FORTRAN interface <code>ME2Pythia</code> provided in the Madgraph
520 All vetoing of events is done through the usual
521 <aloc href="UserHooks">User Hooks</aloc> machinery, and is
522 therefore already taken into account in the cross section. In the output
523 from <code><aloc href="EventStatistics">Pythia::stat()</aloc></code>,
524 the difference between the "Selected" and "Accepted" columns gives the
525 number of events that have not survived the vetoing procedure. It is
526 still the responsibility of the user to add together the results from
527 runs with different jet multiplicities. In the simplest case, when
528 the hard process parameters are used to guide the merging procedure,
529 events will be matched in the exclusive mode.
533 <h3>A note on combining UserHooks</h3>
535 As have been noted above, the matching is implemented using classes
536 derived from the <code><aloc href="UserHooks">UserHooks</aloc></code>
537 class, thereby gaining access to the event generation process at the
538 relevant locations. For native ALPGEN files, which do not adhere to
539 the Les Houches standards, it is also necessary to intervene with
540 a <code>UserHooks</code>-derived <code>AlpgenHooks</code> to handle
541 the extraction and setting of relevant extra information.
544 One must then combine multiple <code>UserHooks</code> classes,
545 such that the functionality of both is present. A prerequisite
546 is that the different <code>UserHooks</code> classes should be
547 declared with virtual inheritance, e.g.
549 class JetMatching : virtual public UserHooks
551 Without this option, when combining two <code>UserHooks</code>-derived
552 classes, two copies of the base <code>UserHooks</code> class would be
553 created, leading to ambiguities.
556 The two first classes in <code>CombineMatchingInput.h</code> combine
557 ALPGEN input with the two different matching schemes, e.g. for the first
559 class JetMatchingAlpgenInputAlpgen : public AlpgenHooks,
560 public JetMatchingAlpgen {
562 // Constructor and destructor.
563 JetMatchingAlpgenInputAlpgen(Pythia& pythia) : AlpgenHooks(pythia),
564 JetMatchingAlpgen() { }
565 ~JetMatchingAlpgenInputAlpgen() {}
567 virtual bool initAfterBeams() {
568 if (!AlpgenHooks::initAfterBeams()) return false;
569 if (!JetMatchingAlpgen::initAfterBeams()) return false;
572 // Process level vetos.
573 virtual bool canVetoProcessLevel() {
574 return JetMatchingAlpgen::canVetoProcessLevel();
579 This class inherits from both <code>AlpgenHooks</code> and
580 <code>JetMatchingAlpgen</code>. Any functions which are present
581 in both classes should be overridden with a function that calls
582 the different parent methods in the desired order. In the
583 above example, the only shared methods are the constructor and
584 <code>initAfterBeams()</code>.
588 <!-- Copyright (C) 2013 Torbjorn Sjostrand -->