FastJet  3.3.3
NNBase.hh
1 #ifndef __FASTJET_NNBASE_HH__
2 #define __FASTJET_NNBASE_HH__
3 
4 //FJSTARTHEADER
5 // $Id: NNBase.hh 4420 2019-11-29 09:28:20Z soyez $
6 //
7 // Copyright (c) 2016-2019, Matteo Cacciari, Gavin P. Salam and Gregory Soyez
8 //
9 //----------------------------------------------------------------------
10 // This file is part of FastJet.
11 //
12 // FastJet is free software; you can redistribute it and/or modify
13 // it under the terms of the GNU General Public License as published by
14 // the Free Software Foundation; either version 2 of the License, or
15 // (at your option) any later version.
16 //
17 // The algorithms that underlie FastJet have required considerable
18 // development. They are described in the original FastJet paper,
19 // hep-ph/0512210 and in the manual, arXiv:1111.6097. If you use
20 // FastJet as part of work towards a scientific publication, please
21 // quote the version you use and include a citation to the manual and
22 // optionally also to hep-ph/0512210.
23 //
24 // FastJet is distributed in the hope that it will be useful,
25 // but WITHOUT ANY WARRANTY; without even the implied warranty of
26 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
27 // GNU General Public License for more details.
28 //
29 // You should have received a copy of the GNU General Public License
30 // along with FastJet. If not, see <http://www.gnu.org/licenses/>.
31 //----------------------------------------------------------------------
32 //FJENDHEADER
33 
34 #include<fastjet/ClusterSequence.hh>
35 
36 
37 FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
38 
39 /// @ingroup advanced_usage
40 /// \class _NoInfo
41 /// internal dummy class, used as a default template argument
42 class _NoInfo {};
43 
44 /// @ingroup advanced_usage
45 /// \class NNInfo
46 ///
47 /// internal helper template class to facilitate initialisation of a
48 /// BJ with a PseudoJet and extra information. Implementations of
49 /// NN-based clustering do not need to explicitly use or refer to
50 /// this class!
51 template<class I> class NNInfo {
52 public:
53  NNInfo() : _info(NULL) {}
54  NNInfo(I * info) : _info(info) {}
55  template<class BJ> void init_jet(BJ * briefjet, const fastjet::PseudoJet & jet, int index) { briefjet->init(jet, index, _info);}
56 private:
57  I * _info;
58 };
59 
60 /// @ingroup advanced_usage Internal helper specialisation of NNInfo
61 /// for cases where there is no extra info
62 template<> class NNInfo<_NoInfo> {
63 public:
64  NNInfo() {}
65  NNInfo(_NoInfo * ) {}
66  template<class BJ> void init_jet(BJ * briefjet, const fastjet::PseudoJet & jet, int index) { briefjet->init(jet, index);}
67 };
68 
69 
70 //----------------------------------------------------------------------
71 /// @ingroup advanced_usage
72 /// \class NNBase
73 /// Helps solve closest pair problems with generic interparticle and
74 /// particle-beam distances.
75 ///
76 /// \section Description Description and derived classes:
77 ///
78 /// This is an abstract base class which defines the interface for
79 /// several classes that help carry out nearest-neighbour
80 /// clustering:
81 ///
82 /// - NNH provides an implementation for generic measures,
83 ///
84 /// - NNFJN2Plain provides an implementation for distances
85 /// satisfying the FastJet lemma i.e. distances for
86 /// which the minimum dij has the property that i is
87 /// the geometrical nearest neighbour of j, or vice
88 /// versa. I.e. the distance can be factorised in a
89 /// momentum factor and a geometric piece. This is
90 /// based on the fastjet N2Plain clustering strategy
91 ///
92 /// - NNFJN2Tiled is a tiled version of NNFJN2Plain (based on the
93 /// N2Tiled FastJet clustering strategy). Like
94 /// NNPlain2 it applies to distance measures that
95 /// satisfy the FastJet lemma, with the additional
96 /// restriction that: (a) the underlying geometry
97 /// should be cylindrical (e.g. rapidity--azimuth)
98 /// and (b) the search for the geometric nearest
99 /// neighbour of each particle can be limited to
100 /// that particle's tile and its neighbouring tiles.
101 ///
102 /// If you can use NNFJN2Plain it will usually be faster than
103 /// NNH. NNFJN2Tiled, where it can be used, will be faster for
104 /// multiplicities above a few tens of particles.
105 ///
106 /// NOTE: IN ALL CASES, THE DISTANCE MUST BE SYMMETRIC (dij=dji)!!!
107 ///
108 /// \section BJ Underlying BriefJet (BJ) class:
109 ///
110 /// All derived classes must be templated with a BriefJet (BJ)
111 /// class --- BJ should basically cache the minimal amount of
112 /// information that is needed to efficiently calculate
113 /// interparticle distances and particle-beam distances.
114 ///
115 /// This class can be used with or without an extra "Information"
116 /// template, i.e. `NN*<BJ>` or `NN*<BJ,I>`. Accordingly BJ must provide
117 /// one of the two following init functions:
118 ///
119 /// \code
120 /// void BJ::init(const PseudoJet & jet); // initialise with a PseudoJet
121 /// void BJ::init(const PseudoJet & jet, I * info); // initialise with a PseudoJet + info
122 /// \endcode
123 ///
124 /// where info might be a pointer to a class that contains, e.g.,
125 /// information about R, or other parameters of the jet algorithm
126 ///
127 /// The BJ then provides information about interparticle and
128 /// particle-beam distances. The exact requirements depend on
129 /// whether you use NNH, NNFJN2Plain or NNFJN2Tiled. (See the
130 /// corresponding classes for details).
131 ///
132 ///
133 /// \section Workflow Workflow:
134 ///
135 /// In all cases, the usage of NNBase classes works as follows:
136 ///
137 /// First, from the list of particles, create an `NN*<BJ>`
138 /// object of the appropriate type with the appropriate BJ class
139 /// (and optional extra info).
140 ///
141 /// Then, cluster using a loop like this (assuming a FastJet plugin)
142 ///
143 /// \code
144 /// while (njets > 0) {
145 /// int i, j, k;
146 /// // get the i and j that minimize the distance
147 /// double dij = nn.dij_min(i, j);
148 ///
149 /// // do the appropriate recombination and update the nn
150 /// if (j >= 0) { // interparticle recombination
151 /// cs.plugin_record_ij_recombination(i, j, dij, k);
152 /// nn.merge_jets(i, j, cs.jets()[k], k);
153 /// } else { // bbeam recombination
154 /// double diB = cs.jets()[i].E()*cs.jets()[i].E(); // get new diB
155 /// cs.plugin_record_iB_recombination(i, diB);
156 /// nn.remove_jet(i);
157 /// }
158 /// njets--;
159 /// }
160 /// \endcode
161 ///
162 /// For an example of how the NNH<BJ> class is used, see the
163 /// JadePlugin or EECambridgePlugin.
164 template<class I = _NoInfo> class NNBase : public NNInfo<I> {
165 public:
166  /// Default constructor
167  NNBase() {}
168  /// Constuctor with additional Info
169  NNBase(I * info) : NNInfo<I>(info) {}
170 
171  /// initialisation from a given list of particles
172  virtual void start(const std::vector<PseudoJet> & jets) = 0;
173 
174  /// returns the dij_min and indices iA, iB, for the corresponding jets.
175  /// If iB < 0 then iA recombines with the beam
176  virtual double dij_min(int & iA, int & iB) = 0;
177 
178  /// removes the jet pointed to by index iA
179  virtual void remove_jet(int iA) = 0;
180 
181  /// merges the jets pointed to by indices A and B and replaces them with
182  /// jet, assigning it an index jet_index.
183  virtual void merge_jets(int iA, int iB, const PseudoJet & jet, int jet_index) = 0;
184 
185  virtual ~NNBase() {};
186 };
187 
188 
189 FASTJET_END_NAMESPACE // defined in fastjet/internal/base.hh
190 
191 
192 #endif // __FASTJET_NNBASE_HH__
Helps solve closest pair problems with generic interparticle and particle-beam distances.
Definition: NNBase.hh:164
NNBase()
Default constructor.
Definition: NNBase.hh:167
internal dummy class, used as a default template argument
Definition: NNBase.hh:42
internal helper template class to facilitate initialisation of a BJ with a PseudoJet and extra inform...
Definition: NNBase.hh:51
Class to contain pseudojets, including minimal information of use to jet-clustering routines...
Definition: PseudoJet.hh:67
NNBase(I *info)
Constuctor with additional Info.
Definition: NNBase.hh:169