This file is indexed.

/usr/share/doc/pythia8-doc/html/CKKWLMerging.html is in pythia8-doc-html 8.1.86-1.2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
 
<html>
<head>
<title>CKKW-L Merging</title>
<link rel="stylesheet" type="text/css" href="pythia.css"/>
<link rel="shortcut icon" href="pythia32.gif"/>
</head>
<body>
 
<h2>CKKW-L Merging</h2> 
 
CKKW-L merging [<a href="Bibliography.html" target="page">Lon01</a>] allows for a consistent merging of parton 
showers with 
matrix elements to include multiple well-separated partons. The 
algorithm implemented  in PYTHIA is described in [<a href="Bibliography.html" target="page">Lon11</a>]. To 
perform matrix element merging,  the user has to supply LHE 
files [<a href="Bibliography.html" target="page">Alw07</a>] for the hard process  and the corresponding 
process with up to N additional jets. 
 
<p/> The usage of the merging procedure is illustrated in a few 
example main  programs 
(<code>main81.cc</code>, <code>main82.cc</code>, 
<code>main83.cc</code>, <code>main84.cc</code> and <code>main85.cc</code>, 
together with the input files <code>main81.cmnd</code>, 
<code>main82.cmnd</code>, <code>main84.cmnd</code> and 
<code>main85.cmnd</code>). These examples should of course only serve 
as  an illustration, and as such will not make use of the merging in 
all  possible ways. For full generality, the example programs link to 
LHAPDF,  FastJet and HepMC. Of course the user is welcome to  remove 
these dependencies. To remove the FastJet dependence, the functions 
calculating example observables have to be deleted. Removing the 
LHAPDF  dependence requires changing the cmnd input files to choose an 
inbuilt PDF,  as outlined in the 
<a href="PDFSelection.html" target="page">PDF documentation</a>.  The 
HepMC dependence can be removed by erasing the code allowing for HepMC 
output. 
 
<p/> Please note that a detailed tutorial on merging in Pythia is available 
from 
<a href="http://home.thep.lu.se/~torbjorn/pythia8/mergingworksheet8160.pdf"> 
http://home.thep.lu.se/~torbjorn/pythia8/mergingworksheet8160.pdf</a>. 
 
<p/> Three very short LHE files (<code>w+_production_lhc_0.lhe</code>, 
<code>w+_production_lhc_1.lhe</code>, <code>w+_production_lhc_2.lhe</code>) 
are included in the distribution. These files are not intended for 
physics  studies, but only serve as input for the example main 
programs. For  realistic studies, the user has to supply LHE files. 
 
<p/> In the generation of LHE files, the value of the factorisation 
scale used in  the PDFs is not important, since the cross section will 
be multiplied by ratios  of PDFs to adjust to the PYTHIA starting 
scales. The same is true for the  renormalisation scale (and starting 
value <i>&alpha;<sub>s</sub>(M<sub>Z</sub>)</i>)  used to evaluate 
<i>&alpha;<sub>s</sub></i>. Coupling and scale choices by the user 
will be transferred to the merging routines. 
 
<p/> Multi-jet events can suffer from infrared divergences in the 
calculation. Sensible matrix element generator (MEG) outputs should not 
contain phase space points in which the calculation is ill-defined, meaning 
infrared regions need to be removed by cuts. This is most conveniently done 
by disallowing the MEG to produce partons below a 
minimal parton-parton separation in a certain jet algorithm. Using 
dedicated cuts to regularise MEG output is of course possible as well. Any 
regularisation criterion defines the matrix element region: The parts of 
phase space in which the fixed order calculation is considered valid and 
preferable to the parton shower. Matrix element merging is combining 
MEG events in the matrix element region with parton shower events in regions 
outside the regularisation cut (often called parton shower region). Because 
the regularisation cut defines a boundary between the matrix element 
and parton shower regions, i.e. the regions to be merged into one inclusive 
sample, it is usually called <i> merging scale </i>. Since many different 
cut choices may regularise the MEG calculation, many different merging scale 
definitions are possible. A few standard choices are listed below, as well as 
documentation on how to use a user-defined cut criterion. In combining matrix 
element and parton shower regions, the CKKW-L prescription tries to minimise 
the dependence on the merging scale. This can only be achieved if the 
combination of MEG events and parton shower populates the whole phase space. 
Additional cuts on the partons in the LHEF generation should hence be 
avoided as much as possible, meaning that the merging scale cut should always 
pose a more stringent cut than all other cuts on the partons. Of course, if 
the hard process itself is divergent, cuts need to be made. However, this 
should be chosen in such a way as to not exclude regions that will be 
available to the matrix elements with additional jets. An example is QCD 
di-jet production with additional jets: Say the <i>2 &rarr; 2</i> process is 
regularised with a <i>pTmin</i> cut of pTminCut = 100 GeV, and 
the <i>2 - >3</i> sample is regularised with a <i>kTmin</i>-cut of 
kTminCut = 50 GeV. This would mean that when reclustering 
the  emission in the 2 &rarr; 3 sample, we could end up with a 
<i>pT</i> value <i>pTminNow</i> of the 2 &rarr; 2 configuration with 
<i>pTminCut > pTminNow</i>, which is excluded in the 
2 &rarr; 2 sample. Thus, the 2 &rarr; 3 sample will include a 
Sudakov factor  not included in the 2 &rarr; 2 sample, resulting 
in merging scale  dependencies. Such dependencies can be avoided if 
the additional cuts on the hard process are minimal. 
 
<p/> Of course, additional cuts on electroweak particles are 
allowed. These  should be the same for all samples with 
 <i>0 &lt;= n &lt;= N</i>  additional partons. 
 
<p/> If it is not possible to generate LHE files with minimal cuts, 
the user can choose to use the <code>MergingHooks</code> structures in 
order to decide how much influence to attribute to parton shower 
histories in which the reclustered lowest multiplicity process does 
not pass the matrix element cuts. This is  described below. 
 
<p/> When generating LHE files, we advise against putting 
unstable  particles (e.g. massive gauge bosons) in the final state. 
Rather, specify a  resonance by its decay products, e.g. if Les Houches 
events for the <i>pp &rarr; Z + jets &rarr; e+e- + jets</i> process 
are desired, generate the matrix element events with the <i>Z</i> decay 
included. From a physical  point of view, on-shell final massive gauge 
bosons should not be considered  part of a hard process, since only 
the boson decay products will be detectable.  Furthermore, 
non-narrow-width approximation contributions are not present if  the 
ME generator only produces on-shell bosons. Interference effects 
between  different production channels for the decay products would 
also be neglected.  These points seem an unnecessary restriction on 
the accuracy of the ME  calculation.  In addition, there is a 
technical reason for this strategy. Since  some matrix element 
generators choose to put additional information on  intermediate 
bosons into Les Houches events, depending on if they pass a certain 
criterion (e.g. being close to the mass shell), without exact 
knowledge of this  criterion, the only feasible way of bookkeeping the 
hard process is by  identifying outgoing decay products. 
 
<p/> Despite these considerations, (massive) gauge bosons in the final state 
are allowed in the hard process definition. This is useful particularly for 
Higgs physics, when different decays of the Higgs boson need to be simulated 
after the LHEF generation. 
 
<p/> For all merging purposes, processes with different charge of 
outgoing leptons are considered different processes. That means 
e.g. that <i>e+&nu;<sub>e</sub>+ jets</i> and 
<i>e-&nu;&#772;<sub>e</sub> + jets</i> 
are considered independent processes. If the user wishes to generate 
distributions including effects of more than one  process, merged 
samples for all independent processes should be generated  separately 
and added afterwards. Alternatively, to combine simple processes, 
combined LHE files can be used in conjunction with flexible containers (see 
below). 
 
