FastJet 3.4.1
GhostedAreaSpec.hh
1//FJSTARTHEADER
2// $Id$
3//
4// Copyright (c) 2005-2023, Matteo Cacciari, Gavin P. Salam and Gregory Soyez
5//
6//----------------------------------------------------------------------
7// This file is part of FastJet.
8//
9// FastJet is free software; you can redistribute it and/or modify
10// it under the terms of the GNU General Public License as published by
11// the Free Software Foundation; either version 2 of the License, or
12// (at your option) any later version.
13//
14// The algorithms that underlie FastJet have required considerable
15// development. They are described in the original FastJet paper,
16// hep-ph/0512210 and in the manual, arXiv:1111.6097. If you use
17// FastJet as part of work towards a scientific publication, please
18// quote the version you use and include a citation to the manual and
19// optionally also to hep-ph/0512210.
20//
21// FastJet is distributed in the hope that it will be useful,
22// but WITHOUT ANY WARRANTY; without even the implied warranty of
23// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
24// GNU General Public License for more details.
25//
26// You should have received a copy of the GNU General Public License
27// along with FastJet. If not, see <http://www.gnu.org/licenses/>.
28//----------------------------------------------------------------------
29//FJENDHEADER
30
31
32#ifndef __FASTJET_GHOSTEDAREASPEC_HH__
33#define __FASTJET_GHOSTEDAREASPEC_HH__
34
35#include<vector>
36#include<string>
37#include "fastjet/PseudoJet.hh"
38#include "fastjet/internal/BasicRandom.hh"
39#include "fastjet/Selector.hh"
40#include "fastjet/LimitedWarning.hh"
41#include "fastjet/internal/deprecated.hh"
42#include "fastjet/SharedPtr.hh"
43
44//
45#define STATIC_GENERATOR 1
46
47FASTJET_BEGIN_NAMESPACE // defined in fastjet/internal/base.hh
48
49/// namespace to hold default parameters for the active area spec
50namespace gas {
51 const double def_ghost_maxrap = 6.0;
52 const int def_repeat = 1;
53 const double def_ghost_area = 0.01;
54 const double def_grid_scatter = 1.0;
55 const double def_pt_scatter = 0.1;
56 const double def_mean_ghost_pt = 1e-100;
57}
58
59//----------------------------------------------------------------------
60/// @ingroup area_classes
61/// \class GhostedAreaSpec
62/// Parameters to configure the computation of jet areas using ghosts
63///
64/// Class that defines the parameters that go into the measurement
65/// of active jet areas.
66///
67/// Notes about thread-safety.
68/// --------------------------
69///
70/// Ghosts are generated randomly, using by default a static random
71/// number generator.
72///
73/// By default, we will lock the number generator during the period
74/// over which we generate the required random numbers. The procedure
75/// will keep track of the seeds that have been used to generate a
76/// particular set of ghosts and, ultimately, these seeds will be
77/// made available from ClusterSequenceArea via
78///
79/// ClusterSequenceArea::area_def().ghost_spec().get_last_seed(vector<int>);
80///
81/// To use user-specified seeds in a thread-safe way, the end-user
82/// should use
83///
84/// ClusterSequenceArea csa(particles, jet_def,
85/// area_def.with_fixed_seed(user_defined_seed));
86///
87/// or explicitly make a copy of the AreaDefinition before doing
88/// the clustering:
89///
90/// AreaDefinition local_area_def
91/// = area_def.with_fixed_seed(user_defined_seed);
92/// ClusterSequenceArea csa(particles, jet_def, area_def,local_area_def);
93///
94/// This will use a local random generator to compute the ghosts (in
95/// particular, it will not affect the static global generator)
96///
97/// Note that each clustering done with the GhostedAreaSpec obtained
98/// through area_def.with_seed(user_defined_seed) will use exactly the
99/// same set of ghosts. Using
100/// area_def.with_fixed_seed(user_defined_seed), with an empty vector
101/// passed as argument, will return to using the common static random
102/// generator.
104public:
105 /// default constructor
107 _ghost_maxrap (gas::def_ghost_maxrap),
108 _ghost_rap_offset(0.0),
109 _repeat (gas::def_repeat),
110 _ghost_area (gas::def_ghost_area),
111 _grid_scatter (gas::def_grid_scatter),
112 _pt_scatter (gas::def_pt_scatter),
113 _mean_ghost_pt(gas::def_mean_ghost_pt),
114 _fj2_placement(false),
115 _user_random_generator(){_initialize();}
116
117 /// explicit constructor
118 ///
119 /// It takes as parameters the maximal (abs) rapidity for the ghosts
120 /// and an optional user-specified random number generator.
121 ///
122 /// For the latter, ownership is transferred to the GhostedAreaSpec
123 /// class (i.e. it is stored internally as a shared pointer)
124 explicit GhostedAreaSpec(double ghost_maxrap_in,
125 BasicRandom<double> *user_random_generator):
126 _ghost_maxrap(ghost_maxrap_in),
127 _ghost_rap_offset(0.0),
128 _repeat (gas::def_repeat),
129 _ghost_area (gas::def_ghost_area),
130 _grid_scatter (gas::def_grid_scatter),
131 _pt_scatter (gas::def_pt_scatter),
132 _mean_ghost_pt(gas::def_mean_ghost_pt),
133 _fj2_placement(false),
134 _user_random_generator(user_random_generator) {_initialize();}
135
136 /// explicit constructor
137 explicit GhostedAreaSpec(double ghost_maxrap_in,
138 int repeat_in = gas::def_repeat,
139 double ghost_area_in = gas::def_ghost_area,
140 double grid_scatter_in = gas::def_grid_scatter,
141 double pt_scatter_in = gas::def_pt_scatter,
142 double mean_ghost_pt_in = gas::def_mean_ghost_pt,
143 BasicRandom<double> *user_random_generator=NULL):
144 _ghost_maxrap(ghost_maxrap_in),
145 _ghost_rap_offset(0.0),
146 _repeat(repeat_in),
147 _ghost_area(ghost_area_in),
148 _grid_scatter(grid_scatter_in),
149 _pt_scatter(pt_scatter_in),
150 _mean_ghost_pt(mean_ghost_pt_in),
151 _fj2_placement(false),
152 _user_random_generator(user_random_generator) {_initialize();}
153
154 /// explicit constructor
155 explicit GhostedAreaSpec(double ghost_minrap_in,
156 double ghost_maxrap_in,
157 int repeat_in = gas::def_repeat,
158 double ghost_area_in = gas::def_ghost_area,
159 double grid_scatter_in = gas::def_grid_scatter,
160 double pt_scatter_in = gas::def_pt_scatter,
161 double mean_ghost_pt_in = gas::def_mean_ghost_pt,
162 BasicRandom<double> *user_random_generator=NULL):
163 _ghost_maxrap (0.5*(ghost_maxrap_in - ghost_minrap_in)),
164 _ghost_rap_offset(0.5*(ghost_maxrap_in + ghost_minrap_in)),
165 _repeat(repeat_in),
166 _ghost_area(ghost_area_in),
167 _grid_scatter(grid_scatter_in),
168 _pt_scatter(pt_scatter_in),
169 _mean_ghost_pt(mean_ghost_pt_in),
170 _fj2_placement(false),
171 _user_random_generator(user_random_generator) {_initialize();}
172
173
174 /// constructor based on a Selector
175 explicit GhostedAreaSpec(const Selector & selector,
176 int repeat_in = gas::def_repeat,
177 double ghost_area_in = gas::def_ghost_area,
178 double grid_scatter_in = gas::def_grid_scatter,
179 double pt_scatter_in = gas::def_pt_scatter,
180 double mean_ghost_pt_in = gas::def_mean_ghost_pt,
181 BasicRandom<double> *user_random_generator=NULL);
182
183
184 /// does the initialization of actual ghost parameters
185 void _initialize();
186
187 // for accessing values set by the user
188 inline double ghost_rapmax () const {return _ghost_maxrap;}
189 inline double ghost_maxrap () const {return _ghost_maxrap;}
190 inline double ghost_etamax () const {return _ghost_maxrap;}
191 inline double ghost_maxeta () const {return _ghost_maxrap;}
192 inline double ghost_area () const {return _ghost_area ;}
193 inline double grid_scatter () const {return _grid_scatter;}
194 inline double pt_scatter () const {return _pt_scatter ;}
195 inline double mean_ghost_pt() const {return _mean_ghost_pt ;}
196 inline int repeat () const {return _repeat ;}
197 inline bool fj2_placement() const {return _fj2_placement;}
198
199 inline double kt_scatter () const {return _pt_scatter ;}
200 inline double mean_ghost_kt() const {return _mean_ghost_pt ;}
201
202 // for accessing values
203 inline double actual_ghost_area() const {return _actual_ghost_area;}
204 inline int n_ghosts() const {return _n_ghosts;}
205
206 // when explicitly modifying values, sometimes call the initializer
207 inline void set_ghost_area (double val) {_ghost_area = val; _initialize();}
208 inline void set_ghost_rapmax (double val) {_ghost_maxrap = val; _initialize();}
209 inline void set_ghost_maxrap (double val) {_ghost_maxrap = val; _initialize();}
210 inline void set_ghost_etamax (double val) {_ghost_maxrap = val; _initialize();}
211 inline void set_ghost_maxeta (double val) {_ghost_maxrap = val; _initialize();}
212 inline void set_grid_scatter (double val) {_grid_scatter = val; }
213 inline void set_pt_scatter (double val) {_pt_scatter = val; }
214 inline void set_mean_ghost_pt(double val) {_mean_ghost_pt = val; }
215 inline void set_repeat (int val) {_repeat = val; }
216
217 inline void set_kt_scatter (double val) {_pt_scatter = val; }
218 inline void set_mean_ghost_kt(double val) {_mean_ghost_pt = val; }
219
220 /// if val is true, set ghost placement as it was in FastJet 2.X. The
221 /// main differences between FJ2 and FJ3 ghost placement are
222 ///
223 /// - in FJ2 the rapidity spacing was
224 /// ceil((maxrap-minrap)/sqrt(area)), while in FJ3 it is
225 /// int((maxrap-minrap)/sqrt(area) + 0.5) [similarly for phi].
226 /// The FJ3 option offers more stability when trying to specify a
227 /// spacing that exactly fits the extent.
228 ///
229 /// - in FJ2, the ghosts are placed at the corners of grid cells
230 /// (i.e. extending up to maxrap), while in FJ3 they are placed at
231 /// the centres of grid cells (i.e. extending roughly up to
232 /// maxrap-sqrt(area)). The FJ2 behaviour effectively skews the
233 /// total area coverage when maxrap is small, by an amount
234 /// sqrt(area)/(2*maxrap).
235 ///
236 /// FJ2 placement is now deprecated.
237 FASTJET_DEPRECATED_MSG("This is deprecated since we strongly recommend use of the new ghost placement instead",
238 void set_fj2_placement(bool val));
239
240 /// return nphi (ghosts layed out (-nrap, 0..nphi-1), (-nrap+1,0..nphi-1),
241 /// ... (nrap,0..nphi-1)
242 inline int nphi() const {return _nphi;}
243 inline int nrap() const {return _nrap;}
244
245 /// get all relevant information about the status of the
246 /// random number generator, so that it can be reset subsequently
247 /// with set_random_status.
248 ///
249 ///
250 inline void get_random_status(std::vector<int> & __iseed) const {
251 if (_user_random_generator){
252 _user_random_generator->get_status(__iseed);
253 } else {
254 _random_generator.get_status(__iseed);
255 }
256 }
257
258 /// set the status of the random number generator, as obtained
259 /// previously with get_random_status. Note that the random
260 /// generator is a static member of the class, i.e. common to all
261 /// instances of the class --- so if you modify the random for this
262 /// instance, you modify it for all instances.
263 inline void set_random_status(const std::vector<int> & __iseed) {
264 if (_user_random_generator){
265 _user_random_generator->set_status(__iseed);
266 } else {
267 _random_generator.set_status(__iseed);
268 }
269 }
270
271 /// allows to return a copy of this GhostedAreaSpec with a local set
272 /// of seeds
273 GhostedAreaSpec with_fixed_seed(const std::vector<int> & __iseed) const {
274 GhostedAreaSpec new_spec = (*this);
275 new_spec._fixed_seed = __iseed;
276 return new_spec;
277 }
278
279 /// returns the current fixed seed
280 void get_fixed_seed(std::vector<int> & __iseed) const {
281 __iseed = _fixed_seed;
282 }
283
284 /// allows the user to get the seed that was used at the start of the
285 /// last generation of ghosts.
286 ///
287 /// This should typically be access through the area definition held
288 /// by the ClusterSequenceArea, because the CSA class takes a copy of the
289 /// AreaDefinition and it is that copy that stored the
290 void get_last_seed(std::vector<int> & __iseed) const {
291 if (_repeat > 1) _warn_fixed_last_seeds_nrepeat_gt_1
292 .warn("Using fixed seeds (or accessing last used seeds) not sensible with repeat>1");
293 __iseed = _last_used_seed;
294 }
295
296 inline void checkpoint_random() {get_random_status(_random_checkpoint);}
297 inline void restore_checkpoint_random() {set_random_status(_random_checkpoint);}
298
299 /// for a summary
300 std::string description() const;
301
302 /// push a set of ghost 4-momenta onto the back of the vector of
303 /// PseudoJets
304 void add_ghosts(std::vector<PseudoJet> & ) const;
305
306 /// very deprecated public access to a random number
307 /// from the internal generator
308 inline double random_at_own_risk() const {return _our_rand();}
309 /// very deprecated public access to the generator itself
311 return _user_random_generator ? *_user_random_generator : _random_generator;}
312 /// access to the user-defined random-number generator. Will be empty if not set.
314 return _user_random_generator;}
315
316private:
317
318 // quantities that determine nature and distribution of ghosts
319 double _ghost_maxrap;
320 double _ghost_rap_offset;
321 int _repeat ;
322 double _ghost_area ;
323 double _grid_scatter;
324 double _pt_scatter ;
325 double _mean_ghost_pt;
326 bool _fj2_placement;
327
328 Selector _selector;
329
330 // derived quantities
331 double _actual_ghost_area, _dphi, _drap;
332 int _n_ghosts, _nphi, _nrap;
333
334
335 std::vector<int> _random_checkpoint;
336
337 // optional fixed seeds
338 std::vector<int> _fixed_seed;
339
340 // access to the seeds used the very last time
341 mutable std::vector<int> _last_used_seed;
342
343 // in order to keep thread-safety, have an independent random
344 // generator for each thread
345 //
346 // 2015-09-24: thread_local is not supported by Apple's version of
347 // clang! So we'll rely on something different here (see comment at
348 // the top of the class)
349 //#ifdef FASTJET_HAVE_LIMITED_THREAD_SAFETY
350 // static thread_local BasicRandom<double> _random_generator;
351 //#else
352 static BasicRandom<double> _random_generator;
353 //#endif
354 //mutable BasicRandom<double> _random_generator;
355
356 /// a set of seeds as defined by the end-user
357 std::vector<int> _user_defined_seeds;
358
359 // allow for a user-defined random generator
360 SharedPtr<BasicRandom<double> > _user_random_generator;
361
362 static LimitedWarning _warn_fj2_placement_deprecated;
363 static LimitedWarning _warn_fixed_last_seeds_nrepeat_gt_1;
364
365 inline double _our_rand() const {
366 return _user_random_generator ? (*_user_random_generator)() : _random_generator();}
367
368 inline void _our_rand(unsigned int npoints, double *pointer,
369 std::vector<int> & used_init_seed) const {
370 return _user_random_generator
371 ? (*_user_random_generator)(npoints, pointer, used_init_seed)
372 : _random_generator(npoints, pointer, used_init_seed);
373 }
374
375};
376
377/// just provide a typedef for backwards compatibility with programs
378/// based on versions 2.0 and 2.1 of fastjet. Since there is no
379/// easy way of telling people this is deprecated at compile or run
380/// time, we should be careful before removing this in the future.
382
383
384FASTJET_END_NAMESPACE
385
386#endif // __FASTJET_GHOSTEDAREASPEC_HH__
Parameters to configure the computation of jet areas using ghosts.
void get_last_seed(std::vector< int > &__iseed) const
allows the user to get the seed that was used at the start of the last generation of ghosts.
void set_random_status(const std::vector< int > &__iseed)
set the status of the random number generator, as obtained previously with get_random_status.
GhostedAreaSpec with_fixed_seed(const std::vector< int > &__iseed) const
allows to return a copy of this GhostedAreaSpec with a local set of seeds
GhostedAreaSpec(double ghost_maxrap_in, int repeat_in=gas::def_repeat, double ghost_area_in=gas::def_ghost_area, double grid_scatter_in=gas::def_grid_scatter, double pt_scatter_in=gas::def_pt_scatter, double mean_ghost_pt_in=gas::def_mean_ghost_pt, BasicRandom< double > *user_random_generator=NULL)
explicit constructor
SharedPtr< BasicRandom< double > > & user_random_generator_at_own_risk()
access to the user-defined random-number generator. Will be empty if not set.
GhostedAreaSpec(double ghost_minrap_in, double ghost_maxrap_in, int repeat_in=gas::def_repeat, double ghost_area_in=gas::def_ghost_area, double grid_scatter_in=gas::def_grid_scatter, double pt_scatter_in=gas::def_pt_scatter, double mean_ghost_pt_in=gas::def_mean_ghost_pt, BasicRandom< double > *user_random_generator=NULL)
explicit constructor
GhostedAreaSpec(double ghost_maxrap_in, BasicRandom< double > *user_random_generator)
explicit constructor
int nphi() const
return nphi (ghosts layed out (-nrap, 0..nphi-1), (-nrap+1,0..nphi-1), ... (nrap,0....
GhostedAreaSpec()
default constructor
BasicRandom< double > & generator_at_own_risk() const
very deprecated public access to the generator itself
void get_random_status(std::vector< int > &__iseed) const
get all relevant information about the status of the random number generator, so that it can be reset...
void get_fixed_seed(std::vector< int > &__iseed) const
returns the current fixed seed
double random_at_own_risk() const
very deprecated public access to a random number from the internal generator
class to provide facilities for giving warnings up to some maximum number of times and to provide glo...
Class that encodes information about cuts and other selection criteria that can be applied to PseudoJ...
Definition: Selector.hh:149
An implementation of shared pointers that is broadly similar to C++11 shared_ptr (https://en....
Definition: SharedPtr.hh:341