Fork me on GitHub

source: git/external/fastjet/NNBase.hh@ af6ce6a

Timing
Last change on this file since af6ce6a was b7b836a, checked in by Pavel Demin <pavel-demin@…>, 6 years ago

update FastJet library to 3.3.1 and FastJet Contrib library to 1.036

  • Property mode set to 100644
File size: 7.4 KB
Line 
1#ifndef __FASTJET_NNBASE_HH__
2#define __FASTJET_NNBASE_HH__
3
4//FJSTARTHEADER
5// $Id: NNBase.hh 4355 2018-04-22 15:38:54Z salam $
6//
7// Copyright (c) 2016-2018, 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
37FASTJET_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
42class _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!
51template<class I> class NNInfo {
52public:
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);}
56private:
57 I * _info;
58};
59
60/// @ingroup advanced_usage Internal helper specialisation of NNInfo
61/// for cases where there is no extra info
62template<> class NNInfo<_NoInfo> {
63public:
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.
164template<class I = _NoInfo> class NNBase : public NNInfo<I> {
165public:
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
189FASTJET_END_NAMESPACE // defined in fastjet/internal/base.hh
190
191
192#endif // __FASTJET_NNBASE_HH__
Note: See TracBrowser for help on using the repository browser.