<p/> When the matrix element merging is used to produce HepMC 
[<a href="Bibliography.html" target="page">Dob01</a>] files to be analysed  with RIVET [<a href="Bibliography.html" target="page">Buc10</a>], 
special care  needs to taken in how the cross section is read by RIVET 
(see below). 
 
<p/> To specify the merging conditions, additionally information on 
the merging scale value and the functional definition of the merging 
scale is needed. A few  standard definitions of merging scales are 
available. We hope this makes the user interface less cumbersome. 
 
<p/> Different choices intrinsic to the CKKW-L merging procedure might 
be relevant for the user as well. The base 
class <code>MergingHooks</code> gives the user the opportunity to 
define the functional form of the merging scale.  In the following, 
the usage of the merging machinery to consistently include LHE files 
with additional jets into PYTHIA  will be discussed. 
 
<br/><br/><hr/> 
<h3>Merging scale definitions</h3> 
 
<p/> The quickest way to include processes with additional jets is to 
produce LHE files with one of the standard ways to define the merging 
scale. Three standard ways to define a merging scale (minimal <i>kT</i>, 
minimal evolution <i>pT</i> and by three cuts) are implemented. All of these 
prescriptions are equivalent - different definitions have only been introduced 
for the convenience of users, who might be limited by which cuts can be used 
in the generation of LHE files. Below, we describe how to switch on and use 
these different merging scale definitions. 
 
<h4>Merging with merging scale defined in kT:</h4> 
 
<p/><code>flag&nbsp; </code><strong> Merging:doKTMerging &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
If the additional jets in the LHE files have been regulated by 
a <i>kT</i> cut, the user can supply the merging scale definition by 
setting this flag to on. <i>kT</i> here and below means cutting on 
Durham <i>kT</i> for <i>e+e-</i>  collisions, and cutting on 
longitudinally invariant <i>kT</i> for hadronic  collisions. Please note 
that this particular merging scale definition will check <i>kT</i> between 
all pairs of <i>u,d,c,s,b,g</i> partons. 
   
 
</p> 
Currently, the name longitudinally invariant <i>kT</i> is used 
for a few jet recombination algorithms with slightly different 
jet measures. A specific form can be chosen by setting the switch 
 
<p/><code>mode&nbsp; </code><strong> Merging:ktType &nbsp;</strong> 
 (<code>default = <strong>1</strong></code>; <code>minimum = 1</code>; <code>maximum = 3</code>)<br/>
Precise functional definition of longitudinally 
invariant <i>kT</i>. For e+e- collisions, <i>Durham kT</i> is 
always defined by the square root of <i>min{ 2*min[ </sub> 
E<sub>i</sub><sup>2</sup>, E<sub>j</sub><sup>2</sup>] * [ 1 - 
cos&theta;<sub>ij</sub>] }</i>, so that this switch will have no effect. 
<br/><code>option </code><strong> 1</strong> :  Longitudinally invariant <i>kT</i> is defined by 
the  square root of the minimum of minimal jet kinematic <i>pT</i> 
(<i>p<sub>Tkin,min</sub><sup>2</sup> = min{ p<sub>T,i</sub><sup>2</sup> } 
 </i>) and <i>p<sub>Tlon,min</sub><sup>2</sup> = 
min{ min[ p<sub>T,i</sub><sup>2</sup>, p<sub>T,j</sub><sup>2</sup>] * 
 [ (&Delta;y<sub>ij</sub>)<sup>2</sup> + 
(&Delta;&phi;<sub>ij</sub>)<sup>2</sup> ] / D<sup>2</sup> }</i> , i.e. 
<i>kT = min{ &radic;p<sub>Tkin,min</sub><sup>2</sup>, 
 &radic;p<sub>Tlon,min</sub><sup>2</sup> }</i> for hadronic collisions. Note 
that the true rapidity of partons is used. 
   
<br/><code>option </code><strong> 2</strong> : Longitudinally invariant <i>kT</i> is defined by 
the  square root of the minimum of minimal jet kinematic <i>pT</i> 
(<i>p<sub>Tkin,min</sub><sup>2</sup> = min{ p<sub>T,i</sub><sup>2</sup> 
 } </i>) and <i>p<sub>Tlon,min</sub><sup>2</sup> = 
min{ min[ p<sub>T,i</sub><sup>2</sup>, 
p<sub>T,j</sub><sup>2</sup>] * [ 
(&Delta;&eta;<sub>ij</sub>)<sup>2</sup> + 
(&Delta;&phi;<sub>ij</sub>)<sup>2</sup> ] / D<sup>2</sup> }</i>, i.e. 
<i>kT = min{ &radic;p<sub>Tkin,min</sub><sup>2</sup>, 
 &radic;p<sub>Tlon,min</sub><sup>2</sup> }</i> 
for hadronic collisions. Note that the pseudorapidity of partons is used. 
   
<br/><code>option </code><strong> 3</strong> :  Longitudinally invariant <i>kT</i> is defined by 
the  square root of the minimum of minimal jet kinematic <i>pT</i> 
(<i>p<sub>Tkin,min</sub><sup>2</sup> = min{ p<sub>T,i</sub><sup>2</sup> 
 } </i>) and 
<i>p<sub>Tlon,min</sub><sup>2</sup> = 
min{ min[ p<sub>T,i</sub><sup>2</sup>, 
p<sub>T,j</sub><sup>2</sup>] * [ cosh(&Delta;&eta;<sub>ij</sub>) - 
cos(&Delta;&phi;<sub>ij</sub>) ] / D<sup>2</sup> } </i>,  i.e. 
<i>kT = min{ &radic;p<sub>Tkin,min</sub><sup>2</sup> 
, &radic;p<sub>Tlon,min</sub><sup>2</sup> }</i> 
for hadronic collisions. 
   
   
 
<p/><code>parm&nbsp; </code><strong> Merging:Dparameter &nbsp;</strong> 
 (<code>default = <strong>1.0</strong></code>)<br/>
The value of the <i>D</i> parameter needed in the definition of 
longitudinally invariant <i>kT</i> separation.
   
 
<p/><code>mode&nbsp; </code><strong> Merging:nJetMax &nbsp;</strong> 
 (<code>default = <strong>0</strong></code>; <code>minimum = 0</code>)<br/>
Maximal number of additional jets in the matrix element 
   
 
<p/><code>parm&nbsp; </code><strong> Merging:TMS &nbsp;</strong> 
 (<code>default = <strong>0.0</strong></code>)<br/>
The value of the merging scale. The name is inspired by the scale in 
evolution equations, which is often called 't', and the suffix 'MS' stands 
for merging  scale.  In the particular case of <i>kT</i>-merging, this 
would be the value of the <i>kT</i>-cut  in GeV. For any merging scale 
definition, this input is considered the actual value of the merging 
scale. 
   
 
<p/><code>word&nbsp; </code><strong> Merging:Process &nbsp;</strong> 
 (<code>default = <strong>void</strong></code>)<br/>
The string specifying the hard core process, in MG4/ME notation. 
   
 
</p> 
If e.g. <i>W + jets</i> merging should be performed, set this to 
<code>pp>e+ve</code> (<i>without white spaces or  quotation marks</i>). 
This string may contain resonances in the MG/ME notation, e.g. for merging 
<i>pp&rarr;Z W<sup>+</sup>&rarr;q q&#772; e+&nu;<sub>e</sub> + jets</i>, 
the string <code>pp>(z>jj)(w+>e+ve)</code> would be applicable. 
 
