PamCut/doc/PamCutDevGuide.tex

\documentclass{article}

\title{PamCut Developer's Guide}
\author{Nicola Mori}

\begin{document}
\maketitle
\tableofcontents
\section{The philosophy}

{\bf PamCut} is an abstract class, defining the interface for a cut object used
in the analysis of PAMELA data. The main idea beyond the development is that a
cut object must be capable of saying if an event is good or not, ie., if it
satisfies some selection criteria. This criteria have to be implemented from
scratch every time a specific cut is needed, by defining a concrete class which
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. 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.

\subsection{More on collections}
A collection is an object which inherits from {\bf PamCutCollection}, which in
turn inherits from {\bf PamCut}. So a collection is a cut itself, meaning that
its interface contains a {\bf Check} method, an {\bf ApplyCut} method and so
on. Logically, this is in agreement with the fact that a bunch of cuts can be
thought of as a single cut whose result is the logical AND of all the basic
cuts. More specifically, the implementation chosen for {\bf PamCutCollection}
methods consists in simply performing a cyclic call of the corresponding
methods in basic cuts. So {\bf PamCutCollection::Check} will subsequently call
all the {\bf Check} methods of the basic cuts it contains, and {\bf
PamCutCollection::ApplyCut} will call the basic {\bf ApplyCut}s. This last
feature deserves some more words. When the collection calls a basic {\bf
ApplyCut}, the basic cut will also perform its specific post-selection tasks as
defined in its implementations of {\bf OnGood} and {\bf OnBad}. If all the
basic cuts result to be satisfied, then {\bf PamCutCollection::ApplyCut} will
call {\bf PamCutCollection::OnGood}, allowing for the execution of a
post-processing task which occurs only if all the basic selection criteria are
satisfied. Indeed, as said above a collection is a cut, so it behaves exactly
like a cut: when you apply it, you will also do the apprpriate post-processing.
We have then two levels of post-processing: the first is triggered by success
of a basic cut, the second by the success of the whole sequence of basic cuts.
This modular behaviour achieved with collections allow for a definition of a
hierarchy of cuts: a collection can contain other collections, which in turn
can contain other collections or basic cuts, in a tree-like hierarchy. Each
level has its own post-selection tasks, allowing for a fine control of the
post-processing procedure.

To perform some tests it could be useful to have a collection which applies
the whole bunch cuts to all the events, regardless if some cuts are not
satisfied for a specific event ({\bf PamCutCollection} stop the evaluation for
the current event as soon as a cut is not satisfied). This is achieved with the
{\bf BlindCutCollection} class, which blindly checks all the cuts for all the
events. This will lead to a call to {\bf OnGood} or {\bf OnBad} for all the
cuts for each event; the collection will the call its own {\bf OnGood} or {\bf
OnBad} if all the cuts have been satisfied or not, much like in 
{\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
report. To automate these tasks, the class {\bf CollectionAction} has been
designed. A {\bf CollectionAction} object has a {\bf Setup} method which
may contain the initialization procedures, like reading parameters from a file.
Also the constructor can contain some initializations. The finalization, like
writing histograms on a file, is in the {\bf Finalize} method. The specific
actions for good and bad events are to be defined in the {\bf OnGood} and {\bf
OnBad} methods, much like in collections. {\bf CollecionAction} is an abstract
class, which does nothing but defining the interface. Its concrete
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 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}. 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.

\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
of this tree must provide the necessary informations about the sub-branches. In
each directory, a header file will contain \verb1#include1 directives for all
header files in the sub-directories. This way, it is sufficient to include the
top-level header in the analysis software to automatically include all the
headers of the project. This top-level header is {\it PamCutEnv.h}. Each time a
sub-directory is created, the headers it contains must be included in the
parent node's header.

\subsection{The makefile organization}
The instructions to build the software library are encoded in the standard {\bf
make} way, following the same tree structure of the software. Each node
directory contains an {\it include.mk} file, which includes all the
{include.mk} in the sub-directories. This chain of inclusions terminates on the
leaves, which most of the times contain the definition and implementation of
the classes. Each leaf directory must provide build instructions for the files
it contains, in a file called {\it subdir.mk}; this file has to be included in
the upper {\it include.mk}. The top level {\it include.mk} is included by
the {\it makefile}.\\
This way, each directory takes care of its sub-directories, letting a quick and
easy addition of the latters.

\section{The software architecture}
The software is organized in a tree of directories. The root folder contains a
{\it PamCutBase} folder, in which the definitions of the base classes ({\bf
PamCut} and {\bf PamCutCollection}) are stored, and the general headers {\it
PamCutEnv.h} and {\it CommonDefs.h}. {\it PamCutEnv.h} contains the inclusion
of all the headers of the framework, allowing for the use of the entire
software with only one \verb1#include1 in the code; {\it CommonDefs.h} contains
all the definitions which are relevant for the entire framework.
To develop a specific cut one has to define a derived class from {\bf PamCut},
which at least must provide a concrete implementation of {\bf Check}. One can
also define new versions of {\bf OnGood} and {\bf OnBad} for specific
post-selection tasks (in the base class these methods do nothing). Be very
careful if you decide to redefine {\bf ApplyCut}: remeber that the interface
requires them to call the post-selection routines.
A good rule for keeping the software distribution clean is to use a different
folder for each cut definition, named as the cut itself. When you define a new
cut, create a folder named as the cut inside an adequate parent directory and
place the {\it .h} and {\it .cpp} files inside it. To speed up development, you may copy
and paste an existing cut and then modify it.\\
In the same way, actions can be defined.

\section{How to define a cut}
As said above, to define a cut (let's name it {\bf DummyCut}) it is suggested
to create a folder {\it DummyCut} inside, eg., a {\bf DummyDir} directory
inside the root folder, and to create inside it two files: {\it DummyCut.h},
which will contain all the declarations, and {\it DummyCut.cpp}, where the
implementation will be coded. A typical structure for {\it DummyCut.h} would be:

\begin{verbatim}
#ifndef DUMMYCUT_H_
#define DUMMYCUT_H_

/*! @file DummyCut.h The DummyCut class declaration file */

#include "../../PamCutBase/PamCutBase.h"

/*! @brief An example cut. */
class DummyCut: public PamCut {
public:

  /*! @brief Constructor. */
  Dummy(char *cutName):
    PamCut(cutName) {
  }

  /*! @brief Destructor. */
  ~DummyCut() {
  }

  /*! @brief The dummy cut check
   *
   * This routine checks the event using the dummy cut criteria.
   *
   * @param event The event to analyze.
   * @return CUTOK if the dummy cut is satisfied
   */
  int Check(PamLevel2 *event);

};

#endif /* DUMMYCUT_H_ */

\end{verbatim}

Note the inclusion of {\it PamCutBase.h}: this is essential to let {\bf
DummyClass} know about its parent class, which in this case is {\bf PamCut}.
Another thing to care about is the multiple inclusion protection, ie., the
preprocessor directives:
\begin{verbatim}
#ifndef DUMMYCUT_H_
#define DUMMYCUT_H_
   .
   .
   .
#endif /* DUMMYCUT_H_ */
\end{verbatim}
This provide protection against multiple inclusion of a header in a single
compilation unit due to circular inclusion; in practice, it will save the
developer a lot of double definition errors from the compiler. Be sure that all
your headers are encapsulated in such a structure, and that for each header
there is a different name after \verb1#ifndef1 (which must match the successive
\verb1#define1); otherwise, the compiler could skip the inclusion of some
headers. The convention adopted in {\bf PamCut} for such tags is: 
\verb1<Filename in uppercase>_H_1, which provides univocal tags for each header.

The essential redeclarations are: the constructor, the desctructor and {\bf
Check}. Constructor deserves some observations: since constructors are not
inherited, each class must have its own. However, if a class has a parent
class, it is necessary to initialize also the parent class. If the parent class
has a default constructor (ie., a constructor without arguments) the compiler
will automatically call it and the user has nothing to worry about. However,
{\bf PamCut} has no default constructor, so in every derived class there must
be an explicit call to the {\bf PamCut} constructor. This is what is done in
the lines:

\begin{verbatim}
  Dummy(char *cutName):
    PamCut(cutName) {
  }
\end{verbatim}
{\bf PamCut} objects have a name, internally stored in the {\bf \_cutName}; so
our {\bf DummyClass}, since it inherits from {\bf PamCut}, must also have a
name. Its constructor, indeed, requires a string containing the cut's name. But
in {\bf DummyCut} there's no local variable to store it, and there's no need to
define one since it is already present in {\bf PamCut}. The only thing to do is
to initialize it exactly as {\bf PamCut} would do: this is the purpose of
invoking \verb1PamCut(cutName)1. As an aside, what follows the colon after the
{\bf DummyCut} constructor declaration is called \emph{initialization list}:
here one can (and must) call the constructors for all the objects and variables
contained in the class. These are executed before the class constructor's body,
so that one can safely assume that at construction time all the internal
objects and variables are properly initialized.

To recap and generalize, when you write a derived class you must always call
the constructor of its parent class, which will take care about initializing
the ``parent core'' of the derived class.

One can also redefine {\bf OnGood}, {\bf OnBad}, add new methods, variables and
so on. If you plan to build a general purpose cut who could be used by
different people please take the time to add the appropriate documentation to
the code. In the example, Doxygen comment lines (beginning with \verb1/*!1)
are shown; an on-line guide for Doxygen can be found at:
\newline
\newline
\verb1            http://www.stack.nl/~dimitri/doxygen/manual.html1   

\vspace{.5cm}
Once the header has been prepared, it's time to implement the cut in {\it
DummyCut.cpp}:

\begin{verbatim}
/*! @file DummyCut.cpp The DummyCut class implementation file */

#include "DummyCut.h"

int DummyCut::Check(PamLevel2 * event) {

  if (<Some condition about the event>)
    return CUTOK;
  else
    return 0;
}
\end{verbatim}

In this very simple implementation a basic feature is noticeable: the interface
requires that whenever an event satisfy the selection criterion, {\bf Check}
must return the {\bf CUTOK} value. This value is defined in {\it CommonDefs.h}.
The return value for a discarded event is implementation-specific, and can be
anything but {\bf CUTOK}. This return value could take different values
depending on the reason why the event has been discarded: for example, it can
be a number associated to a specific detector whose data is missing in a data
quality cut. It is then passed to {\bf OnBad}, which can perform some task
depending on the specific reason of the cut failure (eg., on which detector has
no data).
Remember also to include the header file.

\section{How to setup the cut's build} \label{sec:build}
Once a cut has been declared and implemented, the makefiles have to be adjusted
to include it in the cut library. The {\it makefile} provided with the software
will build a library called {\it libPamCut.so}, which can be then linked to a
specific analysis code. It is based on a submakefile structure. Each folder
containing a cut must also include one of these submakefiles (named {\it
subdir.mk} by convention), who instructs the main {\it makefile} on how to build
the newly added cut. An example is:

\begin{verbatim}
# Choose a name for the object file. This must coincide with the
# .cpp and .h filename, except for the extension which has to 
# be .o
OBJS += ./DummyDir/DummyCut/DummyCut.o 

# Dependencies file. The extension must be .d, and the name equal 
# to the cut name.
CPP_DEPS += ./DummyDir/DummyCut/DummyCut.d 

# Rules for compilation. You will likely have only to specify
# the path. Put the directory path:
#            here                     here
./DummyDir/DummyCut/%.o: ./DummyDir/DummyCut/%.cpp
        @echo 'Building file: $<'
        @echo 'Invoking: GCC C++ Compiler'
        $(C++) -I${ROOTSYS}/include -I${PAM_INC} -I${PAM_INC}/yoda \
           -Wall -c -MMD -MP -MF"$(@:%.o=%.d)" -MT"$(@:%.o=%.d)"\
           -o"$@" "$<"
        @echo 'Finished building: $<'
        @echo ' '

\end{verbatim}

Existing files can be used as a template. The first thing you have to modify
is the object name (\verb1OBJS1 variable): be careful to append the object name
to \verb1OBJS1 using \verb1+=1 instead of overwriting it with \verb1=1. The
paths in this file will be relative to the root directory where the {\it
makefile} is, eg., \verb1./1 is not the {\it DummyCut} directory where {\it
subdir.mk} is, but the root directory which contains the {\it makefile}. The
object file ({\it DummyCut.o}) must be named as the cut and the directory that
contains the cut. The \verb1CPP_DEPS1 variable must be similarly modified.
This variable contains a list of dependency files, which contains all the
external headers (eg., PAMELA and ROOT headers) {\bf PamCut} depends on. These
lists are automatically generated, and allows {\it make} to rebuild {\bf
PamCut} whenever one of these headers are modified. Finally, one has also to
put the directory name in the target line which precedes the build command,
just below \verb1here1.

After creating the {\it subdir.mk}, it must be included in the {\it include.mk}
in the parent directory. It looks like this:

\begin{verbatim}
# Include here the submakefiles for each cut

# Cuts
-include DummyDir/DummyCut/subdir.mk
 .
 .
 .
\end{verbatim}

 
Remember to write paths as relative to the root directory. Going backward along
the chain of inclusions leads to the {\it makefile}:
 
\begin{verbatim}
# ------------------------ Build options ----------------------#

# C++ compiler and linker
C++ = g++

# Optimization flags.
OPTIMIZE = -g3 #-DDEBUGPAMCUT

# Library flags
EXCLUSIONFLAGS = #-DNO_TOFNUCLEI -DNO_CALONUCLEI -DNO_TRKNUCLEI

COMMONDEPS = makefile

-include include.mk

#------------------------ Make body ---------------------------#
#
# Below the make commands are defined. There are no options to 
# set in this section, so it has to be modified only in case of 
# radical changes to the make procedure.

# Remove command for clean
RM := rm -rf

# Additional dependencies from headers of other software 
# (PAMELA, ROOT)
ifneq ($(MAKECMDGOALS),clean)
ifneq ($(strip $(CPP_DEPS)),)
-include $(CPP_DEPS)
endif
endif

# All Target
all: version libPamCut.so

# Tool invocations
libPamCut.so: $(OBJS) $(USER_OBJS)
        @echo 'Building target: $@'
        @echo 'Invoking: GCC C++ Linker'
        $(C++) -shared -o"libPamCut.so" $(OBJS)
        @echo 'Finished building target: $@'
        @echo ' '

# Other Targets
clean:
        -$(RM) $(CPP_DEPS) $(OBJS) libPamCut.so
        -@echo ' '

version:
        @gcc --version | grep gcc; echo

.PHONY: all clean dependents version
\end{verbatim}

The Build options section is the one that will most likely need a modification
if one wants to tweak the compilation; the make body will most of the times be
good as it is. The {\it makefile} contains comments to explain how to set the
various options.\\
The first option to set is the compiler: g++ will work on
almost all Linux systems. Next is the optimization level, which could be set to
one of the proposed values according to the specific necessities. The {\it
makefile} comments contains also instructions on how to enable debug sections
in the code.\\
Since the PAMELA software is modular, in some setups it may lack some libraries
needed by some cuts. When designing such a cut it is a good habit to setup
its eventual exclusion from the library. This can be efficiently done using
the compiler directive \verb1#ifdef1. For example, encapsulating all the code
in the header and implementation files of {\bf DummyCut} in a structure like
this:

\begin{verbatim}
#ifdef NO_DUMMYCUT
 .
 .
 .
#endif
\end{verbatim} 

\noindent will completely exclude {\bf DummyCut} from the environment if the
flag \verb1NO_DUMMYCUT1 is defined. It can be done passing the parameter
\verb1-DNO_DUMMYCUT1 to the compiler. These exclusion flags can be  defined in
the \verb1EXCLUSIONFLAGS1 variable. A concrete example is given by
{\bf TofNucleiZCut}, which requires the {\bf ToFNuclei} library: look at it to
see how its exclusion from the code is implemented, allowing to build and use
{\bf PamCut} in those environments that do not include {\bf ToFNuclei}. In the
end, this is very similar to what is done with the debug sections.\\
The \verb1COMMONDEPS1 flag contains the files which, if modified, will trigger
a complete rebuild of the library. For example, if you change the {\it
makefile} by modifying an optimization option all the modules should be rebuilt
so that the whole library will have the same level of optimization. That's why
{\it makefile} is in \verb1COMMONDEPS1. Add all the other files that should
behave like this.\\

If you need some extra modifications to the building system you need to know
more about {\it make}; an online guide is at:
\newline
\verb1http://www.linuxtopia.org/online_books/programming_tool_guides/1
\newline
\verb1          gnu_make_user_guide/make.html#SEC_Top1


\section{How to define an action}
Defining an action is very similar to defining a cut. An example header:

\begin{verbatim}
#ifndef DUMMYACTION_H_
#define DUMMYACTION_H_

#include "../CollectionAction/CollectionAction.h"

/*! @brief A dummy action definition. */
class DummyAction: public CollectionAction {

public:
  /*! @brief Constructor.
   *
   * @param actionName The action's name.
   */
  DummyAction(const char *actionName): 
        CollectionAction(actionName){}

  /*! @brief Destructor */
  ~DummyAction() {
  }

  /*! @brief The setup procedure.
   *
   * @param events The events pointer.
   */
  void Setup(PamLevel2 *events);

  /*! @brief The OnGood procedure. 
   *
   * @param event The selected event.
   */
  void OnGood(PamLevel2 *event);

  /*! @brief Writes the tree of saved events to the output file.  */
  void Finalize();
};

#endif /* DUMMYACTION_H_ */

\end{verbatim}

The {\bf DummyAction} declaration above is a good example. The action classes
must inherit from {\bf CollectionAction}, and their constructor have to call
the constructor of the ancestor class in the initialization list, similarly to
what happens for cuts. Then some of the base class' methods are overridden,
specifically {\bf Setup}, {\bf OnGood} and {\bf Finalize}. The last two methods
have to be overridden, since they are pure virtual (an action is supposed to do
something for good events and something to end the analysis, so making these 
methods pure virtual is a way to enforce a definition in the derived classes).
Conversely, {\bf Setup} and {\bf OnBad} are concrete in the base class, with
void implementation: since not all actions would need a setup (it can be done
also in the constructor) or a procedure for bad events, this implementation
allows to not define them in derived classes. Obviously, the re-declared
methods in the header have to have a re-definition in a .cpp file, exactly as
for the cuts.

\section{How to setup the actions's build}
This topic is very similar to that explained in sec. \ref{sec:build}, so it
should be straightforward. However, look at the provided concrete
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. 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 "<root PamCutdirectory>/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}
  
  #include <PamCut/PamCutEnv.h>
  
  int main(){
    .
    .
    .
  
  PamCutCollection collection("Collection");

  DummyCut1 *dummy1 = new DummyCut1("name1");
  collection.AddCut(dummy1);
  // The two lines above can be summarized also as:
  // collection.AddCut(new DummyCut1("name1"));
  
  DummyCut2 *dummy2 = new DummyCut2("name2", <eventual params>);
  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.

\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       -I<directory>1
\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 <directory>} 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 <PamCut/PamCutEnv.h>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

The following option must be added to the linker invocation:
\newline
\verb1       -L<root PamCut directory> -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
accessible libraries. If libPamCut.so is still in the root PamCut directory one
can type:
\newline
\verb1export LD_LIBRARY_PATH=<root PamCut directory>:$LD_LIBRARY_PATH1
\newline
This has to be done every time you open a shell; one way to avoid this is to
append the above line at the end of your set\_pam\_env script, so that it will
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.
\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 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
  class (one can also cut and paste the files from an existing class and edit
  them), defining at least the constructor, the distructor and {\bf Check} for
  the new class.
  \item Create inside the directory a {\it subdir.mk} file which contains the
  instructions to build the directory content, as described in \ref{sec:build};
  as usual, one can cut and paste from an existing class and then edit.
  \item Modify the {\it makefile} in the root code directory as in
  \ref{sec:build}, to include the newly developed cut.
  \item Modify the {\it PamCutEnv.h} file, adding the \verb1#include#1 for the
  new class header (see examples therein).
  \item Set the PAMELA environment with the set\_pam\_env script.
  \item Build the library typing \verb1make all1 (or \verb1make clean all1 to
  build from scratch); this will produce the library {\it libPamCut.so} in the
  root code directory, which will contain all the class definitions and
  implementations.
  \item Insert \verb1#include ``<root PamCut directory>/PamCutEnv.h#1 in the
  analysis code, to have access to all the classes in the library.
  \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
  cut, instead of modifying an existing one. As an example, you can define a
  cut with a specific implementation for {\bf Check}, then derive from it many
  classes which only redefine {\bf OnGood} and {\bf OnBad}. In this way, you
  can have several post-selection options associated to the same cut; if
  you'll ever need to modify the cut criteria, you will have to do it only in
  one place, saving time and reducing code errors opportunities.
  \item Be consistent with the existing code style. Everyone has its own
  code style, with its own conventions for naming variables and functions based
  on personal preferences. Maintaining a uniform code style is a good way to
  improve the code readability, so it's worth a little effort. The conventions
  chosen for {\bf PamCut} are:
  \begin{itemize}
        \item the names of private and protected members (variables and methods)
        always begin with an underscore, eg., \verb1_previousOBT1, \verb1_LT1;
        \item the names of variables usually begin with a lower case; for compound
        words, the successive initials are upper case, eg., \verb1time1,
        \verb1liveTime1, \verb1nHitPaddles1;
        \item the names of classes and methods begin with upper case, eg.,
        \verb1PamCut1, \verb1GeoFieldCut1, \verb1ApplyCut()1. 
  \end{itemize}
  Within these conventions, a code row like:
  \newline
  \verb1   GeoFieldCut geoFieldCut;1
  \newline
  is easily interpreted as the instantiation of a class named 
  \verb1GeoFieldCut1 into an object named \verb1geoFieldCut1. This allows to
  have objects whose names are almost identical to those of the respective
  classes, allowing a straightforward type recognition. Also, the discrimination between
  public and private variables and methods inside a class is immediate. 
  \item Respect the interface. {\bf PamCut} has been designed following precise
  rules, which allow for a quite general environment that should cover many
  of the necessities related to data analysis. Try to fit your
  particular analysis in this scheme; this will result in a much more
  raedable code. However, someone may need features that are not compatible with
  the current interface. In this case, the first thing to do is to try a
  workaround that would leave the interface unchanged. As an example, if the
  automated post-selection tasks based on {\bf OnGood} and {\bf OnBad} does not
  satisfy you, you can call directly the {\bf Check} method inside a loop and
  then do a custom post-processing. In the worst case, the interface could
  result incompatible with the analysis needs: in this case a redesign
  hypotheses can be considered if the incompatibility is such that a large
  piece of the analysis would be compromised. Redesigning is always a tricky
  task, so it has to be considered as a last option.
  \item Take care about other people. If you plan to write a code that is
  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 the
  questions other people will ask you.
\end{itemize}


\end{document}