source: JEM-EUSO/esaf_lal/tags/v1_r0/esafdoc/UserGuide/RecoCode.tex @ 117

% ESAF User Guide
% $Id: RecoCode.tex 1034 2004-09-17 17:04:57Z thea $
% M.Pallavicini, A. Thea - created

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% reco code
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{The Reconstruction code}
%\addcontentsline{toc}{section}{The Reconstruction code}

\subsection{Overview}
%\addcontentsline{toc}{subsection}{Overview}
\label{sec:over}

In this section we describe the structure of the Reco code. The logic here
is slightly different from the previous section, because even normal user must
have a good understanding of the Reconstruction framework in order to use
it efficiently. Therefore, some more insight of the internal structure of
the framework is given, even if Rule number 0 of the software developer should
always be remembered: the only document that is always up to date is the code!

The proposed scheme for the organization of the \esaf{} reconstruction module 
is sketched in figure~\ref{fig:recoscheme}. Input data comes either from 
the simulation module (Root file) or from the real data stream (pre-processed 
telemetry)\footnote{Right now, only data input from simulation \ROOT file
is available}. 

From this figure, the following basic entities/structures can be 
identified:

\begin{itemize}

\item
Input module

This modules handles the reading of the events for reconstruction. Foreseen 
are the reading of a Root simulation file (already supported) and the 
reading of events from the real data stream (pre-processed telemetry). 

\item
Event container

This is the container structure for the input event which we are going to 
reconstruct.
The event container will allow the access the objects holding: event header 
information, trigger information and readout information at macrocell and 
pixel level. In principle the available information should correspond 
exactly to the one available in real data, although test modes in which 
the ``Monte Carlo truth'' is available are also foreseen.

\item
Reconstruction framework

This is the main structure, which actually builds the chain of modules which 
will reconstruct the event. Event reconstruction is divided into different 
tasks (e.g. direction reconstruction, energy reconstruction, ...) and for 
each task different possible modules may be available.
The use of a structure allows to easily replace or exclude a given processing 
module.
In this way different algorithms or algorithm combinations can be compared 
and tests can be performed.

\item
Modules 

This is the set of processing modules, possibly several alternative modules
for each specific task, that can actually be picked by the user and included in 
the reconstruction chain build by the framework.

\item
Configuration files

Configuration data includes the name and location of the input file and 
the definition of the processing modules to load.

The configuration definition in \Reco{} is rather simple for the user point of 
view but corresponds to a relatively complex implementation (see below). It allows to change
the base directory for all configuration files, thus allowing to define and use
different full configurations stored in different places.

The reconstruction uses the files stored in \code{config/Reco} directory.

\item
Access to databases

Access to databases will be a major issue in \Reco{}. The reconstruction 
procedure will naturally require the access to a run conditions database, as 
well as to the detector calibration database. Furthermore, access to 
atmospheric data (both collected by the EUSO atmospheric sounding devices or 
originating from external sources and databases) will have to be accessed. 

This part of the code is, at this early stage, not yet implemented. 
See below (future developments) for more information.

\end{itemize}

This structure is shown in the interactions diagram in figure~\ref{fig:objdiag}.

\subsection{Class structure}
%\addcontentsline{toc}{subsection}{Class structure}

The basic class diagram of \Reco{} as its present stage is schematically 
shown in figure~\ref{fig:classdiag}.

The different basic ``groups'' in the above classification 
are shown in different colours. The scheme is described in the sections 
below, where some design and implementation aspects are presented.

\subsubsection{Input}
%\addcontentsline{toc}{subsubsection}{Input}

There is an abstract interface \code{InputModule} from which are built
the different concrete input classes. The existing concrete classes are 
\code{RootInputModule} (for simulation file reading) and \code{TestInputModule}
(for test purposes only, not to be used by normal users).

\subsubsection{Event}
%\addcontentsline{toc}{subsubsection}{Event}

The main class is the event container, \code{RecoEvent}. The event header is 
stored separately in a RecoEventHeader class. For each \code{RecoEvent} a \code{RecoEventHeader}
is required. Event information is kept in the objects \code{RecoCellHit}, with macrocell 
level information (this is the class defining a hit),
\code{RecoPixelData}, a generalisation of the previous one containing
pixel level information. Furthermore, \code{RecoCellInfo} contains trigger and 
macrocell level information and \code{RecoAnalogData} holds analog readout 
information and \code{RecoPhotoElectronData} contains informations about the photoelectrons for test and debugging.

\subsubsection{Framework}
%\addcontentsline{toc}{subsubsection}{Framework}

The \emph{framework} is responsible for creating a \emph{factory} which will 
generate \emph{modules} according to pre-defined models. Different module types 
can be selected/unselected. One and only one input module should exist.

The central class is the \code{RecoFramework} class, which will create a \emph{factory},
\code{ModuleFactory}, able to generate modules according to a given model.
\code{RecoModule} is the abstract interface from which are built the different concrete
classes defining the different types of modules. \code{TestRecoModule} is an example
concrete implementation. \code{RecoSequence} is meant to define a special type of
composite module.


\subsubsection{Modules}
%\addcontentsline{toc}{subsubsection}{Modules}