<p/> 
A lot more flexible hard process definitions are possible. To not dwell too 
much on these details here, we will come back to the process string at the end 
of this section. 
 
 
<p/><code>flag&nbsp; </code><strong> Merging:doMGMerging &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
Even easier, but highly non-general, is to perform the merging with 
MadGraph/MadEvent-produced LHE files, with a merging scale defined by 
a <i>kT</i> cut.  For this, set this switch to on. The merging scale 
value will be read from  the +1 jet LHE file by searching for the 
string <code>ktdurham</code>, and  extracting the value from <code> 
value  = ktdurham</code>. Also, the hard  process will be read from 
the +0 jet LHE file, from the line containing  the string <code>@1</code> 
(the tag specifying the first process in the  MadGraph process card). 
For this to work, PYTHIA should be initialised on LHE files called 
<code>NameOfYourLesHouchesFile_0.lhe</code> (+0 jet sample) and 
<code>NameOfYourLesHouchesFile_1.lhe</code> (+1 jet sample) and the 
same naming convention for LHE files with two or more additional jets. 
Since for this option, the merging scale value is read from the 
LHEF, no merging scale value needs to be supplied by setting <code> 
Merging:TMS </code>.  Also, the hard process is read from LHEF, the 
input <code>Merging::Process</code> does not have to be defined. 
However, the maximal number of merged jets still has to be supplied by 
setting <code>Merging:nJetMax</code>. 
   
 
 
<h4>Merging with merging scale defined in Pythia evolution <i>pT</i>:</h4> 
 
If the LHE file has been regularised by cutting on the minimal Pythia 
evolution <i>pT</i> in the state, this can also be used as a merging scale 
right away. For this, change the switch 
 
<p/><code>flag&nbsp; </code><strong> Merging:doPTLundMerging &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
The merging scale is then defined by finding the minimal Pythia evolution 
<i>pT</i> between sets of radiator, emitted and recoiler partons. For this 
particular merging scale definition, <i>u,d,c,s,b,g</i> are considered 
partons. The Pythia evolution <i>pT</i> of a single three-parton set is 
defined by 
<p/> 
<i>pT<sub>evol</sub> = z<sub>ijk</sub>(1-z<sub>ijk</sub>) 
   Q<sub>ij</sub><sup>2</sup></i> for FSR, where <i>i</i> is the radiating 
   parton, <i>j</i> is the emitted parton and <i>k</i> is the recoiler, 
   and 
   <i> Q<sub>ij</sub><sup>2</sup> = 
      (p<sub>i</sub> + p<sub>j</sub>)<sup>2</sup> </i>, and 
   <i>z<sub>ijk</sub> = 
      x<sub>i,jk</sub> / (x<sub>i,jk</sub> + x<sub>j,ik</sub>)</i> with 
   <i>x<sub>i,jk</sub> = 
      2 p<sub>i</sub> (p<sub>i</sub> + p<sub>j</sub> + p<sub>k</sub>) 
        / (p<sub>i</sub> + p<sub>j</sub> + p<sub>k</sub>)<sup>2</sup> </i> 
<p/> 
<i>pT<sub>evol</sub> = (1-z<sub>ijk</sub>) 
   Q<sub>ij</sub><sup>2</sup></i> for ISR, where <i>i</i> is the radiating 
   parton, <i>j</i> is the emitted parton and <i>k</i> is the second 
   initial state parton, and 
   <i> Q<sub>ij</sub><sup>2</sup> = 
     -(p<sub>i</sub> - p<sub>j</sub>)<sup>2</sup> </i>, and 
   <i>z<sub>ijk</sub> = 
     (p<sub>i</sub> - p<sub>j</sub> + p<sub>k</sub>)<sup>2</sup> 
   / (p<sub>i</sub> + p<sub>k</sub>)<sup>2</sup> </i>. 
 
<p/> 
When using this option, the merging scale is defined by the minimum 
<i>pT<sub>evol</sub></i> for all combinations of three partons in the event, 
irrespective of flavour or colour-connections. The merging scale value will 
be read from the <code>Merging:TMS</code> parameter, so that this needs to be 
set just as in the case of the <i>kT</i>-merging prescription. Of course you 
will also need to set <code>Merging:Process</code> and the maximal number of 
additional matrix element jets <code>Merging:nJetMax</code>. 
   
 
<h4>Merging with merging scale defined by a combination of cuts:</h4> 
 
It is possible to regularise QCD divergences in a LHE file by applying cuts 
to the kinematical <i>pT</i> of jets (<i>pT<sub>i</sub></i>), combined 
with a cut on <i> &Delta;R<sub>ij</sub></i> between jets and a cut on 
invariant mass <i> Q<sub>ij</sub></i> of jet pairs. The combination of 
these standard cuts can also serve as a merging scale. For this, use this 
setting 
 
<p/><code>flag&nbsp; </code><strong> Merging:doCutBasedMerging &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
This switch will use cuts on (<i>pT<sub>i</sub></i>), 
<i> &Delta;R<sub>ij</sub></i>  and 
<i> Q<sub>ij</sub></i> to define when parton shower emissions are allowed. 
Please note for this particular merging scale definition, only light jets 
(<i>u,d,c,s,g</i>) are checked. 
   
 
<p/> 
The values of the cuts will then be read from 
 
<p/><code>parm&nbsp; </code><strong> Merging:QijMS &nbsp;</strong> 
 (<code>default = <strong>0.0</strong></code>)<br/>
The value of the invariant mass cut <i> Q<sub>ij</sub></i> of pairs of final 
state partons used in the matrix element generation. 
   
 
<p/><code>parm&nbsp; </code><strong> Merging:pTiMS &nbsp;</strong> 
 (<code>default = <strong>0.0</strong></code>)<br/>
The value of the minimal transverse momentum cut <i> pT<sub>i</sub></i> on 
final state partons, as used in the matrix element generation. 
   
 
<p/><code>parm&nbsp; </code><strong> Merging:dRijMS &nbsp;</strong> 
 (<code>default = <strong>0.0</strong></code>)<br/>
The value of the minimal <i> &Delta;R<sub>ij</sub></i> separation between 
pairs of final state partons used in the matrix element generation, where 
<i> &Delta;R<sub>ij</sub><sup>2</sup> = (&Delta;y<sub>ij</sub>)<sup>2</sup> + 
(&Delta;&phi;<sub>ij</sub>)<sup>2</sup></i>. 
   
 
<p/> 
With knowledge of these values, and <code>Merging:doCutBasedMerging</code>, 
Pythia will use these cuts as a separation between matrix element phase space 
and parton shower region. If e.g. the Les Houches Events have been generated 
with the cuts <i> &Delta;R<sub>ij</sub> = 0.1 </i>, 
<i>pT<sub>i</sub>= 20 GeV</i> and <i> Q<sub>ij</sub> = 40 GeV</i>, set 
<code>Merging:QijMS=40.</code>, 
<code>Merging:pTjMS=20.</code>, 
<code>Merging:dRijMS=0.1</code> to perform a cut-based merging. Of course 
you will also need to set <code>Merging:Process</code> and the 
maximal number of additional matrix element jets 
<code>Merging:nJetMax</code>. 
 
<h4>Les Houches events outside the matrix element region</h4> 
 
