Fork me on GitHub

source: git/external/fastjet/contribs/RecursiveTools/README@ f118021

ImprovedOutputFile Timing dual_readout llp
Last change on this file since f118021 was 1f1f858, checked in by Michele Selvaggi <michele.selvaggi@…>, 10 years ago

added RecursiveTools package from fastjet contribs

  • Property mode set to 100644
File size: 7.2 KB
Line 
1------------------------------------------------------------------------
2RecursiveTools FastJet contrib
3------------------------------------------------------------------------
4
5The RecursiveTools FastJet contrib aims to provide a common contrib
6for a number of tools that involve recursive reclustering/declustering
7of a jet for tagging or grooming purposes.
8
9Currently it contains:
10
11- ModifiedMassDropTagger
12 This corresponds to arXiv:1307.0007 by Mrinal Dasgupta, Alessandro
13 Fregoso, Simone Marzani and Gavin P. Salam
14
15- SoftDrop
16 This corresponds to arXiv:1402.2657 by Andrew J. Larkoski, Simone
17 Marzani, Gregory Soyez, Jesse Thaler
18
19- Recluster
20 A generic tool to recluster a given jet into subjets
21 Note: this is largely based on the Filter code in FastJet v3.0 and
22 ultimately, this tool will probably be moved into FastJet
23
24The interface for these tools is described in more detail below, with
25all of the available options documented in the header files.
26
27One note about nomenclature. A groomer is a procedure that takes a
28PseudoJet and always returns another (non-zero) PseudoJet. A tagger is
29a procedure that takes a PseudoJet, and either returns another PseudoJet
30(i.e. tags it) or returns an empty PseudoJet (i.e. doesn't tag it).
31
32------------------------------------------------------------------------
33ModifiedMassDropTagger
34------------------------------------------------------------------------
35
36The Modified Mass Drop Tagger (mMDT) recursively declusters a jet,
37following the largest pT subjet until a pair of subjets is found that
38satisfy the symmetry condition on the energy sharing
39
40 z > z_cut
41
42where z_cut is a predetermined value. By default, z is calculated as
43the scalar pT fraction of the softest subjet. Note that larger values
44of z_cut correspond to a more restrictive tagging criteria.
45
46By default, mMDT will first recluster the jet using the CA clustering
47algorithm, which means that mMDT can be called on any jet, regardless
48of the original jet finding measure.
49
50A default mMDT can be created via
51
52 double z_cut = 0.10;
53 ModifiedMassDropTagger mMDT(z_cut);
54
55More options are available in the full constructor. To apply mMDT,
56one simply calls it on the jet of interest.
57
58 PseudoJet tagged_jet = mMDT(original_jet);
59
60Note that mMDT is a tagger, such that tagged_jet will only be non-zero
61if the symmetry cut z > z_cut is satisfied by some branching of the
62clustering tree.
63
64To gain additional information about the mMDT procedure, one can use
65
66 tagged_jet.structure_of<ModifiedMassDropTagger>()
67
68which gives access to information about the delta_R between the tagged
69subjets, their z value, etc.
70
71------------------------------------------------------------------------
72SoftDrop
73------------------------------------------------------------------------
74
75The SoftDrop procedure is very similar to mMDT, albeit with a
76generalized symmetry condition:
77
78 z > z_cut * (R / R0)^beta
79
80Note that larger z_cut and smaller beta correspond to more aggressive
81grooming of the jet.
82
83SoftDrop is intended to be used as a groomer (instead of as a tagger),
84such that if the symmetry condition fails throughout the whole
85clustering tree, SoftDrop will still return a single particle in the
86end. Apart from the tagger/groomer distinction, SoftDrop with beta=0 is
87the same as mMDT.
88
89A default SoftDrop groomer can be created via:
90
91 double z_cut = 0.10;
92 double beta = 2.0;
93 double R0 = 1.0; // this is the default value
94 SoftDrop sd(z_cut,beta,R0);
95
96and acts on a desired jet as
97
98 PseudoJet groomed_jet = sd(original_jet);
99
100and additional information can be obtained via
101
102 groomed_jet.structure_of<SoftDrop>()
103
104SoftDrop is typically called with beta > 0, though beta < 0 is still a
105viable option. Because beta < 0 is infrared-collinear unsafe in
106grooming mode, one probably wants to switch to tagging mode for negative
107beta, via set_tagging_mode().
108
109------------------------------------------------------------------------
110Recluster
111------------------------------------------------------------------------
112
113The Recluster class allows the constituents of a jet to be reclustered
114with a different recursive clustering algorithm. This is used
115internally in the mMDT/SoftDrop code in order to recluster the jet using
116the CA algorithm. This is achieved via
117
118 Recluster ca_reclusterer(cambridge_algorithm,
119 JetDefinition::max_allowable_R);
120 PseudoJet reclustered_jet = ca_reclusterer(original_jet);
121
122Note that reclustered_jet creates a new ClusterSequence that knows to
123delete_self_when_unused.
124
125
126------------------------------------------------------------------------
127Changing behaviour
128------------------------------------------------------------------------
129
130The behaviour of the ModifiedMassDropTagger and SoftDrop classes can
131be tweaked using the following options:
132
133SymmetryMeasure = {scalar_z,vector_z,y} [constructor argument]
134 : The definition of the energy sharing between subjets, with 0
135 corresponding to the most asymmetric
136
137RecursionChoice = {larger_pt,larger_mt,larger_m} [constructor argument]
138 : The path to recurse through the tree after the symmetry condition
139 fails
140
141mu_cut [constructor argument]
142 : An optional mass drop condition
143
144set_subtractor(subtractor*) [or subtracter as a constructor argument]
145 : provide a subtractor. When a subtractor is supplied, the
146 kinematic constraints are applied on subtracted 4-vectors. In
147 this case, the result of the ModifiedMassDropTagger/SoftDrop is a
148 subtracted PseudoJet, and it is assumed that
149 ModifiedMassDropTagger/SoftDrop is applied to an unsubtracted jet.
150 The latter default can be changed by calling
151 set_input_jet_is_subtracted().
152
153set_reclustering(bool, Recluster*)
154 : An optional setting to recluster a jet with a different jet
155 recursive jet algorithm. The code is only designed to give sensible
156 results with the CA algorithm, but other reclustering algorithm
157 (especially kT) may be appropriate in certain contexts.
158 Use at your own risk.
159
160set_grooming_mode()/set_tagging_mode()
161 : In grooming mode, the algorithm will return a single particle if the
162 symmetry condition fails for the whole tree. In tagging mode, the
163 algorithm will return an zero PseudoJet if no symmetry conditions
164 passes. Note that ModifiedMassDropTagger defaults to tagging mode
165 and SoftDrop defaults to grooming mode.
166
167------------------------------------------------------------------------
168Technical Details
169------------------------------------------------------------------------
170
171Both ModifiedMassDropTagger and SoftDrop inherit from
172RecursiveSymmetryCutBase, which provides a common codebase for recursive
173declustering of a jet with a symmetry cut condition. A generic
174RecursiveSymmetryCutBase depends on the following (virtual) functions
175(see header file for exact full specs, including constness):
176
177double symmetry_cut_fn(PseudoJet &, PseudoJet &)
178 : The function that defines the symmetry cut. This is what actually
179 defines different recursive declustering schemes, and all classes
180 that inherit from RecursiveSymmetryCutBase must define this
181 function.
182
183string symmetry_cut_description()
184 : the string description of the symmetry cut.
185
186------------------------------------------------------------------------
Note: See TracBrowser for help on using the repository browser.