A set of modules will be available for the different reconstruction tasks.
As an example, a basic clustering algorithm is implemented in the class
\code{BaseClusteringModule}, which, just like \code{TestRecoModule}, inherits from 
the abstract interface \code{RecoModule}. This section of the code is currently 
being implemented, the diagram corresponds to the status on January 23$^{rd}$.


\subsubsection{Configuration and utilities}
%\addcontentsline{toc}{subsubsection}{Configuration and utilities}

In this category are included different software tools of interest for both 
the simulation and the reconstruction parts of \esaf{}. This includes code 
for the following purposes:
configuration handling, object persistency (\ROOT{}), graphic user interface, 
basic data and mathematical procedures (units, constants, random number
handling, time/orbit info, ISS time/orbit description...), atmosphere description.
As seen in the diagram, 
at present configuration handling is already implemented and can serve here as an 
example:
\code{EusoConfigurable} is the abstract interface that should be used by all classes
that need to access configuration data, in order to create \code{Config}, a singleton object
in which the relevant information is stored.
All the classes that need to access configuration data should inherit from 
\code{EusoConfigurable} 
(and call in their definition the macro \code{EusoConfigurable(type,name)}.  
The method \code{Conf()} returns a pointer to
a \code{ConfigFileParser} object that contains all the parameter values 
(identifies the file containing the configuration parameters 
for the object considered, parses the file, and stores the parname=parvalue
pairs in maps).  
The \code{ConfigFileParser} objects are created by a factory, \code{Config}, This object is a
singleton.


\subsection{Time sequence}
%\addcontentsline{toc}{subsection}{Time sequence}

This section presents a rough and simple-minded temporal sequence view of the control flow
and object interaction during and \Reco{} test run. 
The purpose is to clarify the ideas and provide the reader with a simple picture
of how it works. A schematic representation is given in figure~\ref{fig:seqdiag}.
In the description below, the pure object lifecycle view is here mixed with a more code-oriented 
description of the program flow (usually given in parentheses).

\begin{itemize}

\item
Building the Framework:

\begin{enumerate}

\item
A \code{RecoFramework} object is created (\code{RecoFramework} constructor called in \code{reco-main.cc}):

\begin{displaycode}
RecoFramework theFrameWork;
\end{displaycode}
\item get name of the file with module list and read module list (within \code{RecoFramework} constructor);
\begin{displaycode} 
string sName = Conf()->getStr("RecoFramework.ModuleFile");
sName = "./config/Reco/"+sName;
\end{displaycode}

\item create factory object \code{ModuleFactory} and build module (within
\code{RecoFramework} constructor, calling \code{ModuleFactory} constructor with
module list as arguments. In there, modules are built using the
\code{MakeModule()}, \code{MakeInputModule()} methods of the
\code{ModuleFactory}).
\begin{displaycode} 
// build factory 
ModuleFactory factory( sName );

// build modules
if ( identifier == "InputModule" ) {
    MakeInputModule(name);
}
else if ( identifier == "Module" ) {
    MakeModule( name );
}
else if ( identifier == "Sequence" ) {
    MakeSequence( name );
}
else {
    throw runtime_error("Syntax error in file"
                         +sName+" line "+dummy);
}
\end{displaycode}

\end{enumerate}

\item
Executing the module chain: 

\begin{enumerate}

\item
Call \code{Execute()} method of \code{RecoFramework} (back to main, perform
some information dump and then execute framework);
\begin{displaycode} 
theFrameWork.Dump();
theFrameWork.ParseCommandLine(argc,argv);
try {
    theFrameWork.Execute();
}
catch( exception &e ) {
    cerr << "RECO Error: " << e.what() << endl;
cerr << "Euso Reco Program Exiting" << endl;
exit(1);
}
\end{displaycode}


\item
initialize input module and the other modules (\code{Init()} methods of
\code{TestInputModule} and \code{TestRecoModule} classes);

\begin{displaycode}
// init input module
fInputModule->Init();

// init all modules
for( it = fModules.begin(); it != fModules.end(); it++) {
    if ( ! it->second->Init() ) {
    cerr << "Module " << it->first << " failed\n";
    throw runtime_error("Init failed");
}
\end{displaycode}

\item
get event into a \code{RecoEvent} object (a \code{RecoEvent} object is created
and the \code{GetEvent}() method of \code{TestInputModule} is invoked);

\begin{displaycode}
// run
while ( RecoEvent *anEvent = fInputModule->GetEvent() ) {
\end{displaycode}

\item
process the event through each module (the methods \code{PreProcess()},
\code{Process()} and \code{PostProcess()} of TestRecoModule are invoked);

\begin{displaycode}
for( it = fModules.begin(); it != fModules.end(); it++) {
    if ( ! it->second->PreProcess() )
    break;
if ( ! it->second->Process( anEvent ) )
    break;
if ( ! it->second->PostProcess() )
    break;
}
\end{displaycode}

\item
destroy the event (method \code{DestroyEvent()} of \code{TestInputModule});

\begin{displaycode}
fInputModule->DestroyEvent();
\end{displaycode}

\item
done with all modules (\code{Done()} methods of input and other modules).

\begin{displaycode}
// end all modules
fInputModule->Done();
for( it = fModules.begin(); it != fModules.end(); it++) {
    it->second->Done();
}
\end{displaycode}

\end{enumerate}

Procedures 1 to 5 are obviously repeated for each event, and persistency is
handled before the event is destroyed.

\end{itemize}