</p> 
Before continuing, we would like to point out that in general, the user 
should make sure that the events in the Les Houches file are actually 
calculated using the regularisation cut definition and value(s) supplied to 
Pythia as merging scale definition and value(s). However, if LH files with 
a large number of events and loose merging scale cuts are available, it 
might be useful to choose a higher merging scale value, e.g. for merging 
scale variations as part of uncertainty assessments. If CKKW-L merging is 
enabled, Pythia will by default check if events read from Les Houches file 
are in the matrix element region as defined by the merging scale definition 
and merging scale value. Events outside the matrix element region will be 
discarded. This will lead to warnings of the form "<code>Les Houches Event 
fails merging scale cut. Cut by rejecting event</code>". These warnings 
should, in this case, rather be regarded as information. 
To change the default behaviour, use the flag 
 
<p/><code>flag&nbsp; </code><strong> Merging:enforceCutOnLHE &nbsp;</strong> 
 (<code>default = <strong>on</strong></code>)<br/>
This will check if the events read from LHE file are in the matrix element 
region as defined by the merging scale definition and value(s). If on, LHE 
input outside the matrix element region will be rejected. If off, every 
event is assumed to pass the merging scale cut. 
   
 
<h4>Defining the hard process</h4> 
 
To perform CKKW-L matrix element merging, the user has to decide on a hard 
process, and communicate this choice to Pythia. This is done by setting the 
input <code>Merging:Process</code> 
  
<p/> 
For single processes in the Standard Model or the MSSM, MG4/ME notation is 
applicable. However, for some purposes, using a single simple process 
string is not satisfactory. Mixed W<sup>+</sup> and W<sup>-</sup> events 
in a single LHE file is a common example. For this case, it would of course 
be perfectly allowed to perform twice, once for W<sup>+</sup> production and 
once for W<sup>-</sup> production, and then add the results. Nevertheless, it 
seems reasonable to alleviate difficulties by allowing for less restrictive 
hard process definitions. Two generalisations of the process tag are 
available: Containers and user-defined particle tags. The syntax of these 
settings is described below. 
 
<p/> 
In case you want multiple processes in a LHE file to be treated on equal 
footing (e.g. <i>W<sup>+</sup> + jets</i> and 
<i>W<sup>-</sup> + jets</i>), you should use flexible containers do 
specify the hard process. So far, we allow the use of the containers 
<code>LEPTONS</code>, <code>NEUTRINOS</code>, <code>BQUARKS</code>. If you 
use these containers, the hard process definition is relatively flexible, 
meaning that Pythia will attempt a merging of QCD jets for each event in 
the LHE file, and assume that all particles matching one of the containers 
are products of the hard process. This is best explained by examples. 
If you want to have both <i>pp &rarr; e+ &nu;<sub>e</sub> + jets</i> 
and <i>pp &rarr; e- &nu;&#772;<sub>e</sub> + jets</i> events in a single 
file, you can set <code>Merging:Process=pp>LEPTONS,NEUTRINOS</code> as hard 
process (note that for readability, you are allowed to use commata to separate 
container names). Combining e.g. the processes 
<i>pp &rarr; e+ &nu;<sub>e</sub></i> and 
<i>pp &rarr; &mu;+ &nu;<sub>&mu;</sub></i> is possible with the hard process 
definition <code>pp>LEPTONS,NEUTRINOS</code>. 
 
<p/> 
For maximal flexibility, the definition of the hard process by these 
containers does not mean that each Les Houches event needs to contain 
particles to match each container. It is enough if one container is matched. 
This means that with the string <code>pp>LEPTONS,NEUTRINOS</code>, you can 
immediately process <i>pp &rarr; e+ e- </i> events mixed with 
<i>pp &rarr; e+ &nu;<sub>e</sub></i> events, since particles matching at 
least one container can be found in both cases. Another example for the usage 
of containers is mixing <i>pp &rarr; e+ &nu;<sub>e</sub></i> and 
<i>pp &rarr; tt&#772; &rarr; e+ &nu;<sub>e</sub> e- &nu;&#772;<sub>e</sub> 
  bb&#772;</i>. This can be accommodated by the hard process string 
<code>Merging:Process=pp>LEPTONS,NEUTRINOS,BQUARKS</code>. 
 
<p/> 
There is however a conceptual limitation to containers: The hard process 
definition is necessary to ensure that when constructing lower multiplicity 
states (that will be used to calculate the correct merging weight), the 
structure of the hard process will be preserved. If e.g. we want the hard 
process to be <i>pp &rarr; Z &rarr; bb&#772; </i>, we should ensure that 
the lowest multiplicity state contains a colour-singlet bb&#772;-pair. When 
reconstructing intermediate lower multiplicity states from multi-jet matrix 
elements, we should thus always be able to find at least one bb&#772;-pair. By 
mixing different processes in a LHE file, this requirement might already be 
violated at the level of Les Houches events. Flexible containers cannot give 
strong conditions which flavours should be preserved in the construction of 
the hard process. In order to avoid non-sensible results, it is hence <i> 
assumed that all</i> particles matching any of the containers will be part 
of the lowest multiplicity process. This implies that if you decide to use the 
<code>BQUARKS</code> container, all b-quarks in the LHE file will be 
interpreted as hard process particles, and never as additional radiation. 
 
<p/> 
Another way to specify the hard process particles is to explicitly define the 
particle names and identifiers. This is necessary if the matrix element 
merging in Pythia does not contain the particles of interest. To make sure 
that the hard process is still treated correctly, it is possible to define 
particles in the process string. If you e.g. want the hard process to contain 
a particle "zeta~" with PDG identifier "12345", produced in proton collisions, 
you have to include a user-defined particle tag by setting the process string 
to <code>pp>{zeta~,12345}</code>. The  user-defined particle is enclosed in 
curly brackets, with syntax 
<code>{particle_name,particle_identifier}</code>, where "particle_name" 
and "particle_identifier" are the particle name and particle identifier used 
for this particle in the input LHE file. User-defined particles are only 
allowed in the final state. You are free to fix user-defined particles with 
more common ones, as long as user-defined particles are put before more common 
particles in the process string. This means that if you e.g. wanted the hard 
process to contain a graviton in association with a positron and an 
electron-neutrino, you have to define the hard process as 
<code>pp>{G,39}e+ve</code>. 
 
<p/> 
Below you can find a list of particles predefined in the merging. If you wish 
to include a hard process with different final state particles, you may use 
the "curly bracket notation" outlined above. 
 
<p/> 
The set of incoming particles us limited to: 
<code>e-</code> (electron), <code>e+</code> (positron), <code>mu-</code> 
(muon), <code>mu+</code> (antimuon), <code>p</code> (proton, container to 
hold all initial state coloured particles),  <code>p~</code> (identical to 
<code>p</code> container). 
 
<p/> 
The following intermediate particles are allowed: 
<code>a</code> (photon), <code>z</code> (Z boson), 
<code>w-</code> (W<sup>-</sup> boson), <code>w+</code> (W<sup>+</sup> boson), 
<code>h</code> (scalar Higgs boson), <code>W</code> (container to hold both 
W<sup>-</sup> and W<sup>+</sup> boson), <code>t</code> (top quark), 
<code>t~</code> (anti-top), 
<code>dl</code>, <code>dl~</code>, <code>ul</code>, <code>ul~</code>, 
<code>sl</code>, <code>sl~</code>, <code>cl</code>, <code>cl~</code>, 
<code>b1</code>, <code>b1~</code>, <code>t1</code>, <code>t1~</code>, 
<code>dr</code>, <code>dr~</code>, <code>ur</code>, <code>ur~</code>, 
<code>sr</code>, <code>sr~</code>, <code>cr</code>, <code>cr~</code>, 
<code>b2</code>, <code>b2~</code>, <code>t2</code>, <code>t2~</code> 
(all MSSM squarks). 
 
