PWG4/JetCorrel/README

   1 The libJetCorrel library implements generic two-particle correlations between
   2 a "trigger" and an "associated" particle, where these to can be any physical
   3 particle ((un)identified hadron, photon, pi0, (di)electron, jet, etc.). It can
   4 run several correlations at the same time with the advantage of keeping the
   5 minimum number of mixing pools in memory (for eg., if one runs di-hadron and
   6 pi0-hadron correlations, only one associated pool of hadrons is stored).
   7
   8 The running/JetCorrelSelector.C macro that accompanies the main running macro
   9 instantiates and returns the AliJetCorrelSelector class (see below) that sets
  10 all the input parameters needed for running. The parameter names should be
  11 obvious. Comments:
  12 (a) the binning (vertex, centrality/multiplicity, trigger&associated pT) is
  13 loaded thru simple dynamic arrays (originally STL vectors, but forbidden in
  14 AliRoot), hence not only they values, but their number can be changed;
  15 (b) the CorrelTypes dynamic array has the same property and allows the running
  16 of many types of "trigger"-"associated" correlations simultaneously (thus
  17 reducing the CPU&memory since most correlations typically share the same assoc
  18 types - hadrons). Finally, adding a new type of correlation to JetCorrel implies
  19 only two new methods: one in AliJetCorrelSelector that reads and applies the
  20 cuts specific to any new type of particle and another one in AliJetCorrelReader
  21 that fills the internal lists of that particle type. JetCorrel then takes care
  22 automatically of all the rest (mixing, histogramming, etc.) because for it
  23 the new list becomes just a trigger and/or associated list...
  24
  25 Analysis Task Classes:
  26 (1) AliAnalysisTaskJetCorrel class
  27 Main class which inherits from AliAnalysisTaskSE and runs the show by delegating
  28 sub-tasks to the following classes:
  29 (2) AliJetCorrelSelector class
  30 Is the class that reads user-defined selections and propagates them thru the
  31 rest of the code. The macro JetCorrelSelector.C instantiates it and sets:
  32 the correlations to be run, the centrality/vertex/momentum binnings and various
  33 selections and cuts to be applied.
  34 (3) AliJetCorrelMaker class
  35 Reads the list of correlations to be run from the Selector and builds the
  36 interface needed to manipulate them.
  37 (4) AliJetCorrelReader class
  38 Reads the list of selections and cuts from the Selector and builds the two
  39 trigger and associated CorrelList_t lists for one event and one correlation.
  40 For example, if in the current run we ask for hadron-hadron, Z0-hadron and
  41 gamma-hadron, then 3 trigger lists but only 1 associated list are built each
  42 event.
  43 (5) AliJetCorrelWriter class
  44 Reads the list of binnings from the Selector and books the arrays of output
  45 correlation histograms; it also has methods for filling them.
  46 (6) AliJetCorrelMixer class
  47 Manages the event mixing pools. The mixing method is rolling buffer (hence is
  48 kept in memory) and the mixing pools are 4-dimensional static arrays of
  49 2-dimensional dynamic lists; the 4 static dimensions correspond to pool type
  50 (triggs/assocs), pool type bin, vertex bin, centrality bin and they are all
  51 fixed at task initialization time (via the Selector). Then, each of these pools
  52 is a TList of events, each event being a CorrelList_t of particles (CorrelParticle_t
  53 or upper class). Taking into account that sizeof(CorrelParticle_t)=20b and
  54 sizeof(CorrelListNode_t)=8b (two pointers are used by CorrelList_t to store a
  55 particle) one gets the pool sizes:
  56 - for p-p analyses:
  57 2(type)x2(centrality)x10(vertex)x20(events)x30(particles)x28b<0.7Mb
  58 - for Pb-Pb analyses:
  59 2(type)x7(centrality)x10(vertex)x20(events)x3000(particles)x28b<250Mb
  60 Caveats: these values are for one associated pool (which dominates) and consider
  61 rather high stored particle multiplicities per event (3000 associates per event).
  62 For eg., in jet induced correlation studies, we are interested only in pT>1GeV/c.
  63
  64 Particle Container Classes:
  65 (1) CorrelParticle_t class.
  66 Base particle for correlations: implements only the essential kinematics needed
  67 for correlations. Since this is the object to go into the mixing pools (and into
  68 the memory) DON'T CLUTTER IT!!! As it stands now, its size is 20b (4xFloat_t+
  69 1xUInt_t) on 32b machines. Also, it MUST NOT inherit from TObject since this will
  70 impose an overhead of 12b (>30%) by inheritance, a burden that cannot be carried
  71 in Pb-Pb analysis. BTW, this is the main reason to have CorrelList_t instead of
  72 another TList for particles.
  73 (2) CorrelList_t class.
  74 A custom-designed single-linked list class written because the main two options
  75 (STL and ROOT) couldn't be used - STL because is not allowed in AliRoot and ROOT
  76 because its lists (TList/TClonesArray) store only objects of classes inheriting
  77 from TObject (thus inheriting a significant overhead for small particle objects
  78 like CorrelParticle_t). Note that CorrelList_t itself does inherit from TObject
  79 in order to be storeable in a TList (our mixing pools are TLists of CorrelLists)
  80 but this is OK since we have one CorrelList_t per event, not per particle. There
  81 are two helper classes: CorrelListNode_t for the data node and CorrelListIter_t
  82 provides utilities for list iteration. See CorrelList.h for interface description.
  83 (3) CorrelTrack_t class.
  84 Inherits from CorrelParticle_t and allows storage of global track parameters
  85 (TPC entrance coordinates) to be used in pair cuts (to eliminate detector
  86 resolution effects). Whether this cut (and hence this class altogether) will be
  87 used remains to be seen since it is possible that such effects can be eliminated
  88 thru single-track cuts (like high number of TPC clusters) - highly desireable
  89 because CorrelTrack_t would additionally store 12b for something like TPC entrance
  90 point (x,y,z).Note: any cut applied to the same event pairs must be applied to
  91 mixed event pairs (hence pair cut parameters must be stored in the mixing pools).
  92 On the other hand the high number of TPC clusters cut reduces the efficiency...
  93 (4) CorrelRecoParent_t class.
  94 Inherits from CorrelParticle_t and reconstructs (using TLorentzVector) parent
  95 particles from two children; intended for diphotons (pi0), dielectrons (Z0), etc.
  96 In the case of dielectrons (Z0), a reconstruction via the AliKFParticle class is
  97 provided since this also allows for a vertex cut on the reconstructed mother (see
  98 the CorrelKFTrack_t class). To switch between a TLorentzVector based reconstruction
  99 and a AliKFParticle based reconstruction, set kUseAliKF in CorrelDefs.h.
 100 (5) CorrelKFTrack_t class.
 101 Inherits from CorrelParticle_t and allows storage of ESD track parameters needed
 102 as input by the AliKFParticle to reconstruct the parent particle.
 103
 104 CorrelList_t class implements a single-linked list with pointer to head node
 105 (last inserted). It is labelled by 3 identifiers: the event number EvtID, the
 106 pool type (triggs/assocs) PoolID, and the particle type PartID. Interface:
 107  - CorrelList_t() creates empty list; ~CorrelList_t() destroys the list;
 108  - Clear() deletes all data nodes but leaves list defined (and empty);
 109  - Push() adds a new data node at head;
 110  - Head() returns iterator to head node;
 111  - assignment operator = performs a deep list copy;
 112  - Size() returns the current size of the list;
 113  - Filled() and SetFilled() gets/sets a boolean with the current fill status;
 114  - EvtID(), PartID(), and PoolID() return the list identifiers;
 115  - Label() sets the above list identifiers.
 116 CorrelList_t must inherit from TObject to be storable in a TList - the mixing
 117 pool becomes a TList of CorrelList. Access to the list data is made thru the
 118 iterator class.
 119 CorrelListIter_t class implements an iterator for CorrelList_t. Interface:
 120  - hasEnded() returns true if current node terminates list;
 121  - Move() moves iterator to next node in list;
 122  - Node() returns the current node pointed to by the iterator;
 123  - Data() returns the data contained in the current node;
 124
 125
 126 TO DO LIST AS OF 24 MARCH 2009:
 127 (1) finish the macros for output merging, acceptance study and correlation
 128     building in the analysis directory;
 129 (2) add a dynamic array CorrelArray_t implementation for the particle lists.
 130 (3) implement the official AliRoot logging (AliDebug/AliError/etc)