/[PAMELA software]/PamCut/doc/PamCutDevGuide.tex
ViewVC logotype

Diff of /PamCut/doc/PamCutDevGuide.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1.1.1 by pam-fi, Wed May 27 13:30:01 2009 UTC revision 1.5 by pam-fi, Tue Oct 27 10:24:36 2009 UTC
# Line 16  scratch every time a specific cut is nee Line 16  scratch every time a specific cut is nee
16  inherits form {\bf PamCut} and provides an implementation for the pure virtual  inherits form {\bf PamCut} and provides an implementation for the pure virtual
17  method {\bf Check}.  method {\bf Check}.
18  A special derived class is {\bf PamCutCollection}. This is a sort of a  A special derived class is {\bf PamCutCollection}. This is a sort of a
19  container for basic cuts, and is considered as a single cut. Its {\bf Check}  container for basic cuts, and is considered as a single cut. It has an {\bf
20    AddCut} method which will add a cut to the collection. Its {\bf Check}
21  implementation simply invokes all the {\bf Check}s of the single cuts, and it  implementation simply invokes all the {\bf Check}s of the single cuts, and it
22  is successful if all the single cuts are succesful.  is successful if all the single cuts are succesful. {\bf PamCut} also provides
23  {\bf PamCut} also provides the interface for two methods for post-processing:  the interface for two methods for post-processing: {\bf OnGood} and {\bf
24  {\bf OnGood} and {\bf OnBad}. In derived classes these can contain specific  OnBad}. In derived classes these can contain specific tasks to be performed
25  tasks to be performed whenever an event satisfy the {\bf Check} condition or  whenever an event satisfy the {\bf Check} condition or not. The method {\bf
26  not. The method {\bf ApplyCut} takes care of invoking {\bf Check} and  ApplyCut} takes care of invoking {\bf Check} and subsequently calls {\bf
27  subsequently calls {\bf OnGood} or {\bf OnBad} according to the result of {\bf Check}.  OnGood} or {\bf OnBad} according to the result of {\bf Check}. Summarizing,
28  Summarizing, {\bf Check}ing an event simply means to ask the object if the  {\bf Check}ing an event simply means to ask the object if the event satisfy
29  event satisfy the selection criteria; applying a cut means to check and then  the selection criteria; applying a cut means to check and then perform
30  perform post-selection tasks. The cut can be applied to a bunch of events by  post-selection tasks. The cut can be applied to a bunch of events by means of
31  means of the {\bf Process} method.  the {\bf Process} method.
32    
33  \subsection{More on collections}  \subsection{More on collections}
34  A collection is an object which inherits from {\bf PamCutCollection}, which in  A collection is an object which inherits from {\bf PamCutCollection}, which in
# Line 67  OnBad} if all the cuts have been satisfi Line 68  OnBad} if all the cuts have been satisfi
68  {\bf PamCutCollection}. See the Doxygen html documentation for more info about  {\bf PamCutCollection}. See the Doxygen html documentation for more info about
69  {\bf BlindCutCollection} and other specific cut implementations.  {\bf BlindCutCollection} and other specific cut implementations.
70    
71    \subsection{Collections and memory management}
72    
73    Regarding to cuts ownership, a collection will by default own its cuts. This
74    means that when you add a cut to a collection calling {\bf AddCut} with a
75    pointer to the cut as argument, the collection will store this pointer and
76    will take charge of deleting it. This is done by the collection's destructor.
77    This way, a user can simply add a cut to a collection and forget about
78    deleting it. However, sometimes this feature is not desirable, so it can be
79    turned off by passing a proper value to the collection's constructor. In this
80    case, the user is in charge of managing the memory allocated for the cuts.
81    
82    
83  \section{Actions and the SmartCollection}  \section{Actions and the SmartCollection}
84  When performing an analysis, each time an event is selected as good some  When performing an analysis, each time an event is selected as good some
85  actions are likely to be performed, like filling histograms or writing a  actions are likely to be performed, like filling histograms or writing a
# Line 81  class, which does nothing but defining t Line 94  class, which does nothing but defining t
94  implementations will be called actions.\\  implementations will be called actions.\\
95  Actions are automatically handled by the {\bf SmartCollection} class. It  Actions are automatically handled by the {\bf SmartCollection} class. It
96  inherits from {PamCutCollection}, and contains a vector of {\bf  inherits from {PamCutCollection}, and contains a vector of {\bf
97  CollectionAction} objects. These actions can be added using {\bf  CollectionAction} objects. These actions can be added calling {\bf
98  SmartCollection::AddAction}; for each of them, the collection will take care of  SmartCollection::AddAction}; for each of them, the collection will take care of
99  calling {\bf Setup} at the beginning of the analysis, {\bf OnGood} and {\bf  calling {\bf Setup} at the beginning of the analysis, {\bf OnGood} and {\bf
100  OnBad} for every event (depending on the selection result), and {\bf Finalize}  OnBad} for every event (depending on the selection result), and {\bf Finalize}
101  at the end of the analysis. In all other aspects, it behaves exactly as {\bf  at the end of the analysis. In all other aspects, it behaves exactly as {\bf
102  PamCutCollection}.\\  PamCutCollection}. The handling of the actions depend on their position with
103    respect to cuts. In the main analysis code, cuts can be added to the
104    collection; then, an action or more can be added. This sequence of cuts and the
105    actions added after the cuts will be called a bunch. The last bunch may have no
106    actions at its end.
107    \begin{verbatim}
108      .
109      .
110      .
111    Cut1 cut1(``cut1'');
112    Cut2 cut2(``cut2'');
113    Action1 action1(``action1'');
114    
115    Cut1 cut3(``cut3'');
116    Cut2 cut4(``cut4'');
117    Cut1 cut5(``cut5'');
118    Cut2 cut6(``cut6'');
119    Action1 action2(``action2'');
120    Action1 action3(``action3'');
121      .
122      .
123      .
124    \end{verbatim}
125    In the example above, {\bf cut1}, {\bf cut2} and {\bf action1} are the first
126    bunch,  {\bf cut3}, {\bf cut4}, {\bf cut5}, {\bf cut6}, {\bf action2} and {\bf
127    action3} are the second bunch and so on. If all the cuts in the bunch are
128    successful, the {\bf SmartCollection} will call {\bf OnGood} for every action
129    in that bunch, and then the analysis will go on with the next bunch for the same
130    event. If a certain cut in a bunch fails, then {\bf OnBad} is called for the
131    actions of the bunch, but successive bunches are ignored; the current event is
132    discarded and the focus switches on the next one (the {\bf
133    SmartBlindCollection} behaves a little different; see the Doxygen
134    documentation for more details.)
135    \\
136  Loosely speaking, after defining an action one simply has to instantiate it,  Loosely speaking, after defining an action one simply has to instantiate it,
137  add it to a {\bf SmartCollection} and launch the analysis (fire and  add it to a {\bf SmartCollection} and launch the analysis.
138  forget\ldots).  
139    \subsection{SmartCollections and memory management}
140    Like the standard collection, SmartCollection can handle the memory management
141    for actions. This works exactly as for cuts. Cuts and actions have to be
142    managed uniformly, ie., one cannot turn off ownership only for cuts or only for
143    actions.
144    
145  \section{The software organization}  \section{The software organization}
146  The software is organized in a tree of directories. The idea is that each node  The software is organized in a tree of directories. The idea is that each node
# Line 502  should be straightforward. However, look Line 553  should be straightforward. However, look
553  implementations of actions if you need some example to setup your build.  implementations of actions if you need some example to setup your build.
554    
555  \section{How to build and use the library}  \section{How to build and use the library}
556    \subsection{Standard Pamela environment}
557  If the makefiles are correctly set up, the only remaining thing is to type  If the makefiles are correctly set up, the only remaining thing is to type
558  \verb1make all1. Remember to set the PAMELA environment with the set\_pam\_env  \verb1make all1. Remember to set the PAMELA environment with the set\_pam\_env
559  script BEFORE invoking \verb1make1. This will generate a {\it libPamCut.so} file  script BEFORE invoking \verb1make1. This will generate a {\it libPamCut.so} file
560  which will contain all the cuts. To clean the project and build from scratch  which will contain all the cuts. To clean the project and build from scratch
561  type \verb1make clean all1. To use the library in an analysis code the  type \verb1make clean all1. The software can then be installed in the usual
562    Pamela environment calling \verb1make install1: this will place  all the
563    headers in the folder \verb1$PAM_INC/PamCut1 and the {\it libPamCut.so} file in
564    \verb1$PAM_LIB1. To eliminate the installed files call \verb1make distclean1;
565    note that this will NOT do the work of \verb1make clean1, eg., clean the
566    project, but simply remove the files copied in the Pamela directories. Remember
567    to type \verb1make install1 each time you modify and recompile the software, to
568    upgrade the installed version to the new one.
569    
570    To use the library in an analysis code the
571  environment header must be included in the code:  environment header must be included in the code:
572  \verb1#include "<root PamCutdirectory>/PamCutEnv.h"1. With this, all the  \verb1#include "<root PamCutdirectory>/PamCutEnv.h"1. With this, all the
573  classes and common definitions will be accessible. A typical usage of {\bf  classes and common definitions will be accessible. A typical usage of {\bf
574  PamCut} inside the analysis code would look like:  PamCut} inside the analysis code would look like:
575    
576  \begin{verbatim}  \begin{verbatim}
577          
578    PamCutCollection collection;    #include <PamCut/PamCutEnv.h>
579      
580      int main(){
581        .
582        .
583        .
584      
585      PamCutCollection collection("Collection");
586    
587    DummyCut1 dummy1;    DummyCut1 dummy1;
588    collection.AddCut(dummy1);    collection.AddCut(dummy1);
# Line 523  PamCut} inside the analysis code would l Line 591  PamCut} inside the analysis code would l
591    
592    collection.Process(event, 0, event->GetEntries()-1);    collection.Process(event, 0, event->GetEntries()-1);
593            
594         .
595         .
596         .
597      }  
598        
599  \end{verbatim}  \end{verbatim}
600    
601  In the simple example above a \verb1DummyCut11 and a \verb1DummyCut21 object  In the simple example above a \verb1DummyCut11 and a \verb1DummyCut21 object
602  (which requires some sort of parameter) are instantiated. They are added to  (which requires some sort of parameter) are instantiated. They are added to
603  \verb1collection1 which takes care of applying them to all the events.  \verb1collection1 which takes care of applying them to all the events.
604    
605  When the analysis code is compiled the linker must be aware that it  \subsection{Custom environment}
606  needs a library called {\it libPamCut.so} and where to find it. In the {\it  If you don't have access to the Pamela software directories (eg., you don't
607  makefile} which builds the analysis program the following option must be added  have write permission on them) you cannot install the software; but you can
608  to the linker invocation:  still use PamCut directly from the source folder.
609    
610    First of all, you have to tell the compiler where to find the {\bf PamCut}'s
611    headers. They are in the main {\bf PamCut} directory, so you may add this
612    option:
613  \newline  \newline
614  \verb1-L<root PamCut directory> -lPamCut1.  \verb1       -I<directory>1
615    \newline
616  One could also wish to move {\it libPamCut.so} to another directory: this path  to the compiler invocation in the {\it makefile} of your main analysis program.
617  must then replace what is indicated as \verb1<root PamCut directory>1 above.  This tells the compiler to search for headers in the folder specified after
618    \verb1-I1. So, if {\it <directory>} is the folder which contains the {\bf
619    PamCut}'s main folder, you don't have to change anything in your main analysis
620    file (with respect to what described in the previous subsection), since:
621    \newline
622    \verb1       #include <PamCut/PamCutEnv.h>1
623    \newline
624    includes the file {\it PamCutEnv.h} which is in the folder {\it PamCut} in the
625    standard inclusion directories, one of which is the one specified with the
626    \verb1-I1 compiler directive. Obviously, one can play with directories, having
627    care to indicate the right paths to the compiler
628    
629  Finally, when the analysis code is compiled and linked against libPamCut.so, to  The following option must be added to the linker invocation:
630    \newline
631    \verb1       -L<root PamCut directory> -lPamCut1.
632    \newline
633    to tell the linker where the dynamic library is.
634    
635    Then, when the analysis code is compiled and linked against libPamCut.so, to
636  launch it it's necessary to tell the environment where the library is, so that  launch it it's necessary to tell the environment where the library is, so that
637  the program can dynamically access it at runtime. This information is encoded  the program can dynamically access it at runtime. This information is encoded
638  in the environment variable LD\_LIBRARY\_PATH, which contains the paths of the  in the environment variable LD\_LIBRARY\_PATH, which contains the paths of the
Legend:
Removed from v.1.1.1.1  
changed lines
  Added in v.1.5
  ViewVC Help
Powered by ViewVC 1.1.23