<p/> 
We have pre-defined the outgoing particles: 
<code>e+</code>, <code>e-</code>, <code>ve~</code>, 
<code>ve</code>, <code>mu+</code>, <code>mu-</code>, 
<code>vm~</code>, <code>vm</code>, <code>ta+</code>, <code>ta-</code>, 
<code>vt~</code>, <code>vt</code> (all SM leptons and neutrinos), 
<code>j~</code> (container to hold all final state coloured particles), 
<code>j</code> (container to hold all final state coloured particles), 
<code>NEUTRINOS</code> (container to hold all final state neutrinos and 
anti-neutrinos), <code>LEPTONS</code> (container to hold all final state 
leptons and anti-leptons), <code>BQUARKS</code> (container to hold final 
state b-quarks), <code>d~</code>, <code>d</code>, <code>u~</code>, 
<code>u</code>, <code>s~</code>, <code>s</code>, <code>c~</code>, 
<code>c</code>, <code>b~</code>, <code>b</code>, <code>t~</code>, 
<code>t</code> (all SM quarks), <code>a</code>, <code>z</code>, 
<code>w-</code>, <code>w+</code> (all SM electro-weak bosons), 
<code>h</code> (scalar Higgs boson), <code>W</code> (container to hold both 
W<sup>-</sup> and W<sup>+</sup> boson), <code>n1</code> (MSSM neutralino), 
<code>dl~</code>, <code>dl</code>, <code>ul~</code>, <code>ul</code>, 
<code>sl~</code>, <code>sl</code>, <code>cl~</code>, <code>cl</code>, 
<code>b1~</code>, <code>b1</code>, <code>t1~</code>, <code>t1</code>, 
<code>dr~</code>, <code>dr</code>, <code>ur~</code>, <code>ur</code>, 
<code>sr~</code>, <code>sr</code>, <code>cr~</code>, <code>cr</code>, 
<code>b2~</code>, <code>b2</code>, <code>t2~</code>, <code>t2</code> 
(all MSSM squarks). Other outgoing particles are possible if you use the 
"curly bracket notation" described earlier. 
 
<br/><br/><hr/> 
<h3>Histogramming the events</h3> 
After the event has been processed, histograms for observables of interest 
need to be filled. In order to achieve good statistical accuracy for all jet 
multiplicities and all subprocesses contributing to one jet multiplicity, 
generally a fixed number of unit-weighted events is read from each Les 
Houches Event file. To then arrive at the correct prediction, for each of 
these events, histogram bins should be filled with the corresponding cross 
section, or weighted with unit weight and normalised at the end to 
the generated cross section for each jet multiplicity separately. 
 
<p/> Still another, even more important, event weight that has to 
applied on an  event-by-event basis is the CKKW-L-weight. This 
corrective weight is the main  outcome of the merging procedure and 
includes the correct no-emission  probabilities, PDF weights and 
&alpha;<sub>s</sub> factors. This means that the merging 
implementation will generate weighted events. The CKKW-L-weight can be 
accessed by the following function: 
 
<p/><strong> double Info::mergingWeight() &nbsp;</strong> <br/> 
Returns the CKKW-L weight for the current event. 
 
<p/> Note that to avoid confusion, this function does not include the 
the weight of a phase space point (given 
by <strong>Info::weight()</strong>). This weight will differ from 
unity when reading in weighted Les Houches events. In this case, the 
full weight with which to fill histogram bins is 
<strong>Info::mergingWeight() * Info::weight()</strong>. 
 
<p/> Finally, to arrive at a correct relative normalisation of the 
contributions from different number of additional jets in the matrix 
element, each histogram should be rescaled with the accepted cross 
section given by 
<strong>Info::sigmaGen()</strong>. The accepted cross section includes 
the  effect of vetoes generating Sudakov form factors for the matrix 
elements, and  is in general only known after the run. 
 
<p/> This final step can of course be skipped if the accepted cross 
section had been estimated before the histogramming run, and  histogram 
bins had instead been filled with the weight 
<strong>Info::mergingWeight() * &sigma;<sub>est</sub>(number of 
additional jets in current ME sample)</strong>. This is the way HepMC 
events should be weighted to produce correct relative weights of 
events (see below, and particularly examine the example programs 
<code>main84.cc</code> and <code>main85.cc</code>). 
 
<p/> Examples how to use these options are given in <code>main81.cc</code> 
(<i>kT</i> merging), <code>main84.cc</code> (automatic MG/ME merging 
for RIVET usage), and <code>main85.cc</code> (HepMC output for RIVET usage). 
 
<br/><br/><hr/> 
<h3>Merging with user-defined merging scale function</h3> 
 
<p/> For all other merging scale definitions, the procedure is 
slightly more  complicated, since the user has to write a small piece 
of code defining the  merging scale. To allow for a user defined 
procedure, set the input 
 
<p/><code>flag&nbsp; </code><strong> Merging:doUserMerging &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
General user defined merging on/off. 
   
 
</p> 
Then, set 
the <strong>Merging:nJetMax</strong>, <strong>Merging:TMS</strong> 
and <strong>Merging:Process</strong> input as before. 
 
<p/> Since during execution, PYTHIA needs to evaluate the merging 
scale with the  definition of the user, the user interface is designed 
in a way similar to the 
<code>UserHooks</code> strategy. The class controlling the merging 
scale  definition is called <code>MergingHooks</code>. 
 
<h4>Initialisation</h4> 
 
<p/> To initialise the merging with user-defined merging scale, we 
should construct a class derived from <code>MergingHooks</code>, with 
a constructor and destructor 
 
<p/> 
<a name="method1"></a>
<p/><strong>MergingHooks::MergingHooks() &nbsp;</strong> <br/>
   
<a name="method2"></a>
<p/><strong>virtual MergingHooks::~MergingHooks() &nbsp;</strong> <br/>
   
The constructor and destructor do not need to do anything. 
 
<p/> For the class to be called during execution, a pointer to an 
object of the class should be handed in with the 
<br/><code><a href="ProgramFlow.html" target="page"> 
Pythia::setMergingHooksPtr( MergingHooks*)</a></code> method. 
 
An examples of this procedure are given in <code>main82.cc</code>. 
 
<h4>Defining a merging scale</h4> 
 
<p/> Then, in the spirit of the <code>UserHooks</code> class, the user 
needs to  supply the process to be merged by defining a methods to 
evaluate the merging scale variable. 
 
<a name="method3"></a>
<p/><strong>virtual double MergingHooks::tmsDefinition(const Event& event) &nbsp;</strong> <br/>
This method will have to calculate the value of the merging scale 
defined in  some variable from the input event record. An example of 
such a function is  given in <code>main82.cc</code>. 
   
 
<p/> The base class <code>MergingHooks</code> contains many functions 
giving  information on the hard process, to make the definition of the 
merging scale as easy as possible: 
 
