Fork me on GitHub

source: git/external/fastjet/contribs/Nsubjettiness/Njettiness.hh

Last change on this file was 973b92a, checked in by Pavel Demin <pavel.demin@…>, 9 years ago

update FastJet library to 3.1.3 and Nsubjettiness library to 2.2.1

  • Property mode set to 100644
File size: 11.9 KB
Line 
1// Nsubjettiness Package
2// Questions/Comments? jthaler@jthaler.net
3//
4// Copyright (c) 2011-14
5// Jesse Thaler, Ken Van Tilburg, Christopher K. Vermilion, and TJ Wilkason
6//
7// $Id: Njettiness.hh 822 2015-06-15 23:52:57Z jthaler $
8//----------------------------------------------------------------------
9// This file is part of FastJet contrib.
10//
11// It is free software; you can redistribute it and/or modify it under
12// the terms of the GNU General Public License as published by the
13// Free Software Foundation; either version 2 of the License, or (at
14// your option) any later version.
15//
16// It is distributed in the hope that it will be useful, but WITHOUT
17// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
18// or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
19// License for more details.
20//
21// You should have received a copy of the GNU General Public License
22// along with this code. If not, see <http://www.gnu.org/licenses/>.
23//----------------------------------------------------------------------
24
25#ifndef __FASTJET_CONTRIB_NJETTINESS_HH__
26#define __FASTJET_CONTRIB_NJETTINESS_HH__
27
28
29#include "MeasureDefinition.hh"
30#include "AxesDefinition.hh"
31#include "TauComponents.hh"
32
33#include "fastjet/PseudoJet.hh"
34#include "fastjet/SharedPtr.hh"
35#include <fastjet/LimitedWarning.hh>
36
37#include <cmath>
38#include <vector>
39#include <list>
40
41FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
42
43namespace contrib {
44
45/** \mainpage Nsubjettiness Documentation
46 *
47 * These Doxygen pages provide automatically generated documentation for the
48 * Nsubjettiness FastJet contrib. This documentation is being slowly improved.
49 *
50 * \section core_classes Core Classes
51 *
52 * - Nsubjettiness: Calculating N-subjettiness jet shapes
53 * - NsubjettinessRatio: Calculating N-subjettiness ratios
54 * - XConePlugin: Running the XCone jet algorithm
55 * - NjettinessPlugin: Running generic N-jettiness as a jet algorithm
56 *
57 * \subsection core_classes_helper Helper Classes for Core
58 * - Njettiness: Core code for all N-(sub)jettiness calculations
59 * - NjettinessExtras: Way to access additional N-jettiness information
60 * - TauComponents: Output format for all N-(sub)jettiness information
61 * - TauPartition: Access to N-(sub)jettiness partitioning information
62 * - PseudoXConePlugin: Testing code to compare to XConePlugin (doesn't use one-pass minimization)
63 *
64 * \section axes_classes Axes Definitions
65 *
66 * \subsection axes_classes_base Base Classes
67 * - AxesDefinition: Defines generic axes definition
68 * - ExclusiveJetAxes: Axes finder from exclusive jet algorithm
69 * - ExclusiveCombinatorialJetAxes: Axes finder from exclusive jet algorithm (with extra axes to test combinatoric options)
70 * - HardestJetAxes: Axes finder from inclusive jet algorithm
71 *
72 * \subsection axes_classes_derived Derived Classes
73 *
74 * \b OnePass means iterative improvement to a (local) N-(sub)jettiness minimum.
75 *
76 * \b MultiPass means using multiple random seed inputs
77 *
78 * \b Comb means checking N + Nextra choose N combinatorial options
79 *
80 * - KT_Axes / OnePass_KT_Axes: Axes from exclusive kT
81 * - CA_Axes / OnePass_CA_Axes: Axes from exclusive Cambridge/Aachen
82 * - AntiKT_Axes / OnePass_AntiKT_Axes: Axes from inclusive anti-kT
83 * - WTA_KT_Axes / OnePass_WTA_KT_Axes: Axes from exclusive kT, using winner-take-all recombination
84 * - WTA_CA_Axes / OnePass_WTA_CA_Axes: Axes from exclusive CA, using winner-take-all recombination
85 *
86 * - GenET_GenKT_Axes / OnePass_GenET_GenKT_Axes / Comb_GenET_GenKT_Axes: Axes from exclusive generalized kt, with generalized Et recombination
87 * - WTA_GenKT_Axes / OnePass_WTA_GenKT_Axes / Comb_WTA_GenKT_Axes: Axes from exclusive generalized kt, with winner-take-all recombination
88 *
89 * - Manual_Axes / OnePass_Manual_Axes / MultiPass_Manual_Axes: Use manual axes
90 * - MultiPass_Axes: Multiple passes with random input seeds
91 *
92 * \subsection axes_classes_helper Helper Classes for Axes
93 * - GeneralEtSchemeRecombiner: Generalized Et-scheme recombiner
94 * - WinnerTakeAllRecombiner: Winner-take-all recombiner (similar functionality now in FastJet 3.1)
95 * - JetDefinitionWrapper: Wrapper for Jet Definitions to handle memory management
96 *
97 * \section measure_classes Measure Definitions
98 *
99 * \subsection measure_classes_bases Base Classes
100 * - MeasureDefinition: Defines generic measures
101 * - DefaultMeasure: Base class for the original N-subjettiness measures
102 *
103 * \subsection measure_classes_derived Derived Classes
104 * - NormalizedMeasure / UnnormalizedMeasure / NormalizedCutoffMeasure / UnnormalizedCutoffMeasure : Variants on the default N-subjettiness measure.
105 * - ConicalMeasure: Similar to default measure, but intended as N-jettiness event shape
106 * - ConicalGeometricMeasure / XConeMeasure: Measure used in XCone jet algorithm
107 * - OriginalGeometricMeasure / ModifiedGeometricMeasure: Dot product measures useful for theoretical calcualtions
108 *
109 * \subsection measure_classes_helper Helper Classes for Measures
110 * - LightLikeAxis : Defines light-like axis
111 */
112
113///////
114//
115// Main Njettiness Class
116//
117///////
118
119///------------------------------------------------------------------------
120/// \class Njettiness
121/// \brief Core class for N-(sub)jettiness calculations
122///
123/**
124 * The N-jettiness event shape.
125 *
126 * This is the core class used to perform N-jettiness jet finding (via NjettinessPlugin or XConePluggin)
127 * as well as find the N-subjettiness jet shape (via Nsubjettiness).
128 *
129 * In general, the user should never need to call this object. In addition, its API should not be considered
130 * fixed, since all code improvements effectively happen from reorganizing this class.
131 *
132 * Njettiness uses AxesDefinition and MeasureDefinition together in order to find tau_N for the event.
133 * It also can return information about the axes and jets it used in the calculation, as well as
134 * information about how the event was partitioned.
135 */
136class Njettiness {
137public:
138
139 /// Main constructor that uses AxesMode and MeasureDefinition to specify measure
140 /// Unlike Nsubjettiness or NjettinessPlugin, the value N is not chosen
141 Njettiness(const AxesDefinition & axes_def, const MeasureDefinition & measure_def);
142
143 /// Destructor
144 ~Njettiness() {};
145
146 /// setAxes for Manual mode
147 void setAxes(const std::vector<fastjet::PseudoJet> & myAxes);
148
149 /// Calculates and returns all TauComponents that user would want.
150 /// This information is stored in _current_tau_components for later access as well.
151 TauComponents getTauComponents(unsigned n_jets, const std::vector<fastjet::PseudoJet> & inputJets) const;
152
153 /// Calculates the value of N-subjettiness,
154 /// but only returns the tau value from _current_tau_components
155 double getTau(unsigned n_jets, const std::vector<fastjet::PseudoJet> & inputJets) const {
156 return getTauComponents(n_jets, inputJets).tau();
157 }
158
159 /// Return all relevant information about tau components
160 TauComponents currentTauComponents() const {return _current_tau_components;}
161 /// Return axes found by getTauComponents.
162 std::vector<fastjet::PseudoJet> currentAxes() const { return _currentAxes;}
163 /// Return seedAxes used if onepass minimization (otherwise, same as currentAxes)
164 std::vector<fastjet::PseudoJet> seedAxes() const { return _seedAxes;}
165 /// Return jet partition found by getTauComponents.
166 std::vector<fastjet::PseudoJet> currentJets() const {return _currentPartition.jets();}
167 /// Return beam partition found by getTauComponents.
168 fastjet::PseudoJet currentBeam() const {return _currentPartition.beam();}
169 /// Return beam partition found by getTauComponents.
170 TauPartition currentPartition() const {return _currentPartition;}
171
172
173private:
174
175 /// AxesDefinition to use. Implemented as SharedPtrs to avoid memory management headaches
176 SharedPtr<const AxesDefinition> _axes_def;
177 /// MeasureDefinition to use. Implemented as SharedPtrs to avoid memory management headaches
178 SharedPtr<const MeasureDefinition> _measure_def;
179
180
181 // Information about the current information
182 // Defined as mutables, so user should be aware that these change when getTau is called.
183 // TODO: These are not thread safe and should be fixed somehow
184 mutable TauComponents _current_tau_components; //automatically set to have components of 0; these values will be set by the getTau function call
185 mutable std::vector<fastjet::PseudoJet> _currentAxes; //axes found after minimization
186 mutable std::vector<fastjet::PseudoJet> _seedAxes; // axes used prior to minimization (if applicable)
187 mutable TauPartition _currentPartition; //partitioning information
188
189 /// Warning if the user tries to use v1.0.3 measure style.
190 static LimitedWarning _old_measure_warning;
191 /// Warning if the user tries to use v1.0.3 axes style.
192 static LimitedWarning _old_axes_warning;
193
194
195public:
196
197 // These interfaces are included for backwards compability, and will be deprecated in a future release (scheduled for deletion in v3.0)
198
199 /// \deprecated
200 /// Deprecated enum to determine axes mode
201 /// The various axes choices available to the user
202 /// It is recommended to use AxesDefinition instead of these.
203 enum AxesMode {
204 kt_axes, // exclusive kt axes
205 ca_axes, // exclusive ca axes
206 antikt_0p2_axes, // inclusive hardest axes with antikt-0.2
207 wta_kt_axes, // Winner Take All axes with kt
208 wta_ca_axes, // Winner Take All axes with CA
209 onepass_kt_axes, // one-pass minimization from kt starting point
210 onepass_ca_axes, // one-pass minimization from ca starting point
211 onepass_antikt_0p2_axes, // one-pass minimization from antikt-0.2 starting point
212 onepass_wta_kt_axes, //one-pass minimization of WTA axes with kt
213 onepass_wta_ca_axes, //one-pass minimization of WTA axes with ca
214 min_axes, // axes that minimize N-subjettiness (100 passes by default)
215 manual_axes, // set your own axes with setAxes()
216 onepass_manual_axes // one-pass minimization from manual starting point
217 };
218
219 /// \deprecated
220 /// Deprecated enum to determine measure mode
221 /// The measures available to the user.
222 /// "normalized_cutoff_measure" was the default in v1.0 of Nsubjettiness
223 /// "unnormalized_measure" is now the recommended default usage
224 /// But it is recommended to use MeasureDefinition instead of these.
225 enum MeasureMode {
226 normalized_measure, //default normalized measure
227 unnormalized_measure, //default unnormalized measure
228 geometric_measure, //geometric measure
229 normalized_cutoff_measure, //default normalized measure with explicit Rcutoff
230 unnormalized_cutoff_measure, //default unnormalized measure with explicit Rcutoff
231 geometric_cutoff_measure //geometric measure with explicit Rcutoff
232 };
233
234 /// \deprecated
235 /// Intermediate constructor (needed to enable v1.0.3 backwards compatibility?)
236 Njettiness(AxesMode axes_mode, const MeasureDefinition & measure_def);
237
238 /// \deprecated
239 /// Old-style constructor which takes axes/measure information as enums with measure parameters
240 /// This version absolutely is not recommended
241 Njettiness(AxesMode axes_mode,
242 MeasureMode measure_mode,
243 int num_para,
244 double para1 = std::numeric_limits<double>::quiet_NaN(),
245 double para2 = std::numeric_limits<double>::quiet_NaN(),
246 double para3 = std::numeric_limits<double>::quiet_NaN())
247 : _axes_def(createAxesDef(axes_mode)), _measure_def(createMeasureDef(measure_mode, num_para, para1, para2, para3)) {
248 }
249
250 /// \deprecated
251 /// Convert old style enums into new style MeasureDefinition
252 AxesDefinition* createAxesDef(AxesMode axes_mode) const;
253
254 /// \deprecated
255 /// Convert old style enums into new style MeasureDefinition
256 MeasureDefinition* createMeasureDef(MeasureMode measure_mode, int num_para, double para1, double para2, double para3) const;
257
258};
259
260} // namespace contrib
261
262FASTJET_END_NAMESPACE
263
264#endif // __FASTJET_CONTRIB_NJETTINESS_HH__
265
Note: See TracBrowser for help on using the repository browser.