00001 Release Notes for fastjet
00002 -------------------------
00003
00004 ===========================================================
00005 Summary of changes from v2.4.X -> v3.0alpha1: 27 January 2011
00006 ===========================================================
00007
00008 This is an alpha release, previewing some of the new features that are
00009 expected to be available in FastJet version 3. Interfaces of new
00010 features may yet evolve.
00011
00012 New features:
00013 - Several extensions to PseudoJet:
00014 * it now knows what ClusterSequence it belongs to
00015 * info about internals of jets can be accessed e.g. as jet.constituents()
00016 * it now has a virtual destructor + other support for classes derived from PseudoJet
00017 * new facilities for associating user info with a jet (see PseudoJet::ExtraInfo)
00018 * some of these features make use of a new SharedPtr class
00019 (intended mainly for advanced users)
00020 similar to C++0x std::shared_ptr
00021 * calculation of phi and rapdity (cached) only on request
00022 - R can now be taken larger than pi/2 for natively coded jet algorithms
00023 - Addition of "Selector" tools through #include "fastjet/tools/Selector.hh"
00024 - New plugin for D0RunICone (code contributed by Lars Sonnenschein)
00025 - Improvements to fortran wrapper (access to SISCone, jet constituents, etc.)
00026
00027 Bug fixes:
00028 - fixed issue with inconsistent returned sign in PseudoJet::delta_phi_to(...)
00029
00030 Other notable changes:
00031 - Revamping of examples
00032 - by default all plugins are now packaged into libfastjetplugins.
00033 Note that "external" libraries like libsiscone are still separate.
00034 - Significant improvements to doxygen documentation
00035
00036 ===========================================================
00037 Summary of changes from v2.4.1 -> v2.4.2: 26 February 2010
00038 ===========================================================
00039 - exclusive_ymerge_max(...) was not working; now fixed
00040 - the D0RunIIConePlugin gave segfaults for some parameters; now fixed
00041 - the D0RunIIConePlugin gave different results on 32/64 bit machines;
00042 optimisation flags now changed just for D0 code so that 32 bit gives same
00043 results as 64 bit.
00044 - changes to configure.ac to better handle fortran compiler checks
00045 - removed some orphan/redundant code that was generating compilation warnings
00046 - added an "--enable-monolithic" option to ./configure which causes
00047 all plugins to be placed in a single library (except SISCone)
00048 - added a "--list-plugins" option to fastjet-config
00049
00050 =======================================================
00051 Summary of changes from v2.4.0 -> v2.4.1: 29 May 2009
00052 =======================================================
00053
00054 Fixes to the build system
00055 -------------------------
00056 - Included SISCone 2.0.1 (shared libs now enabled by default in
00057 SISCone too, and other small fixes)
00058 - Fixed platform-dependent failures during make check
00059 - Fixed gcc 4.4 compatibility issues (missing headers)
00060 - Fixed a problem on Mac OS X with the arguments provided by
00061 "fastjet-config --libs" (--rpath versus -rpath).
00062 - fastjet-config has new optional arguments (--rpath=no, --runpath)
00063 related to finding shared libraries at runtime on linux.
00064 Run fastjet-config without any arguments for more info.
00065 To instead use static libraries, either configure with the
00066 --disable-shared option, or use fastjet-config with the --shared=no option.
00067 - fastjet-config can now take --cxxflags and --libs in a single invocation
00068 - With --cxxflags, fastjet-config now returns the minimal required set of arguments
00069 - Various other small mods (better fortran support, standardisation, ...)
00070 [thanks to Andy Buckley and David Grellscheid for suggestions]
00071
00072 Also
00073 ----
00074 - Added a fortran wrapper for pp sequential recombination algorithms
00075 - Fixed issue in median rho estimation when some jets have zero area
00076 - Expanded descriptions that are returned by ATLAS/TrackJet/CMS plugins
00077 - Warnings are no longer given when using exclusive jets with
00078 Cam/Aachen and certain e+e- algorithms (the warnings were misleading)
00079 - Small fixes to the manual
00080
00081 =======================================================
00082 Summary of changes from v2.3.X -> v2.4.0: 17 April 2009
00083 =======================================================
00084
00085
00086 New pp algorithms
00087 -----------------
00088
00089 - added implementation of generalised kt algorithm (genkt_algorithm) for pp
00090 - added D0RunIICone plugin [--enable-d0runiicone at configure time]
00091 - added ATLASCone Plugin [--enable-atlascone at configure time]
00092 - added CMSIterativeConePlugin [--enable-cmsiterativecone at configure time]
00093 - added TrackJet Plugin (used by CDF in UE studies)
00094 [--enable-trackjet at configure time]
00095
00096 Introduction of e+e- algorithms
00097 -------------------------------
00098
00099 - added an implementation of the e+e- kt algorithm (ee_kt_algorithm),
00100 - added EECambridgePlugin for the (original) e+e- Cambridge algorithm
00101 - added JADEPlugin for the JADE algorithm (see the ChangeLog or header
00102 file for details)
00103 - added SISConeSphericalPlugin [enabled by default] for SISCone in
00104 e+e- and other spherical environments.
00105 - native implementation of generalised kt algorithm for e+e- (ee_genkt_algorithm)
00106 [also provides access to e+e- form of anti-kt alg, conical jets on a sphere]
00107 - added JadePlugin for the e+e- Jade algorithm
00108
00109 Meta-algorithms
00110 ----------------
00111
00112 - added NestedDefs plugin for daisy-chaining multiple jet definitions
00113 [still under testing; API may change in the future]
00114
00115 New functionality
00116 -----------------
00117 - added subjet functions for viewing jet at particular dcut, etc.
00118 - added access to exclusive jets based on ycut as well as dcut (for e+e-)
00119 - added support for asymmetric rapidity ranges in GhostedAreaSpec
00120 - added support for a CircularRange (derived from RangeDefinition) for
00121 use in background estimation
00122 - added class NNH to help users implement algorithms with
00123 user-chosen distance measure (see JadePlugin for an example)
00124
00125 Interface modifications
00126 -----------------------
00127 - removed default value of 0.5 for overlap_threshold in
00128 CDFMidPointPlugin, CDFJetCluPlugin and SISConePlugin constructors
00129
00130 *** may break backwards compatibility ***
00131
00132 - a JetDefinition(jet_alg) constructor, without an R value, is no
00133 longer legal, except when jet_alg is ee_kt_algorithm (it has no R).
00134
00135 *** may break backwards compatibility ***
00136
00137 - in SISCone, new way of accessing the information about pass at which
00138 a jet was found (old method retained for 2.4, but now deprecated)
00139
00140
00141 Configure modifications
00142 -----------------------
00143 - added --enable-allplugins and --enable-allcxxplugins options, to
00144 avoid having to specify a long list of individual plugins
00145 - shared libraries are now enabled by default
00146
00147 Bugs fixed
00148 ----------
00149 - fixed missing support for periodicity in azimuth in RangeDefinition
00150 class
00151
00152 Other modifications
00153 -----------------------
00154 - added support for CGAL 3.4 (for non-standard locations, specify
00155 --with-cgaldir at configure time)
00156 - removed restriction that fastjet throws exception on empty events
00157 - added an example that illustrates the use of subjet techniques for
00158 a boosted Higgs->b+bbar search
00159
00160 Still to come
00161 -------------
00162 - add CMSIterativeCone Plugin
00163
00164
00165
00166 =======================================================================
00167 Summary of changes from v2.3.3 -> v2.3.4 (bug fix release): 15 Aug 2008
00168 ==========================================================
00169
00170 - fixed infinite-loop bug in JetClu plugin on certain rare events
00171
00172 - fixed compatibility issues of certain example programs with g++-4.3
00173
00174 - incorporated SISCone 1.3.3 with similar g++-4.3 fixes
00175
00176 =======================================================================
00177 Summary of changes from v2.3.2 -> v2.3.3 (bug fix release): 28 Apr 2008
00178 ==========================================================
00179
00180 - fixed missing installation of .../config_auto.h
00181
00182 - fixed missing typename in .../SearchTree.hh
00183
00184 =======================================================================
00185 Summary of changes from v2.3.1 -> v2.3.2 (bug fix release): 03 Apr 2008
00186 ==========================================================
00187
00188 - fixes to propagation of CXXFLAGS through the build chain
00189
00190 - small change in Voronoi area code to fix crashes on regular
00191 (calorimeter) layouts of momenta
00192
00193 - small change in active areas code to fix crashes on algorithms that
00194 do not cluster all particles
00195
00196 - eliminated "using namespace std" that had accidentally been left in
00197 certain area header files
00198
00199 - incorporation of SISCone 1.3.2 with fixes for inappropriate public
00200 symbols and to build framework
00201
00202
00203 ======================================================================
00204 Summary of changes from v2.3.0 -> v2.3.1 (bug fix release)
00205 ==========================================================
00206
00207 - Fixed compilation issues under windows VC7.1 (reported by
00208 I. Belyaev); also included SISCone 1.3.1 with similar fixes.
00209
00210 - Fixed speed issue under optimized compilation of CDF MidPoint plugin
00211 for 32 bit architectures that had arisen subsequent to the switch to
00212 autotools with its common optimization settings.
00213
00214 - Fixed "make check" failure with the --disable-siscone option.
00215
00216 - Fixed crash in exclusive_dmerge(njets) for njets=0 (reported by P. Lenzi)
00217
00218
00219 ======================================================================
00220 Summary of changes from v2.1.0 (previous stable release) to v2.3.0
00221 ===================================
00222
00223 - added the anti-kt algorithm (LPTHE-07-03), which is a sequential
00224 recombination algorithm that gives conical jets.
00225
00226 - Added Passive and Voronoi areas, and new common class for accessing
00227 all types of areas, ClusterSequenceArea.
00228
00229 - switched to autotools for compilation and installation:
00230 ./configure --prefix=...
00231 make
00232 make check [optional]
00233 make install
00234
00235 NB: users should no longer include fastjet-2.x.y/Makefile
00236 when building their own programs, and instead should use
00237 g++ -c file.cc `fastjet-config --cxxflags`
00238 g++ file.o `fastjet-config --libs --plugins`
00239
00240 - plugin include files are now to be accessed with fastjet/ in
00241 front of them, i.e.
00242 #include "fastjet/SISConePlugin.hh"
00243 A simple #include "SISConePlugin.hh" is now obsolete but will
00244 continue to work through 2.x
00245
00246 - Added RangeDefinition class to provide more flexibility in UE/pileup
00247 estimation.
00248
00249 - New facilities for navigating the cluster sequence (has_parents,
00250 has_child and has_partner members of ClusterSequence)
00251
00252 - other bug fixes and small enhancements (including SISCone-1.3.0,
00253 improvements to plugin facilities).
00254
00255 See individual beta-releases below for more information, as well as
00256 the ChangeLog.
00257
00258
00259 ======================================================================
00260 Changes from v2.2beta0 to v2.3-beta0
00261 ===================================
00262
00263 - switched to autotools for compilation and installation;
00264
00265 - old build procedure still available for now, with files called
00266 makefile.static (make -f makefile.static);
00267
00268 test-script.sh has been renamed test-static.sh and builds and
00269 tests using the old procedure.
00270
00271 - plugins include files are now to be accessed with fastjet/ in
00272 front of them, i.e.
00273 #include "fastjet/SISConePlugin.hh"
00274
00275 For backwards compatibility, the old access method will continue
00276 to work throughout v2.x, i.e.
00277 #include "SISConePlugin.hh"
00278
00279 - added PseudoJet::reset(...) functions to reset the contents of a
00280 PseudoJet.
00281
00282 - added fastjet_version_string()
00283
00284 - added a function PtYPhiM(...) that returns a PseudoJet with the
00285 given py, rapidity , phi and mass. Defined in PseudoJet.hh
00286
00287 - added a directory fortran_wrapper/ to illustrate how to access
00288 fastjet from fortran
00289
00290 - some small bug fixes in the CDF midpoint code
00291
00292
00293 ======================================================================
00294 Changes from v2.1.0 to v2.2beta0
00295 ===============================
00296
00297 - added the anti-kt algorithm (LPTHE-07-03)
00298
00299 - Provided a new common class for accessing all different types of
00300 areas: ClusterSequenceArea.
00301
00302 - added functionality for Passive areas and Voronoi areas.
00303 Areas are now defined much in the same way as jets, via an
00304 AreaDefinition, which is passed as an argument
00305 to ClusterSequenceArea. NB: the Voronoi area uses Fortune's
00306 sweepline code for calculating the Voronoi diagram and so does not
00307 require CGAL to be installed (it still is needed for NlnN kt
00308 clustering).
00309
00310 - Added class RangeDefinition which allows detailed definitions
00311 of the rapidity-azimuth ranges over which to study jet areas
00312 and possibly perform noise subtraction
00313
00314 - added facilities for navigating the cluster sequence (has_parents,
00315 has_child and has_partner members of ClusterSequence)
00316
00317 - changed plugin base class, so that it now includes R() virtual
00318 member, and modified the various plugins to account for this.
00319
00320 - modified the plugin interface to provide facilities to help with
00321 passive areas.
00322
00323 - included SISCone-1.2.0 rather than 1.1.1.
00324
00325 - adapted SISCone plugin to the 1.2.0 release of SISCone -- main
00326 changes are facilities and improvements related areas: some speed
00327 improvements on the split-merge (relevant for active areas) and a
00328 fairly efficient way of running passive areas.
00329
00330 - added ClusterSequence::print_jets_for_root(...) and a corresponding root
00331 script (example/root/jet-plots.C), so as to provide a crude
00332 visualisation tool.
00333
00334
00335 ======================================================================
00336 Summary of main changes from v2.0.0 to v2.1.0
00337 =============================================
00338
00339 - added plugin structure for external jet finders.
00340
00341 - included plugins for SISCone, CDFMidPoint, CDFJetClu, PxCone (with
00342 extensions for MidPoint and bug fixes for PxCone relative to public
00343 codes).
00344
00345 - introduced option of control over recombination scheme, with a
00346 RecombinationScheme enum, which applies also to area_4vector.
00347
00348 - added description() member function to JetDefinition class, so
00349 that you can get a (string) summary of what you're running!
00350
00351 - changed the default number of repeats in ActiveAreaSpec to 1 (which
00352 is sufficient for most purposes).
00353
00354 For further details, see the changes listed in detail below.
00355
00356 ======================================================================
00357 Changes from v2.1.0b4 to v2.1.0
00358 ===============================
00359
00360 - corrected bug in test-script.sh
00361
00362 - removed PxCone from default tests and from
00363 plugins/usage_examples/many_algs_example.cc (to avoid fortran
00364 compilation issues).
00365
00366 ======================================================================
00367 Changes from v2.1.0b3 to v2.1.0b4
00368 =================================
00369
00370 FastJet modifications
00371 ---------------------
00372
00373 - default number of repeats for the active area specification has been
00374 changed from 5 to 1 (the latter goes fast, but note that it provides
00375 a zero error estimate for the area).
00376
00377 Plugin modifications
00378 --------------------
00379
00380 - adapted plugin to accomodate new scale for use in the SISCone
00381 split-merge (pttilde), with a corresponding change of interface.
00382
00383 Changed default number of passes for SISCone to 0.
00384
00385 - Added the pttilde scale choice to the CDF plugin.
00386
00387
00388
00389 ======================================================================
00390 Changes from v2.1.0b2 to v2.1.0b3
00391 =================================
00392
00393 FastJet enhancements
00394 --------------------
00395
00396 - methods for estimating the underlying now have the option of using
00397 area_4vector rather than the plain area
00398
00399 FastJet bug fixes
00400 -----------------
00401
00402 - area_4vector is now calculated with the same recombination scheme as
00403 the jets themselves
00404
00405 - massless recombination schemes now work correctly on particles with
00406 zero momentum
00407
00408 - PseudoJet::phi_std() returned wrong result for phi < pi -- thanks to
00409 Oscar Stal for pointing this out.
00410
00411 Plugin modifications
00412 --------------------
00413
00414 - the plugin mechanism now allows a plugin to add "extra" information
00415 to the ClusterSequence, essentially by providing an auto_ptr to a
00416 class derived from (the new) ClusterSequence::Extras; an example of
00417 this has been implemented with siscone (SISConeExtras) which allows
00418 a user to access the initial (stable) protocones.
00419
00420 - included new siscone version (1.1) which uses transverse mass (mt) rather
00421 than pt in the split-merge procedure, to address an IR problem in
00422 events where the hadronic part conserves momentum -- this can have
00423 an effect on some physical distributions; the siscone update also
00424 addresses issues with collinear safety and co-circular points.
00425
00426 - included bug fixes to pxcone regarding 2pi periodicity when
00427 recombining momenta
00428
00429 - modified the version of the CDF midpoint cone code so as to allow it
00430 to use mt and Et as the parameters in the split--merge step.
00431
00432 ======================================================================
00433 Changes from v2.1.0b1 to v2.1.0b2
00434 =================================
00435
00436 Bug fixes
00437 ---------
00438
00439 - included new siscone version which solves the memory-leak problem
00440
00441 Other changes
00442 -------------
00443
00444 - added sample output from the test-script as test-script-output-orig.txt
00445
00446 ======================================================================
00447 Changes from v2.1.0b0 to v2.1.0b1
00448 =========================
00449
00450 New features:
00451 -------------
00452
00453 - added the SISCone plugin and the beta version of the siscone code
00454 (authored by Soyez & Salam)
00455
00456 Bug fixes
00457 ---------
00458
00459 - removed extraneous semicolons after functions that were causing
00460 problems on some compilers.
00461
00462 Other additions
00463 ---------------
00464
00465 - Added COPYING file with GPL license
00466
00467 ======================================================================
00468 Changes from v2.0 to v2.1 (beta0)
00469 =========================
00470
00471 New features:
00472 -------------
00473
00474 - introduced option of control over recombination scheme, with a
00475 RecombinationScheme enum (a variable of this type should be provided
00476 to the JetDefinition constructor) and also the possibility of an
00477 externally defined recombination scheme.
00478
00479 - introduced a "plugin" facility for alternative jet finders, via an
00480 abstract base class
00481
00482 class JetDefinition::Plugin
00483
00484 Plugins are to be provided as classes derived from this,
00485 implementing the relevant virtual functions (see manual and examples
00486 for further info).
00487
00488 - introduced "description" member function for the JetDefinition
00489 class, which returns a (std::string) textual description of the
00490 algorithm defined.
00491
00492 - provided plugins for CDF JetClu, CDF Midpoint, PxCone code; the
00493 plugins, the code they interface to and example programs are to be
00494 found in the new plugins/ directory.
00495
00496 - added ClusterSequence::unclustered_particles() a vector containing
00497 the unclustered particles (relevant for some plugin algorithms).
00498
00499 Minor additions
00500 ---------------
00501
00502 - introduced PseudoJet::squared_distance (does same as "plain_distance")
00503
00504
00505
00506 Notational changes:
00507 -------------------
00508
00509 - in the documentation, replaced eta -> y, to make it clear that it's
00510 rapidity and not pseudorapidity that is being used throughout. Some
00511 internal code continues to use variables called "eta" -- but these
00512 are actually proper rapidity.
00513
00514
00515 ======================================================================
00516 Changes from v1.0 to v2.0
00517 =========================
00518
00519 New features:
00520 -------------
00521
00522 - the longitudinally invariant inclusive Cambridge/Aachen jet finder
00523 has been added.
00524
00525 Note that the exclusive jets extraction for the Cambridge jet-finder
00526 does not provide the definition as given in the original Cambridge
00527 paper. See the documentation for further details
00528
00529 - classes have been introduced for running jet clustering and
00530 simultaneously collecting information about the area of each jet.
00531 The base class specifying the functionality is
00532
00533 class ClusterSequenceWithArea;
00534
00535 itself derived from ClusterSequence.
00536
00537 Two derived classes that provide the actual areas functionality are:
00538
00539 class ClusterSequenceActiveArea;
00540 class ClusterSequenceActiveAreaExplicitGhosts;
00541
00542 To construct them, one also needs to specify how one wishes the area
00543 to be calculated, via a class
00544
00545 class ActiveAreaSpec;
00546
00547
00548 New optimizations:
00549 ------------------
00550 - new clustering strategies have been added:
00551
00552
00553 N2MinHeapTiled : like N2Tiled, except that the non-geometric
00554 part has been replaced with a N ln N algorithm
00555 (overall the strategy still scales as N^2, but with a
00556 smaller coefficient)
00557
00558 NlnNCam, NlnNCam2pi2R, NlnNCam4pi:
00559
00560 NlnN strategies specific to the Cambridge/Aachen
00561 jet-finder -- the fastest of them is NlnNCam.
00562 Depending on the size of the event and of the CPU
00563 cache it may be up to 2.5 times faster than the
00564 CGAL-based NlnN strategy. Experiment on your own
00565 hardware and events to establish whether the
00566 speed gain is significant.
00567
00568 These strategies are based on the work on dynamic
00569 Closest Pair problems by Timothy Chan.
00570
00571 Best : (was present before) now attempts to select best
00572 among N2Plain, N2Tiled, N2MinHeapTiled, NlnN.
00573
00574 As the best option for a given N may depend on R
00575 and the event structure, you are advised to
00576 experiment with individual strategies if the
00577 last few tens of percent in speed are critical.
00578
00579
00580
00581 Updates to user interface
00582 -------------------------
00583
00584 While the v1 interface to fastjet has been maintained for backwards
00585 compatibility, for new developments in v2 and related forthcoming
00586 work, a new interface is provided as follows:
00587
00588 - User accessible classes and enums have had the "Fj" prefix removed
00589 and are instead now in namespace fastjet; the corresponding include
00590 files are in the include/fastjet directory. So, for example instead
00591 of
00592
00593 #include "FjClusterSequence.hh"
00594
00595 FjClusterSequence clust_seq(...)
00596
00597 one now uses the following
00598
00599 #include "fastjet/ClusterSequence.hh"
00600
00601 fastjet::ClusterSequence clust_seq(...)
00602
00603 If typing "fastjet::" the whole time seems too long-winded, you can
00604 abbreviate "fastjet" as "fj" with
00605
00606 namespace fj = fastjet;
00607
00608 or eliminate the need for it altogether with
00609
00610 using namespace fastjet;
00611
00612 - a new class, fastjet::JetDefinition, has been introduced for holding
00613 the details of the jet finder (which one, value of R, etc...) that
00614 is to be used in a given clustering.
00615
00616 #include "fastjet/JetDefinition.hh"
00617 #include "fastjet/ClusterSequence.hh"
00618
00619
00620 double R = 0.7;
00621
00622
00623 fastjet::JetDefinition jet_def(fastjet::kt_algorithm, R);
00624
00625
00626
00627 fastjet::ClusterSequence clust_seq(momenta, jet_def);
00628
00629 - some errors that previously were assertions now throw an
00630 fastjet::Error -- exception. A fully uniform handling of exceptions
00631 is currently some way away however and users for whom this is an
00632 important issue should contact the authors.