<a name="method4"></a>
<p/><strong>int MergingHooks::nMaxJets() &nbsp;</strong> <br/>
Return the maximum number of additional jets to be merged. 
   
 
<a name="method5"></a>
<p/><strong>int MergingHooks::nHardOutPartons() &nbsp;</strong> <br/>
Returns the number of outgoing partons in the hard core process. 
   
 
<a name="method6"></a>
<p/><strong>int MergingHooks::nHardOutLeptons() &nbsp;</strong> <br/>
Returns the number of outgoing leptons in the hard core process. 
   
 
<a name="method7"></a>
<p/><strong>int MergingHooks::nHardInPartons() &nbsp;</strong> <br/>
Returns the number of incoming partons in the hard core process. 
   
 
<a name="method8"></a>
<p/><strong>int MergingHooks::nHardInLeptons() &nbsp;</strong> <br/>
Returns the number of incoming leptons in the hard core process. 
   
 
<a name="method9"></a>
<p/><strong>int MergingHooks::nResInCurrent() &nbsp;</strong> <br/>
The number of resonances in the hard process reconstructed from the 
current event. If e.g. the ME configuration was 
<i>pp &rarr; (w+&rarr;e+ve)(z &rarr; mu+mu-)jj</i>, and the ME generator put 
both intermediate bosons into the LHE file, this will return 2. 
   
 
<a name="method10"></a>
<p/><strong>double MergingHooks::tms() &nbsp;</strong> <br/>
 Returns the value used as the merging scale. 
   
 
<p/> Filling output histograms for the event then proceeds along the 
lines described above in "Histogramming the events". 
 
<p/> The full procedure is outlined in <code>main82.cc</code>. Special 
care needs to be  taken when the output is stored in the form of HepMC 
files for RIVET usage. 
 
<h4>Defining a cut on lowest jet multiplicity events</h4> 
 
<p/> It can sometimes happen that when generating LHE files, a fairly 
restrictive cut has been used when generating the lowest multiplicity 
matrix element  configurations. Then, it can happen that states that 
are (in the generation of a parton shower history) constructed by 
reclustering from higher multiplicity  configurations, do not pass 
this matrix element cut. 
 
<p/> Consider as an example  pure QCD dijet merging, when up to one 
additional jet should be merged.  Three-jet matrix element 
configurations for which the reclustered two-jet state does not pass 
the cuts applied to the two-jet matrix element would never have  been 
produced by showering the two-jet matrix element. This means that the 
three-jet matrix element includes regions of phase space that would 
never have  been populated by the parton shower. Thus, since the 
matrix element phase space is larger than the shower phase space, 
merging scale dependencies are expected.  A priori, this is not 
troublesome, since the aim of matrix element merging is  to include 
regions of phase space outside the range of the parton shower 
approximation into the shower. An example is the inclusion of 
configurations  with only unordered histories. 
 
<p/> Clearly, if the parton shower phase space is very constrained by 
applying  stringent cuts to the two-jet matrix element, merging scale 
dependencies can  become sizable, as was e.g. seen in [<a href="Bibliography.html" target="page">Lon11</a>] 
when forcing shower emissions to be ordered both in the evolution 
variable and in rapidity. To  influence the effect of large phase 
space differences for shower emissions and matrix element 
configurations due to LHEF generation cuts, the user has to  write a 
small piece of code overwriting method 
 
<a name="method11"></a>
<p/><strong>virtual double MergingHooks::dampenIfFailCuts(const Event& event) &nbsp;</strong> <br/>
multiplicity  reclustered state as an input Event. From this input 
event, the user can then check if matrix element cuts are 
fulfilled. The return value will be internally multiplied to the 
CKKW-L weight of the current event. Thus, if the user wishes  to 
suppress contributions not passing particular cuts, a number smaller 
than  unity can be returned. 
   
 
<p/> Note that this method gives the user access to the lowest 
multiplicity state,  which ( e.g. in the case of incomplete histories) 
does not have to be a <i>2 &rarr; 2</i> configuration. Also, changing the 
weight of the current event by  hand is of course a major intervention 
in the algorithm, and should be  considered very carefully. Generally, 
if this facility would have to be used extensively, it is certainly 
preferable to be less restrictive when applying  additional, 
non-merging-scale-related cuts to the matrix element. 
 
<p/> An example how to force a cut on lowest multiplicity reclustered 
states for pure QCD matrix element configurations is given by 
<code>main83.cc</code> (to be used with e.g. <code>main82.cmnd</code>). 
 
<h4>Influencing the construction of all possible histories</h4> 
 
<p/> Even more powerful - and dangerous - is influencing the construction 
of histories directly. This should only be attempted by expert users. If you 
believe manipulations completely unavoidable, we advise you to take great care 
when redefining the following functions. 
 
<a name="method12"></a>
<p/><strong>virtual bool MergingHooks::canCutOnRecState() &nbsp;</strong> <br/>
In the base class this method returns false. If you redefine it 
to return true then the method <code>doCutOnRecState(...)</code> 
will be called for each reclustered state encountered in the generation of 
all possible histories of the matrix element state. 
   
 
<a name="method13"></a>
<p/><strong>virtual bool MergingHooks::doCutOnRecState(const Event& event) &nbsp;</strong> <br/>
This routine will be supplied internally with every possible reclustered 
event that can be reached by reclustering any number of partons in 
the matrix element input state. The new, reclustered, states can then be 
analysed. If the method returns false, the history to which the state belongs 
will be treated as if it were unordered, i.e. this path will only be chosen 
if no other histories are available. In this way, the number of histories 
not fulfilling the user criterion will be minimised. 
   
 
<p/> 
Clearly, these methods are highly intrusive. It could e.g. happen that no 
history is allowed, which would make merging impossible. One example where 
this method could be useful is if cuts on the core <i>2 &rarr; 2</i> 
processes have to be checked, and the method 
<code>MergingHooks::dampenIfFailCuts(const Event& event)</code> is not 
sufficiently effective. 
 
<h4>Defining the hard process matrix element</h4> 
 
<p/> The MergingHooks class also allows the expert user to define the matrix 
element of the hard process, by defining the method 
 
<a name="method14"></a>
<p/><strong>virtual double MergingHooks::hardProcessME(const Event& inEvent) &nbsp;</strong> <br/>
This routine will be supplied internally with the reconstructed 
lowest-multiplicity event. From this, it is possible to calculate the squared 
matrix element of the hard process, by using the information stored in the 
event record. The function should return a <code>double</code> value that 
corresponds to the matrix element at the phase space point given by the input 
event record. This number will then be multiplied to the product of splitting 
functions that define the probability of the current path of the parton 
shower history. In this way, the hard process configuration can be taken into 
account when choosing the parton shower history, which is, internally, used 
to generate the "merging weight". 
   
 
<p/> The inclusion of the hard process matrix element into the choice 
of histories becomes relevant when the hard process matrix element has very 
strong phase space dependencies. QCD dijet cross sections for example strongly 
depend on the transverse momentum of the jets. So far, the authors have not 
encountered any changes upon inclusion of the full hard process matrix 
element, even for the QCD dijet case. 
 
<br/><br/><hr/> 
<h3>Matrix element merging and HepMC output for RIVET</h3> 
 
Examples how to produce matrix element merged events to be analysed 
with RIVET are given by <code>main84.cc</code> and <code>main85.cc</code>. 
 
<p/> The main issue is that the output of separate RIVET runs can not 
in general be combined. To perform a matrix element merging, we 
however need to runs over  different LHE files. The solution to this 
problem (so far) is to only perform  one RIVET run for all matrix 
elements, i.e. print the events for all ME parton  multiplicities, 
with the correct weights, to a single HepMC file. Since the correct 
weight includes the cross section of the different samples after 
Sudakov vetoes --- which is not a priori known --- the cross sections 
have to be  estimated in a test run, before the actual production run 
is performed. Finally, the cross section of the last event in the 
HepMC file has to be taken as the  full merged cross section 
<i>sigma_merge = Sum_{i=0}^N Sum_{j=0}*^{nEvents} 
sigma_est(i)*wckkwl(j)</i>. 
 
