--- PamCut/doc/PamCutDevGuide.tex 2009/05/27 13:30:01 1.1.1.1 +++ PamCut/doc/PamCutDevGuide.tex 2009/10/28 14:52:29 1.6 @@ -16,18 +16,19 @@ inherits form {\bf PamCut} and provides an implementation for the pure virtual method {\bf Check}. A special derived class is {\bf PamCutCollection}. This is a sort of a -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 +AddCut} method which will add a cut to the collection. Its {\bf Check} implementation simply invokes all the {\bf Check}s of the single cuts, and it -is successful if all the single cuts are succesful. -{\bf PamCut} also provides the interface for two methods for post-processing: -{\bf OnGood} and {\bf OnBad}. In derived classes these can contain specific -tasks to be performed whenever an event satisfy the {\bf Check} condition or -not. The method {\bf ApplyCut} takes care of invoking {\bf Check} and -subsequently calls {\bf OnGood} or {\bf OnBad} according to the result of {\bf Check}. -Summarizing, {\bf Check}ing an event simply means to ask the object if the -event satisfy the selection criteria; applying a cut means to check and then -perform post-selection tasks. The cut can be applied to a bunch of events by -means of the {\bf Process} method. +is successful if all the single cuts are succesful. {\bf PamCut} also provides +the interface for two methods for post-processing: {\bf OnGood} and {\bf +OnBad}. In derived classes these can contain specific tasks to be performed +whenever an event satisfy the {\bf Check} condition or not. The method {\bf +ApplyCut} takes care of invoking {\bf Check} and subsequently calls {\bf +OnGood} or {\bf OnBad} according to the result of {\bf Check}. Summarizing, +{\bf Check}ing an event simply means to ask the object if the event satisfy +the selection criteria; applying a cut means to check and then perform +post-selection tasks. The cut can be applied to a bunch of events by means of +the {\bf Process} method. \subsection{More on collections} A collection is an object which inherits from {\bf PamCutCollection}, which in @@ -67,6 +68,18 @@ {\bf PamCutCollection}. See the Doxygen html documentation for more info about {\bf BlindCutCollection} and other specific cut implementations. +\subsection{Collections and memory management} + +Regarding to cuts ownership, a collection will by default own its cuts. This +means that when you add a cut to a collection calling {\bf AddCut} with a +pointer to the cut as argument, the collection will store this pointer and +will take charge of deleting it. This is done by the collection's destructor. +This way, a user can simply add a cut to a collection and forget about +deleting it. However, sometimes this feature is not desirable, so it can be +turned off by passing a proper value to the collection's constructor. In this +case, the user is in charge of managing the memory allocated for the cuts. + + \section{Actions and the SmartCollection} When performing an analysis, each time an event is selected as good some actions are likely to be performed, like filling histograms or writing a @@ -81,15 +94,53 @@ implementations will be called actions.\\ Actions are automatically handled by the {\bf SmartCollection} class. It inherits from {PamCutCollection}, and contains a vector of {\bf -CollectionAction} objects. These actions can be added using {\bf +CollectionAction} objects. These actions can be added calling {\bf SmartCollection::AddAction}; for each of them, the collection will take care of calling {\bf Setup} at the beginning of the analysis, {\bf OnGood} and {\bf OnBad} for every event (depending on the selection result), and {\bf Finalize} at the end of the analysis. In all other aspects, it behaves exactly as {\bf -PamCutCollection}.\\ +PamCutCollection}. The handling of the actions depend on their position with +respect to cuts. In the main analysis code, cuts can be added to the +collection; then, an action or more can be added. This sequence of cuts and the +actions added after the cuts will be called a bunch. The last bunch may have no +actions at its end. +\begin{verbatim} + . + . + . +Cut1 cut1(``cut1''); +Cut2 cut2(``cut2''); +Action1 action1(``action1''); + +Cut1 cut3(``cut3''); +Cut2 cut4(``cut4''); +Cut1 cut5(``cut5''); +Cut2 cut6(``cut6''); +Action1 action2(``action2''); +Action1 action3(``action3''); + . + . + . +\end{verbatim} +In the example above, {\bf cut1}, {\bf cut2} and {\bf action1} are the first +bunch, {\bf cut3}, {\bf cut4}, {\bf cut5}, {\bf cut6}, {\bf action2} and {\bf +action3} are the second bunch and so on. If all the cuts in the bunch are +successful, the {\bf SmartCollection} will call {\bf OnGood} for every action +in that bunch, and then the analysis will go on with the next bunch for the same +event. If a certain cut in a bunch fails, then {\bf OnBad} is called for the +actions of the bunch, but successive bunches are ignored; the current event is +discarded and the focus switches on the next one (the {\bf +SmartBlindCollection} behaves a little differently; see the Doxygen +documentation for more details.) +\\ Loosely speaking, after defining an action one simply has to instantiate it, -add it to a {\bf SmartCollection} and launch the analysis (fire and -forget\ldots). +add it to a {\bf SmartCollection} and launch the analysis. + +\subsection{SmartCollections and memory management} +Like the standard collection, SmartCollection can handle the memory management +for actions. This works exactly as for cuts. Cuts and actions have to be +managed uniformly, ie., one cannot turn off ownership only for cuts or only for +actions. \section{The software organization} The software is organized in a tree of directories. The idea is that each node @@ -241,7 +292,7 @@ \verb1 http://www.stack.nl/~dimitri/doxygen/manual.html1 \vspace{.5cm} -Once the header has been prepared, it's time to implement the cut into {\it +Once the header has been prepared, it's time to implement the cut in {\it DummyCut.cpp}: \begin{verbatim} @@ -502,44 +553,89 @@ implementations of actions if you need some example to setup your build. \section{How to build and use the library} +\subsection{Standard Pamela environment} If the makefiles are correctly set up, the only remaining thing is to type \verb1make all1. Remember to set the PAMELA environment with the set\_pam\_env script BEFORE invoking \verb1make1. This will generate a {\it libPamCut.so} file which will contain all the cuts. To clean the project and build from scratch -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 +Pamela environment calling \verb1make install1: this will place all the +headers in the folder \verb1$PAM_INC/PamCut1 and the {\it libPamCut.so} file in +\verb1$PAM_LIB1. To eliminate the installed files call \verb1make distclean1; +note that this will NOT do the work of \verb1make clean1, eg., clean the +project, but simply remove the files copied in the Pamela directories. Remember +to type \verb1make install1 each time you modify and recompile the software, to +upgrade the installed version to the new one. + +To use the library in an analysis code the environment header must be included in the code: \verb1#include "/PamCutEnv.h"1. With this, all the classes and common definitions will be accessible. A typical usage of {\bf PamCut} inside the analysis code would look like: \begin{verbatim} - - PamCutCollection collection; + + #include + + int main(){ + . + . + . + + PamCutCollection collection("Collection"); - DummyCut1 dummy1; + DummyCut1 *dummy1 = new DummyCut1("name1"); collection.AddCut(dummy1); - DummyCut2 dummy2(param); + // The two lines above can be summarized also as: + // collection.AddCut(new DummyCut1("name1")); + + DummyCut2 *dummy2 = new DummyCut2("name2", ); collection.AddCut(dummy2); collection.Process(event, 0, event->GetEntries()-1); + . + . + . + } + \end{verbatim} In the simple example above a \verb1DummyCut11 and a \verb1DummyCut21 object (which requires some sort of parameter) are instantiated. They are added to \verb1collection1 which takes care of applying them to all the events. -When the analysis code is compiled the linker must be aware that it -needs a library called {\it libPamCut.so} and where to find it. In the {\it -makefile} which builds the analysis program the following option must be added -to the linker invocation: +\subsection{Custom environment} +If you don't have access to the Pamela software directories (eg., you don't +have write permission on them) you cannot install the software; but you can +still use PamCut directly from the source folder. + +First of all, you have to tell the compiler where to find the {\bf PamCut}'s +headers. They are in the main {\bf PamCut} directory, so you may add this +option: \newline -\verb1-L -lPamCut1. - -One could also wish to move {\it libPamCut.so} to another directory: this path -must then replace what is indicated as \verb11 above. +\verb1 -I1 +\newline +to the compiler invocation in the {\it makefile} of your main analysis program. +This tells the compiler to search for headers in the folder specified after +\verb1-I1. So, if {\it } is the folder which contains the {\bf +PamCut}'s main folder, you don't have to change anything in your main analysis +file (with respect to what described in the previous subsection), since: +\newline +\verb1 #include 1 +\newline +includes the file {\it PamCutEnv.h} which is in the folder {\it PamCut} in the +standard inclusion directories, one of which is the one specified with the +\verb1-I1 compiler directive. Obviously, one can play with directories, having +care to indicate the right paths to the compiler -Finally, when the analysis code is compiled and linked against libPamCut.so, to +The following option must be added to the linker invocation: +\newline +\verb1 -L -lPamCut1. +\newline +to tell the linker where the dynamic library is. + +Then, when the analysis code is compiled and linked against libPamCut.so, to launch it it's necessary to tell the environment where the library is, so that the program can dynamically access it at runtime. This information is encoded in the environment variable LD\_LIBRARY\_PATH, which contains the paths of the @@ -553,13 +649,13 @@ be automatically executed every time you set your PAMELA environment. \section{Usage summary} -Here's a short summary on how to develop a cut, build and use it. If one only +Here's a short summary on how to develop a cut, build and use it. \begin{enumerate} \item Obtain the code (from tarball, repository\ldots) and go in the root code directory. \item Check if the \verb1C++1 option in the Build section of {\it makefile} is correctly set with the C++ compiler name present in your system (for many - Linux platform, \verb1g++1 is a safe choice). + Linux platforms, \verb1g++1 is a safe choice). \item Create a directory named as the cut class you want to develop. \item Place inside the newly created directory a {\it .h} file and a {\it .cpp} file, named as the direcory; edit the files to define and implement the @@ -583,6 +679,19 @@ \item Develop the analysis code \end{enumerate} +\section{Online documentation} +The code is provided with a full set of Doxygen tags; documentation can then be +built using the doxygen documentation system. However, an online documentation +is availbale at: +\newline +\newline +\verb1 http://hep.fi.infn.it/PAMELA/documents/PamCut_documentation/1 + +\vspace{.5cm} +It is updated frequently, but it may lack the description of the most recent +features. Please notify any fault in the online documentation for a quick fix. + + \section{Some advices and suggestions} \begin{itemize} \item Derive your cuts. Try to define a new class every time you need a new @@ -633,7 +742,7 @@ likely to be used and modified by other people, please take your time to write the documentation. Documenting the code is a boring and time-consuming task, but can save you and your colleagues a lot of headaches and - misunderstandings. The better a code is documented, the lesser are the + misunderstandings. The better a code is documented, the lesser the questions other people will ask you. \end{itemize}