<p/> This procedure is outlined in <code>main84.cc</code>. 
 
Input LHE files with only very inclusive cuts pose further difficulties. For 
such files (which were already addressed under the heading <strong>Les Houches 
events outside the matrix element region</strong>), the cross section after 
the merging scale cut is not known before the cut is performed. Using Pythia's 
<code>UserHooks</code> facilities, it is possible to produce a valid estimate 
of the cross section after cuts. This however entails a careful cut definition 
by the user, which might become cumbersome for some in-built merging scale 
definitions. A reasonable alternative is using the switch 
 
<p/><code>flag&nbsp; </code><strong> Merging:doXSectionEstimate &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
If on, estimate cross section after merging scale cut. This switch has to be 
used in conjunction with a merging scale definition (e.g. 
<code>Merging:doPTLundMerging = on</code>). Then, this merging scale 
definition will be used as a cut on the input events. After the requested 
number of Monte Carlo events, the cross section after the cut can be extracted 
by inferring the <code>Info::sigmaGen()</code> method, and the number of 
accepted events by using <code>Info::nAccepted()</code> 
   
 
<p/> 
This switch also relies on knowledge on how many partons a LHE file should 
contain. This is important for real-emission kinematics in the case of 
NLO merging. The number of (additional) partons in a LHE file can be set with 
 
<p/><code>mode&nbsp; </code><strong> Merging:nRequested &nbsp;</strong> 
 (<code>default = <strong>-1</strong></code>; <code>minimum = -1</code>)<br/>
Exact number of additional jets requested for a particular LHE file. If 
a file should for example only contain <i>W<sup>+</sup> g g </i> events, 
this switch should be set to "2" for this LHE file. For NLO merging 
schemes (see <a href="NLOMerging.html" target="page">NLO Merging</a>), this number has to 
be set. 
   
 
<p/> 
The usage of these switches to obtain the necessary cross section estimate is 
illustrated in <code>main85.cc</code>. The example <code>main85.cc</code> 
program is intended as a "front-end" for CKKW-L merging in Pythia8, so we will 
discuss the program briefly. <code>main85.cc</code> should be used together 
with an input file (like <code>main85.cmnd</code>). The executable should be 
invoked with three arguments: the input file, the "name" of the input LHE 
files, and the name of the output HepMC event file. To use the LHE files that 
are shipped with the Pythia distribution, a valid usage would be 
</p> 
<code>./main85.exe ./main85.cmnd ./w_production ./myhepmc.hepmc</code> 
</p> 
If you want to use other input LHE files, note 
that <code>main85.cc</code> assumes the naming 
convention <i>name_tree_#nAdditionalJets.lhe</i>. All settings can 
be included though the input file, so that <code>main85.cc</code> does not 
have to be changed explicitly. <code>main85.cc</code> first switches off 
showers, multiparton interactions and hadronisation, and estimates the cross 
sections (after enforcing the merging scale cut) of samples for different 
numbers of additional jets. Then, showers, MPI and hadronisation are switched 
on again, and the CKKW-L merging procedure is performed. Events will be read 
in a decreasing sequence of jet multiplicities, which also means that e.g. 
events with two additional partons in the LHE file will be printed to the 
HepMC file before events with one additional parton. 
 
<br/><br/><hr/> 
<h3>Further variables</h3> 
 
For more advanced manipulations of the merging machinery, all 
parameter  changes that were investigated in [<a href="Bibliography.html" target="page">Lon11</a>] are 
supplied. Please  check [<a href="Bibliography.html" target="page">Lon11</a>] for a detailed discussion of 
the switches. 
 
<p/> These switches allow enthusiastic users to perform a systematic 
assessment of the merging prescription. Apart from this, we advise the 
non-expert user to keep the default values. 
 
<p/><code>mode&nbsp; </code><strong> Merging:nQuarksMerge &nbsp;</strong> 
 (<code>default = <strong>5</strong></code>; <code>minimum = 2</code>; <code>maximum = 5</code>)<br/>
This switch controls which quarks flavours (labelled by PDG id's) are 
considered additional partons. If e.g. set to 4, then u-, d-, c- and s-quarks 
will be merged, while b-quarks will not be considered in the merging 
(corresponding to a 4-flavour merging scheme). We advise caution when 
changing this number. In particular, please ensure that the allowed flavour 
for additional partons in the input LHE file does not exceed this value, since 
unnecessary double-counting might occur otherwise. 
   
 
<p/><code>flag&nbsp; </code><strong> Merging:includeMassive &nbsp;</strong> 
 (<code>default = <strong>on</strong></code>)<br/>
If on, use the correct massive evolution variable and massive 
splitting kernels in the reconstruction and picking of parton shower 
histories of the matrix  element. If off, reconstruct evolution 
scales, kinematics and splitting kernels  as if all partons were 
massless. 
   
 
<p/><code>flag&nbsp; </code><strong> Merging:enforceStrongOrdering &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
If on, preferably pick parton shower histories of the matrix element 
which  have strongly ordered consecutive splittings, i.e. paths in 
which consecutive reclustered evolution scales are separated by a 
user-defined factor. 
   
 
<p/><code>parm&nbsp; </code><strong> Merging:scaleSeparationFactor &nbsp;</strong> 
 (<code>default = <strong>1.0</strong></code>; <code>minimum = 1.0</code>; <code>maximum = 10.0</code>)<br/>
The factor by which scales should differ to be classified as strongly 
ordered. 
   
 
<p/><code>flag&nbsp; </code><strong> Merging:orderInRapidity &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
If on, preferably pick parton shower histories of the matrix element 
with  consecutive splittings ordered in rapidity and <i>pT</i>. 
   
 
<p/><code>flag&nbsp; </code><strong> Merging:pickByFullP &nbsp;</strong> 
 (<code>default = <strong>on</strong></code>)<br/>
If on, pick parton shower histories of the matrix element by the full 
shower  splitting kernels, including potential ME corrections and 
Jacobians from joined evolution measures. 
   
 
<p/><code>flag&nbsp; </code><strong> Merging:pickByPoPT2 &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
If on, pick parton shower histories of the matrix element by the 
shower  splitting kernels divided by the evolution <i>pT</i>. 
   
 
<p/><code>flag&nbsp; </code><strong> Merging:pickBySumPT &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
If on, exclusively pick parton shower histories of the matrix element 
for which have the smallest sum of scalar evolution <i>pT</i> for 
consecutive splittings has been calculated. 
   
 
<p/><code>flag&nbsp; </code><strong> Merging:includeRedundant &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
If on, then also include PDF ratios and <i>&alpha;<sub>s</sub></i> 
factors in the  splitting probabilities used for picking a parton shower 
history of the matrix  element, when picking histories by the full shower 
splitting probability. As argued in  [<a href="Bibliography.html" target="page">Lon11</a>], this should not 
be done since a reweighting with PDF ratios and <i>&alpha;<sub>s</sub></i> 
factors will be performed. However, it can give useful insight in how 
sensitive the results  are to the prescription on how to choose PS 
histories. 
   
 
<p/><code>parm&nbsp; </code><strong> Merging:nonJoinedNorm &nbsp;</strong> 
 (<code>default = <strong>1.0</strong></code>; <code>minimum = 0.0</code>; <code>maximum = 10.0</code>)<br/>
Normalisation factor with which to multiply splitting probability for 
splittings without joined evolution equation. 
   
 
<p/><code>parm&nbsp; </code><strong> Merging:fsrInRecNorm &nbsp;</strong> 
 (<code>default = <strong>1.0</strong></code>; <code>minimum = 0.0</code>; <code>maximum = 10.0</code>)<br/>
Normalisation factor with which to multiply splitting probability for 
final state splittings with an initial state recoiler. 
   
 
<p/><code>parm&nbsp; </code><strong> Merging:aCollFSR &nbsp;</strong> 
 (<code>default = <strong>1.0</strong></code>; <code>minimum = 0.0</code>; <code>maximum = 10.0</code>)<br/>
Factor with which to multiply the scalar <i>pT</i> of a final state 
splitting, when choosing the history by the smallest sum of scalar 
<i>pT</i>. Default value taken from Herwig++ [<a href="Bibliography.html" target="page">Tul09</a>]. 
   
 
<p/><code>parm&nbsp; </code><strong> Merging:aCollISR &nbsp;</strong> 
 (<code>default = <strong>0.9</strong></code>; <code>minimum = 0.0</code>; <code>maximum = 10.0</code>)<br/>
Factor with which to multiply the scalar <i>pT</i> of an initial state 
splitting, when choosing the history by the smallest sum of scalar 
<i>pT</i>. Default value taken from Herwig++ [<a href="Bibliography.html" target="page">Tul09</a>]. 
   
 
<p/><code>mode&nbsp; </code><strong> Merging:unorderedScalePrescrip &nbsp;</strong> 
 (<code>default = <strong>0</strong></code>; <code>minimum = 0</code>; <code>maximum = 1</code>)<br/>
When the parton shower history of the matrix element contains a 
sequence of splittings which are not ordered in evolution <i>pT</i> 
(called an unordered history), this sequence is interpreted as a combined 
emission. Then, a decision on which starting scale for trial emissions 
off reconstructed states in this sequence of unordered splittings has 
to be made. Two options are available: 
<br/><code>option </code><strong> 0</strong> :  Use larger of the two reconstructed (unordered) 
scales as  starting scale. 
   
<br/><code>option </code><strong> 1</strong> :  Use smaller of the two reconstructed (unordered) 
scales as  starting scale. 
   
   
 
<p/><code>mode&nbsp; </code><strong> Merging:unorderedASscalePrescrip &nbsp;</strong> 
 (<code>default = <strong>1</strong></code>; <code>minimum = 0</code>; <code>maximum = 1</code>)<br/>
Prescription which scale to use to evaluate <i>&alpha;<sub>s</sub></i> 
weight for  splittings in a sequence of splittings which are not ordered 
in evolution <i>pT</i>. 
<br/><code>option </code><strong> 0</strong> :  Use the combined splitting scale as argument in 
<i>&alpha;<sub>s</sub></i>, for both splittings. 
   
<br/><code>option </code><strong> 1</strong> :  Use the true reconstructed scale  as as argument in 
<i>&alpha;<sub>s</sub></i>, for each splitting separately. 
   
   
 
<p/><code>mode&nbsp; </code><strong> Merging:unorderedPDFscalePrescrip &nbsp;</strong> 
 (<code>default = <strong>0</strong></code>; <code>minimum = 0</code>; <code>maximum = 1</code>)<br/>
Prescription which scale to use to evaluate ratios of parton distributions 
for splittings in a sequence of splittings which are not ordered 
in evolution <i>pT</i>. 
<br/><code>option </code><strong> 0</strong> :  Use the combined splitting scale as argument in PDF ratios, 
for both splittings. 
   
<br/><code>option </code><strong> 1</strong> :  Use the true reconstructed scale as argument in PDF 
ratios, for each splitting separately. 
   
   
 
<p/><code>mode&nbsp; </code><strong> Merging:incompleteScalePrescrip &nbsp;</strong> 
 (<code>default = <strong>0</strong></code>; <code>minimum = 0</code>; <code>maximum = 2</code>)<br/>
When no complete parton shower history (i.e. starting from a 
<i>2 &rarr; 2</i> process)  for a matrix element with additional jets 
can be found, such a configuration is said to have an incomplete history. 
Since in incomplete histories, not all  shower starting scales are 
determined by clusterings, a prescription for setting the starting scale 
of trial showers in incomplete histories is needed. Three options are 
provided. 
<br/><code>option </code><strong> 0</strong> :  Use factorisation scale as shower starting scale 
for  incomplete histories. 
   
<br/><code>option </code><strong> 1</strong> :  Use <i>sHat</i> as shower starting scale for 
incomplete histories. 
   
<br/><code>option </code><strong> 2</strong> :  Use <i>s</i> as shower starting scale for 
incomplete histories. 
   
   
 
<p/><code>flag&nbsp; </code><strong> Merging:allowColourShuffling &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
If on, this will allow the algorithm to swap one colour index in the state, 
when trying to find all possible clusterings, if no clustering has been 
found, but more clusterings had been requested. In this way, some incomplete 
histories can be avoided. Generally, we advise the non-expert user to not 
touch this switch, because a slight change in the colour structure can change 
the radiation pattern. To however study the sensitivity of the predictions on 
these effects, allowing for colour reshuffling can be useful. 
   
 
<p/><code>flag&nbsp; </code><strong> Merging:usePythiaQRenHard &nbsp;</strong> 
 (<code>default = <strong>on</strong></code>)<br/>
If on, this will allow the algorithm to use a dynamical renormalisation scale 
to evaluate the strong couplings of the core hard process in dijet and 
prompt photon events. 
This means that the value of <i>&alpha;<sub>s</sub></i> used as coupling 
of the hard process in the matrix element generation will be replaced with 
a running coupling evaluated at the geometric mean of the squared transverse 
masses of the two outgoing particles, as is the default prescription in 
Pythia. 
   
 
<p/><code>flag&nbsp; </code><strong> Merging:usePythiaQFacHard &nbsp;</strong> 
 (<code>default = <strong>on</strong></code>)<br/>
If on, this will allow the algorithm to use a dynamical factorisation scale 
to evaluate parton distributions associated with the hadronic cross section 
of the core hard process in dijet and prompt photon events. 
In the calculation of PDF ratios as part of the CKKW-L weight of an event, 
parton distributions that should be evaluated at the scale of the core 
2 - >2 process will be evaluated using the dynamical factorisation scale 
Pythia would attribute to this process. This means that the hard process 
factorisation scale is set to the smaller of the squared transverse masses 
of the two outgoing particles. 
   
 
<p/><code>flag&nbsp; </code><strong> Merging:mayRemoveDecayProducts &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
Remove products of resonances in the hard process, in case Pythia generates 
decay products before merging. This makes merging possible even for an 
indeterminate final state, if Pythia itself has produced the decay products. 
The merging methods will instead be invoked on the "non-decayed" event, 
thus removing the limitation to only one decay channel when performing 
the merging. 
This switch is necessary e.g. for slepton pair production in association with 
additional QCD jets, if the input LHE file contains the resonant sleptons, 
and Pythia decides on a decay according to the branching fractions read from 
SLHA input. 
   
 
<p/><code>flag&nbsp; </code><strong> Merging:allowSQCDClustering &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
Allow clustering of gluon emission off squarks. 
   
 
<p/><code>flag&nbsp; </code><strong> Merging:allowWClustering &nbsp;</strong> 
 (<code>default = <strong>off</strong></code>)<br/>
Allow clustering of W boson, if interpreted as a final state emission. This 
switch should not be used until electro-weak showers become available. 
   
 
</body>
</html>
 
<!-- Copyright (C) 2014 Torbjorn Sjostrand -->