Added descrioptions of the event tag system and alignment framework
[u/mrichter/AliRoot.git] / doc / aliroot-primer / primer.tex
index b1b133f..1fff536 100644 (file)
 \newcommand {\cm} {\mbox{${\rm cm}$}}
 \newcommand {\mm} {\mbox{${\rm mm}$}}
 \newcommand {\dens} {\mbox{${\rm g}\,{\rm cm}^{-3}$}}
-
+%
+\newcommand{\FR}{ALICE alignment framework}
+\newcommand{\tgeo}{\lstinline!TGeo!}
+%
 \lstset{                      % general command to set parameter(s)
 %  basicstyle=\small,          % print whole listing small
   basicstyle=\ttfamily,       % print whole listing monospace
@@ -2991,8 +2994,8 @@ AliESDtrack.
 
 The secondary vertex reconstruction in case of ${\rm V^0}$ is provided by
 \texttt{AliV0vertexer}, and in case of cascade hyperons by
-\texttt{AliCascadeVertexer}.  An universal tool is
-\texttt{AliITSVertexerTracks}, which can be used also to find secondary
+\texttt{AliCascadeVertexer}. 
+\texttt{AliITSVertexerTracks} can be used to find secondary
 vertexes close to the primary one, for example decays of open charm
 like ${\rm D^0 \to K^- \pi^+}$ or ${\rm D^+ \to K^- \pi^+ \pi^+}$. All
 the vertex 
@@ -3264,6 +3267,8 @@ AOD, and then analyzing it.
   % \newpage
 \item\textbf{AOD analysis}
 
+{\bf OBSOLETE}
+
   Often only a small subset of information contained in the ESD
   is needed to perform an analysis. This information
   can be extracted and stored in the AOD format in order to reduce
@@ -3360,6 +3365,8 @@ AOD, and then analyzing it.
 %\cleardoublepage 
 \section{Analysis Foundation Library}
 
+{\bf OBSOLETE}
+
 The result of the reconstruction chain is the Event Summary Data (ESD) 
 object. It contains all the information that may
 be useful in {\it any} analysis. In most cases only a small subset 
@@ -4230,9 +4237,473 @@ The following use cases are illustrated:
   \begin{lstlisting}[language=C++]
     AliCDBManager::Instance()->Destroy()
   \end{lstlisting}
+
+ \item Create a local copy of all the alignment objects
+
+  \begin{lstlisting}[language=C++]
+    AliCDBManager* man = AliCDBManager::Instance();
+    man->SetDefaultStorage(
+      "alien://folder=/alice/simulation/2006/PDC06/Residual/CDB/");
+
+    man->SetDrain("local://$ALICE_ROOT/CDB");
+    AliCDBStorage* sto = man->GetDefaultStorage();
+    sto->GetAll("*",0);
+
+    // All the objects are stored in $ALICE_ROOT/CDB !
+  \end{lstlisting}
+
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\newpage
+\section{The Event Tag System}
+
+The event tag system \cite{EventTag} is designed to provide fast
+preselection of 
+events with the desired characteristics. This task will be performed
+first of all by imposing event selection criteria within the analysis
+code and then by interacting with software that is designed to provide
+a file-transparent event access for analysis. The latter is an
+evolution of the procedure that has already been implemented by the
+STAR \cite{STAR} collaboration. 
+
+In the next sections we will first describe the analysis scheme using
+the event tag system. Then we will continue by presenting in detail
+the existing event tag prototype. Furthermore, a separate section is
+dedicated to the description of the two ways to create the tag files
+and their integration in the whole framework \cite{CompTDR}. 
+
+\subsection{The Analysis Scheme}
+
+ALICE collaboration intends to use a system that will reduce the time
+and computing resources needed to perform an analysis by providing to
+the analysis code just the events of interest as they are defined by
+the users' selection criteria. Fig. \ref{analysis} gives a schematic
+view of the whole analysis architecture.
+
+\begin{figure}[ht!]
+   \centering
+   \includegraphics[width=10cm]{picts/tagana}
+   \caption{The selected analysis scheme using the event tag system. }
+   \label{analysis}
+\end{figure}
+
+Before describing the architecture let us first define a few terms
+that are listed in this figure:
+
+\begin{itemize}
+
+\item User/Administrator: A typical ALICE user or even the
+  administrator of the system who wants to create tag files for all or
+  a few ESDs \cite{CompTDR} of a run.
+
+
+\item Index Builder: A code with Grid Collector \cite{GC1,GC2}
+  functionality that allows the creation of compressed bitmap indices
+  from the attributes listed in the tag files. This functionality will
+  provide an even faster preselection.
+
+
+\item Selector: The user's analysis code that derives from the
+  TSelector class of ROOT \cite{RootSelector}.
+
+
+\end{itemize}
+
+The whole procedure can be summarized as follows:
+
+The offline framework will create the tag files, which will hold
+information about each Event Summary Data (ESD) file (top left box of
+Fig.\ref{analysis}), as a final step of the whole reconstruction
+chain. The creation of the tag files is also foreseen to be performed
+by each user in a post process that will be described in the following
+sections. These tag files, as will be mentioned in this note, are root
+files containing trees of tag objects. Then, following the procedure
+flow as it is shown in Fig. \ref{analysis}, the indexing algorithm of
+the Grid Collector \cite{GC1,GC2}, the \textit{Index Builder}, will
+take the produced tag files and create the compressed bitmap
+indices. In parallel, the user will submit a job with some selection
+criteria relevant to the corresponding analysis he/she is
+performing. These selection criteria will be used in order to query
+the produced compressed indices (or as it is done at the moment the
+query will be on the tags themselves) and the output of the whole
+procedure will be a list of \textit{TEventList} objects grouped by
+\textit{GUID}, which is the file's unique identifier in the file
+catalog, as it is shown in the middle box of Fig.\ref{analysis}. This
+output will be forwarded to the servers that will interact with the
+file catalog in order to retrieve the physical file for each
+\textit{GUID} (left part of Fig. \ref{analysis}). The final result
+will be passed to a selector \cite{RootSelector} that will process the
+list of the events that fulfill the imposed selection criteria and
+merge the output into a single object, whether this is a histogram or
+a tree or any root object. 
+
+The whole implementation implies the existence of an event tag system
+that will allow the user to create the tags for each file. This event
+tag system is active and has been used inside AliRoot's framework
+\cite{aliroot} since June 2005. In the next section we will describe
+this system in detail. 
+
+
+\subsection{The Event Tag System}
+
+The event tag system that has been built, intends to provide a summary
+of the most useful physics information that describe each ESD to the
+user. It consists of four levels of information \cite{EventTagWeb}: 
+
+\begin{itemize}
+
+\item Run Level: Fields that describe the run conditions and
+  configurations and are retrieved from Detector Control System (DCS),
+  Data Acquisition system (DAQ) and offline (Fig. \ref{sources}). 
+
+\item LHC Level: Fields that describe the LHC condition per ALICE run
+  which are retrieved from the DCS (Fig. \ref{sources}). 
+
+\item Detector Level: Fields that describe the detector configuration
+  per ALICE run which are retrieved from the Experimental Control
+  system (ECS) (Fig. \ref{sources}). 
+
+\item Event Level: Fields that describe each event - mainly physics
+  related information and are retrieved by both offline and the grid
+  file catalog (Fig. \ref{sources}). 
+
 \end{itemize}
+
+\begin{figure}[ht!]
+    \centering
+    \includegraphics[width=15cm]{picts/tagsources}
+    \caption{The sources of information for the different levels of the event tag system.}
+    \label{sources}
+\end{figure}
+
+The corresponding classes that form this system have already been
+included in AliRoot's framework under the
+\textbf{STEER} module. The output tag files will be root files having
+a tree structure \cite{EventTagWeb}.
+
+\underline{Run tags:}
+
+The class that deals with the run tag fields is called
+\class{AliRunTag}. One \class{AliRunTag} object is associated to
+each file.
+
+\underline{LHC tags:}
+
+The class that deals with the LHC tag fields is called
+\class{AliLHCTag}. One \class{AliLHCTag} object is associated to
+each file.
+
+\underline{Detector tags:}
+
+The class that deals with the detector tag fields is called
+\class{AliDetectorTag}. The information concerning the detector
+configuration per ALICE run will be described in the ECS database
+(Fig. \ref{sources}). One \class{AliDetectorTag} object is associated
+to each file.
+
+\underline{Event tags:}
+
+The class that handles the event tag fields is called
+\class{AliEventTag}. The values of these fields, as mentioned before,
+will be mainly retrieved from the ESDs although there are some fields
+the values of which will come from the grid file catalog. The number
+of \class{AliEventTag} objects which are associated to each file is
+equal to the number of events that are stored inside the initial ESD
+file.
+
+\subsection{The Creation of the Tag Files}
+
+As it was mentioned in a previous section, the creation of the tag
+files will be the first step of the whole procedure. Two different
+scenarios were decided: 
+
+\begin{itemize}
+
+\item \textbf{On the fly creation}: The creation of the tag file comes
+  as a last step of the reconstruction procedure.  
+
+\item \textbf{Post creation}: After the ESDs have been transfered to
+  the ALICE's file catalog \cite{AliEn}, every user has the
+  possibility to run this post process and create his/her own tag
+  files. 
+
+\end{itemize}
+
+\subsubsection{The on the fly creation scenario}
+
+As mentioned before, the on the fly creation of the tag files is
+implemented in such a way that the tags are filled as a last step of
+the reconstruction chain. This process is treated inside the
+\class{AliReconstruction} class. Thus, exactly after the creation of
+the ESD, the file is passed as an argument to the
+\method{AliReconstruction::CreateTags(TFile *file)} method. Inside
+this method empty \class{AliRunTag} and \class{AliEventTag} objects
+are created. The next step is to loop over the events listed in the
+ESD file and finally fill the run and event level information. The
+naming convention followed for the output tag file is:
+\textbf{Run}\textbf{\textit{RunId}}.\textbf{Event}\textbf{\textit{FirstEventId}}\_\textbf{\textit{LastEventId}}.\textbf{ESD.tag.root}
+\cite{EventTagWeb}. 
+
+\subsubsection{The post creation scenario}
+
+The post creation procedure provides the possibility to every user to
+create and store the tag files at any time \cite{EventTagWeb}. The
+post creation of the tag files implies the following steps: 
+
+\begin{itemize}
+
+\item The reconstruction code finishes and several ESD files are created. 
+
+\item These files are stored then in ALICE's file catalog \cite{AliEn}. 
+
+\item Then the administrator or even every user for the purpose of his
+  private analysis, can loop over the produced ESDs and create the
+  corresponding tag files.
+
+\item These files can either be stored locally or can be stored in the
+  file catalog \cite{AliEn}.
+
+\item As a final step, a user can choose to create a single merged tag
+  file from all the previous ones.
+
+\end{itemize}
+
+What a user has to do in order to create the tag files using this
+procedure depends on the location of the input AliESDs.root
+files. Detailed instructions on how to create tag files for each
+separate case will be given in the following sections. In general a
+user has to perform the following steps:
+
+\begin{itemize}
+
+\item Generate the input that provides information about the location
+  of the AliESDs.root files: this can be the result of a query to the
+  file catalog (\emph{TGridResult} \cite{RootTGridResult} - grid
+  stored ESDS, an upper level local directory - locally stored ESDs or
+  even a text file - CERN Analysis Facility (CAF) stored ESDs
+  \cite{CAF}.
+
+\item Loop over the entries of the given input (\emph{TGridResult},
+  \emph{local path}, \emph{text file}) and create the tag file for
+  each entry.
+
+\item Either store the files locally or in the grid's file catalog.
+
+\item Merge the tag files into one and store it accordingly (locally
+  or in the file catalog) \cite{RootApi}.
+
+\end{itemize}
+
+Fig. \ref{posttag} has a schematic view of these functionalities.
+
+
+\begin{figure}[ht!]
+   \centering
+   \includegraphics[width=15cm]{picts/tagpost}
+   \caption{A schematic view of the architecture of the post creation of the tag files.}
+   \label{posttag}
+\end{figure}
+
+The class that addresses this procedure is the \class{AliTagCreator}. The main methods of the class and their corresponding functionalities are described in the following lines:
+
+\begin{itemize}
+
+\item \method{AliTagCreator()}: The default constructor of the
+  class. It is used to initialize the private members.
+\item \method{void SetStorage(Int\_t storage)}: Allows the user to
+  define the place where the tag files will be stored. In general
+  there are two possibilities: the tags can either be stored locally
+  (storage = 0) or in the file catalog (storage = 1). If the user
+  defines some other value then an error message appears and the
+  process is aborted.
+
+\item \method{void SetSE(const char *se)}: This method can be used in
+  the case where the files will be stored in the grid. It allows the
+  user to define the desired storage element. If not selected the
+  default storage element will be used.
+
+\item \method{void SetGridPath(const char *gridpath)}: This method may
+  be used in the case where the files will be stored in the grid. It
+  allows the user to define the grid path under which the files will
+  be stored. If not selected the tag files will be stored in the home
+  directory of the user in the file catalog.
+
+\item \method{Bool\_t ReadGridCollection(TGridResult *result)}: This
+  method is used when creating tag files from ESDs that are stored in
+  the file catalog. It takes as an input the result of the query to
+  the file catalog \textit{TGridResult} and loops over the
+  corresponding entries. For each one the
+  \method{AliTagCreator::CreateTags(TFile *f, const char* guid, const char* md5, const char*turl, Long64\_t size, Int\_t Counter)}
+  protected method will be called to create the tag files that will be
+  stored accordingly.
+
+\item \method{Bool\_t ReadCAFCollection(const char* filename)}: This
+  method is used when creating tag files from ESDs that are stored in
+  the CERN Analysis Facility (CAF)\cite{CAF}. It takes as an input a
+  text file that has all the information about the location of the
+  files within the storage element of the CAF. For each one, the
+  \method{AliTagCreator::CreateTags(TFile *f, const char* filepath,
+    Int\_t Counter)} protected method will be called to create the tag
+  files that will be stored accordingly.
+
+\item \method{Bool\_t ReadLocalCollection(const char* localpath)}:
+  This method is used when creating tag files from ESDs that are
+  stored locally. It takes as an input the upper directory where the
+  ESD files are stored. The system assumes that one level down there
+  are several subdirectories where the AliESDs.root are store. The
+  method searches the file system and when it finds an ESD file the
+  \method{AliTagCreator::CreateTags(TFile *f, const char* filepath, Int\_t Counter)}
+ protected method will be called to create the tag
+  files that will be stored accordingly.
+
+\item \method{void CreateTag(TFile* file, const char *guid, const char *md5, const char *turl, Long64\_t size, Int\_t Counter)}:
+ Protected method that is called inside the
+ \method{AliTagCreator::ReadGridCollection(TGridResult *result)}
+ method. Creates the tag file and stores it locally if \method{AliTagCreator::SetStorage(0)}
+  or in AliEn if \method{AliTagCreator::SetStorage(1)}.
+
+\item \method{void CreateTag(TFile* file, const char *filepath, Int\_t Counter)}:
+ Protected method that is called inside the
+  \method{AliTagCreator:: ReadCAFCollection(const char* filename)} or
+  the \method{AliTagCreator:: ReadLocalCollection(const char* filepath)}
+ method. Creates the tag file and stores it locally if
+  \method{AliTagCreator::SetStorage(0)} or in AliEn if
+  \method{AliTagCreator::SetStorage(1)}.
+
+\item \method{Bool\_t MergeTags()}: Chains all the tags regardless of
+  the location (locally stored or in the grid) and merges them by
+  creating a single tag file having a name:
+  \textbf{Run}\textbf{\textit{RunId}}.\textbf{Merged}.\textbf{ESD.tag.root}.
+  This file is then stored either locally or in the grid according to
+  the value set in the \method{SetStorage} method.
+
+
+
+\end{itemize}
+
+\subsubsection{Usage of AliRoot classes}
+
+The following lines intend to give an example on how to use the
+\textbf{AliTagCreator} class in order to create tags. Additional
+information can be found in \cite{EventTagWeb}. There are three
+different cases depending on the location where the AliESDs.root files
+are stored:
+
+
+\begin{itemize}
+
+\item Locally stored AliESDs.root files.
+
+\item CAF stored AliESDs.root files.
+
+\item Grid stored AliESDs.root files.
+
+\end{itemize}
+
+We will address the three different cases separately.
+
+\underline{Locally stored AliESDs.root}
+
+We assume that for debugging or source code validation reasons, a user
+has a few AliESDs.root files stored locally. The files are stored
+under $\$HOME/PDC06/pp$. One level down, the directory structure can
+be of the form:
+
+
+\begin{itemize}
+
+\item xxx/AliESDs.root
+\item yyy/AliESDs.root
+\item zzz/AliESDs.root
+
+\end{itemize}
+
+\noindent where xxx is the directory name which can be something like
+\emph{Run1, Run2} etc or even the run number. In order to create the
+tag files for this case we need to create an empty
+\class{AliTagCreator} object. The next step is to define whether the
+produced tags will be stored locally on in the grid. If the second
+option is chosen, then the user should define the SE and the
+corresponding grid path where the tag files will be stored. If the
+first option is chosen, then the files will be stored locally in
+his/hers working directory. Finally the call of the
+\method{AliTagCreator::ReadLocalCollection(const char* filepath)}
+allows the user to query the local file system and create the tag
+files.
+
+
+\vspace{0.2 cm}
+
+\begin{lstlisting}[language=C++]
+  //create an AliTagCreator object
+  AliTagCreator *t = new AliTagCreator(); 
+  //Store the tag files locally
+  t->SetStorage(0);
+  //Query the file system, create the tags and store them
+  t->ReadLocalollection(''/home/<username>/PDC06/pp'');
+  //Merge the tags and store the merged file
+  t->MergeTags();
+\end{lstlisting}
+
+\underline{CAF stored AliESDs.root}
+
+In the case where the ESD files are stored in the CAF, then we take as
+an input the text file that has the information about the location of
+the files in the storage element of the system \cite{EventTagWeb,
+  CAF}. The next lines, where we assume that this input file is called
+\emph{ESD.txt} and is located in the working directory, indicate the
+steps that one has to follow:
+
+
+\begin{lstlisting}[language=C++]
+  //create an AliTagCreator object
+  AliTagCreator *t = new AliTagCreator(); 
+  //Store the tag files in AliEn's file catalog
+  t->SetStorage(0);
+  //Read the entries of the file, create the tags and store them
+  t->ReadCAFCollection(``ESD.txt'');
+  //Merge the tags and store the merged file
+  t->MergeTags();
+\end{lstlisting}
+
+\underline{GRID stored AliESDs.root}
+
+In the case where the ESD files are stored in the file catalog, then
+the first thing a user needs to have is a ROOT version compiled with
+AliEn support. Detailed information on how to do this, can be found in
+\cite{RootApi}. Then we need to invoke the AliEn's API services
+\cite{RootApi} and use as an input a query to the file catalog
+(\class{TGridResult}). The following lines give an example of the
+whole procedure:
+
+\begin{lstlisting}[language=C++]
+  //connect to AliEn's API services
+  TGrid::Connect("alien://pcapiserv01.cern.ch:10000","<username>");   
+  //create an AliTagCreator object
+  AliTagCreator *t = new AliTagCreator(); 
+  //Query the file catalog and get a TGridResult
+  TGridResult* result = 
+  gGrid->Query("/alice/cern.ch/user/p/pchrista/PDC06/pp/*",
+  "AliESDs.root","","");
+  //Store the tag files in AliEn's file catalog
+  t->SetStorage(1);
+  //Define the SE where the tag files will be stored
+  t->SetSE("ALICE::CERN::se01");
+  //Define the grid's path where the tag files will be stored
+  t->SetGridPath("PDC06/Tags");
+  //Read the TGridResult, create the tags and store them
+  t->ReadGridCollection(result);
+  //Merge the tags and store the merged file
+  t->MergeTags();
+\end{lstlisting}
+
+
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
+\newpage
 \appendix
 
 \section{Kalman filter}
@@ -4564,7 +5035,524 @@ are removed one-by-one from the sample, until no such tracks are left. The
 parameter $\chi^2_{\rm max}$ was tuned,
 as a function of the event multiplicity, so as to obtain the best vertex
 resolution.
+%%%%%%%%%%%%%%%%%%%%%%
+\newpage
+\section{Alignment framework}
+\subsection{Basic objects and alignment constants}
+The purpose of the \FR is to offer all the
+functionality related to storing alignment information, retrieving it from
+the Offline Conditions Data Base (OCDB) and consistently applying it to the
+ALICE geometry in order to improve the knowledge of the real geometry
+by means of the additional information obtained by
+survey and alignment procedures, without needing to change the
+hard-coded implementation of the detector's geometry.
+The \FR\ is based on the \lstinline{AliAlignObj}
+base class and its derived classes; each instance of this class is an
+\emph{alignment object} storing the so called \emph{alignment
+constants} for a single alignable volume, that is the information to
+uniquely identify the physical volume (specific instance of the volume
+in the geometry tree) to be displaced and to unambiguously describe the
+delta-transformation to be applied to that volume. 
+In the \FR\ an alignment object holds the
+following information:
+\begin{itemize}
+  \item a unique volume identifier
+  \item a unique global index
+  \item a delta-transformation
+\end{itemize}
+In the following we describe the meaning of this variables, how they
+are stored and set and the functionality related to them.
+
+\subsubsection{The unique volume identifier}
+The unique volume identifier is the character string which allows the user to
+access a specific physical volume inside the geometry tree. For the
+ALICE geometry (which is a \ROOT geometry) this is the \emph{volume
+path}, that is the string containing the names of all physical volumes
+in the current branch in the directory tree fashion. For example
+\lstinline!/A_1/B_i/.../M_j/Vol_k! identifies the physical volume ``kth
+copy of the volume \lstinline!Vol!'' by listing its container volumes;
+going from right to left in the path corresponds to going from the
+innermost to the outermost containers and from the lowest to the upper
+level in the geometry tree, starting from the mother volume
+\lstinline!M_j! of the current volume \lstinline!Vol_k! up to the
+physical top volume \lstinline!A_1!, the root of the geometry tree.
+
+The unique volume identifier stored by
+the alignment object is not the volume path but a ``\emph{symbolic volume
+name}'', a string dynamically associated to the corresponding volume
+path by a hash table built at the finalization stage of the geometry
+(the physical tree needs to be already closed) and stored as part of it.
+The choice of the symbolic volume names is constrained only by the
+following two rules:
+\begin{enumerate}
+  \item each name has to contain a leading sub-string indicating its
+  pertaining sub-detector; in this way the uniqueness of the name inside
+  the sub-detector scope guarantees also its uniqueness in the global
+  scope of the whole geometry.
+  \item each name has to contain the intermediate alignable levels,
+  separated by a slash ('\texttt{/}'), in case some other physical
+  volume on the same geometry branch is in turn alignable.
+\end{enumerate}
+There are two considerable advantages deriving from the choice to
+introduce the symbolic volume names as unique volume identifiers
+stored in the alignment object in place of the volume path:
+\begin{enumerate}
+  \item the unique volume identifier has no direct dependency on the
+  geometry; in fact changes in the volume paths reflect in changes in
+  the hash table associating the symbolic names to them, which is
+  built and stored together with the geometry.  As a consequence the
+  validity of the alignment objects is not affected by changes in the
+  geometry and hence is in principle unlimited in time.
+  \item The unique volume identifier can be freely chosen, according
+  to the two simple rules mentioned above, thus allowing to assign
+  meaningful names to the alignable volumes, as opposed to the volume
+  paths which inevitably are long strings of often obscure names.
+\end{enumerate}
+The geometry then provides the user with some methods to query the hash table
+linking the symbolic volume names to the 
+corresponding volume paths; in particular the user can 
+\begin{itemize}
+  \item get the number of entries in the table
+  \item retrieve a specific entry (symbolic volume name,
+    volume path) either by index or by symbolic name.
+\end{itemize}
+
+
+\subsubsection{The unique global index}
+Among the alignment constants we store a numerical index uniquely
+identifying the volume to which those constants refer; being a
+\lstinline!short!, this numerical index has 16 bits available which
+are filled from the index of the ``layer'' or sub-detector to which
+the volume belongs (5 bits) and from the ``local index'', i.e. the
+index of the volume itself inside the sub-detector (the remaining 11
+bits). Limiting the range of sub-detectors to $2^5=32$ and of
+alignable volumes inside each sub-detector to $2^{11}=2048$, this
+suites our needs.
+
+The aim of indexing the alignable volumes is fast iterative access
+during alignment procedures. The framework allows to easily
+browse the look-up table mapping indexes to symbolic volume names by
+means of methods which return the symbolic volume name for the present
+object given either its global index or both its layer and local
+indexes. For these methods to work the only condition is that at least
+one instance of an alignment object has been created, so that the
+static method building the look-up table has been called.
+
+
+\subsubsection{The delta-transformation}
+\label{ssec:delta}
+The delta-transformation is the transformation which defines the
+displacement to be applied to the given physical volume.
+During the alignment process we want to correct the hard-coded, ideal
+position of some volume, initially fixed according to the
+engeneers'drawings, by including the survey and alignment information
+related to those volumes; we say that we want to align the ideal
+geometry. With this aim, we need here to describe how the
+delta-transformations are defined and thus how they have to be produced and
+applied to the ideal geometry in order to correct the global and local
+ideal transformations into global and local aligned transformations.
+
+For the representation of the delta-transformation there are several
+possible conventions and choices, in particular: 
+\begin{enumerate}
+  \item to use the local-to-global or the global-to-local convention and
+    ``active-'' or ``passive-transformations'' convention;
+  \item to use the local or global delta-transformation to be stored in the
+    alignment object and to be passed when setting the object itself;
+  \item the convention used for the Euler angles representing the
+    delta-transformation;
+  \item the use of a matrix or of a minimal set of parameters (three
+    orthogonal shifts plus three Euler angles) to be stored in the
+    alignment object and to be passed when setting the object itself.
+\end{enumerate}
+The choices adopted by the framework are explained in the remaining of
+this section.
+
+\underline{Use of the global and local transformations}
+
+Being based on the \ROOT geometry package, the framework keeps the
+``local-to-global'' convention; this means that the \emph{global
+transformation} for a given volume is the matrix $\mathcal{G}$ which, as in
+\tgeo, transforms the local vector $\vec{l}$ (giving the position in the
+local reference system, i.e. the reference system associated to that volume)
+into the global vector $\vec{g}$, giving the position in the
+global (or master) reference system (``MARS''), according to:
+\begin{equation}
+\label{eq:l2g}
+\vec{g} = \mathcal{G}\vec{l}
+\end{equation}
+Similarly, the \emph{local transformation} matrix is the
+matrix $\mathcal{L}$ which transforms a local vector $\vec{l}$ into the
+corresponding vector in the mother volume RS, $\vec{m}$, according to:
+\begin{equation}
+\label{eq:l2m}
+\vec{m} = \mathcal{L}\vec{l}
+\end{equation}
+If furthermore $\mathcal{M}$ is the global transformation for the
+mother volume, then we can write:
+  $$ \vec{g} = \mathcal{G}\vec{l} = \mathcal{M}\vec{m} = \mathcal{M}\mathcal{L}\vec{l} $$
+Recursively repeating this argument to all the parent volumes, that is
+to all the volumes in the branch of the geometry tree which
+contains the given volume, we can write:
+  $$ \vec{g} = \mathcal{G}\vec{l} = \mathcal{M}_0...\mathcal{M}_n\mathcal{L}\vec{l} $$
+which shows that the global matrix is given by the product of the
+matrices of the parent volumes on the geometry branch, from the
+uppermost to the lowest level.
+
+Let's now denote by $\mathcal{G}$ and $ \mathcal{L}$ the ideal global
+and local transformations of a specific physical volume (those
+relative to the reference geometry) and let's put
+the superscript '$^a$' to the corresponding matrices in the aligned
+geometry, so that $\mathcal{G}^a$ and $ \mathcal{L}^a$ are the aligned
+global and aligned local transformations which relate the position of
+a point in the local RS to its position in the global RS and in the
+mother's RS respectively, after the volume has been aligned, according
+to:
+\begin{eqnarray}
+\vec{g} &=& \mathcal{G}^a\vec{l} \label{eq:l2ga}\\ 
+\vec{m} &=& \mathcal{L}^a\vec{l} \label{eq:l2ma}
+\end{eqnarray}
+Eqs.~(\ref{eq:l2ga})-~(\ref{eq:l2ma}) are the equivalent of
+Eqs.~(\ref{eq:l2g})-~(\ref{eq:l2m}) after the volume has
+been displaced.
+
+There are two possible choices for expressing the
+delta-transformation; either we use:
+\begin{itemize}
+\item the \emph{global delta-transformation} $\Delta^g$, that is the
+  transformation to be applied to the ideal global transformation
+  $\mathcal{G}$ in order to get the aligned global transformation:
+  \begin{equation}\label{eq:gadeltag}
+     \mathcal{G}^a=\Delta^g\mathcal{G}=\Delta^g\mathcal{M}\mathcal{L}
+  \end{equation}
+  or we use
+\item the \emph{local delta-transformation} $\Delta^l$, that is the
+  transformation to be applied to the ideal local transformation
+  $\mathcal{L}$ to get the aligned local transformation:
+  \begin{equation}\label{eq:laldelta}
+    \mathcal{L}^a=\mathcal{L}\Delta^l
+  \end{equation}
+\end{itemize}
+
+Eqs.~(\ref{eq:gadeltag})--(\ref{eq:laldelta}) allow to rewrite:
+  \begin{equation} %\label{eq:}
+    \mathcal{G}^a=\mathcal{M}\mathcal{L}^a
+  \end{equation}
+as:
+\begin{equation}
+\label{eq:localal}
+ \Delta^g\mathcal{M}\mathcal{L}=\mathcal{M}\mathcal{L}\Delta^l
+\end{equation}
+or equivalently:
+\begin{eqnarray}
+\Delta^g &=& \mathcal{G}\Delta^l\mathcal{G}^{-1} \label{eq:dltodg}\\
+\Delta^l &=& \mathcal{G}^{-1}\Delta^g\mathcal{G} \label{eq:dgtodl}
+\end{eqnarray}
+to relate global and local alignment.
+
+The alignment object stores as delta-transformation the global
+delta-transformation; nevertheless both global and local
+delta-transformations can be used to construct the alignment object or
+to set it.  The reasons for this flexibility in the user interface
+is that the local RS is sometimes the most natural one for expressing the
+misalignment, as e.g. in the case of a volume rotated around its
+centre; however the use of the local delta-transformation is sometimes
+error-prone; in fact the user has to be aware that he is referring to
+the same local RS which is defined in the hard-coded geometry when
+positioning the given volume, while the local RS used by simulation or
+reconstruction code can in general be different.  In case the
+alignment object is constructed or its delta-transformation is set by
+means of the local delta-transformation, the framework will then use
+Equation~(\ref{eq:dltodg}) to perform the conversion into global
+alignment constants.
+
+As for the choice of storing a symbolic volume name instead of the
+volume path as volume identifier, we would like to also make the
+delta-transformation stored in the alignment objects
+independent from the geometry, keeping thus their validity
+unconstrained. This is possible if we store in the geometry itself a
+matrix for the ideal global transformation related to that volume
+(this possibility is offered by the class storing the link between
+symbolic volume names and volume paths, see Section~\ref{sec:ROOT}).
+
+
+\underline{Matrix or parameters for the delta-transformation}
+
+The global delta-transformation can be saved both
+\begin{itemize}
+\item as a \lstinline!TGeoMatrix! and
+\item as a set of six parameters, out of which three define the
+  translation, by means of the shifts in
+  the three orthogonal directions, and three define the rotation
+  by means of three Euler angles.
+\end{itemize}
+This two cases correspond to choosing one of the following two
+\lstinline{AliAlignObj}- derived classes:
+\begin{itemize}
+  \item \lstinline!AliAlignObjMatrix!: stores a \lstinline!TGeoHMatrix!
+  \item \lstinline!AliAlignObjAngles!: stores six double precision floating
+  point numbers;
+\end{itemize}
+While storing the alignment constants in a different form, they appear
+with the same user interface, which allows to set the
+delta-transformation both via the matrix and via the six parameters
+which identify it.
+
+
+\underline{Choice for the Euler angles}
+
+A general rotation in three-dimensional Euclidean space can be
+decomposed into and represented by three successive rotations  about
+the three orthogonal axis. The three angles characterizing the three
+rotations are called Euler angles; however there are several
+conventions for the Euler angles, depending on the axes
+about which the rotations are carried out, right/left-handed systems,
+(counter)clockwise direction of rotation, order of the three rotations.
+
+The convention chosen in the \FR\ for the Euler angles is the
+``\emph{xyz convention}'' (see Ref.~\cite{mathworld}), also known as
+\emph{pitch-roll-yaw} or \emph{Tait-Bryan angles}, or \emph{Cardano
+angles} convention. Following this convention the general rotation is
+represented as a composition of a rotation around the $z$-axis (yaw)
+with a rotation around the $y$-axis (pitch) with a rotation around the
+$x$-axis (roll).There is an additional choice to fully specify the
+convention used, since the angles have opposite sign wheter we
+consider them bringing the original RS in coincidence with the aligned
+RS (``active-transformation'' convention) or the other way round
+(``passive-transformation'' convention). In order to maintain our
+representation fully consistent with the \lstinline!TGeoRotation!
+methods we choose the ``active-transformation'' convention, that is
+the opposite convention as the one chosen by the already referenced
+description of the pitch-roll-yaw angles (Ref.~\cite{mathworld}).
+
+To summarise, the three angles - $\psi$,$\theta$,$\phi$
+- used by the framework to represent the rotation part of the
+delta-transformation, unambigously represent a rotation $\mathcal{A}$
+as the composition of the following three rotations:
+\begin{enumerate}
+\item a rotation $\mathcal{D}$ by an angle $\phi$ (yaw) around the $z$-axis
+$$  \mathcal{D} = \left( \begin{array}{ccc}
+            cos\phi & -sin\phi & 0 \\
+            sin\phi & cos\phi & 0 \\
+            0 & 0 & 1
+        \end{array} \right)$$
+\item a rotation $\mathcal{C}$ by an angle $\theta$ (pitch) around the $y$-axis
+$$  \mathcal{C} = \left( \begin{array}{ccc}
+           cos\theta & 0 & sin\theta \\
+            0 & 1 & 0 \\
+            -sin\theta & 0 & cos\theta
+        \end{array} \right)$$
+\item a rotation $\mathcal{B}$ by an angle $\psi$ (roll) around the $x$-axis
+$$  \mathcal{B} = \left( \begin{array}{ccc}
+            1 & 0 & 0 \\
+            0 & cos\psi & -sin\psi \\
+            0 & sin\psi & cos\psi
+        \end{array} \right) $$
+\end{enumerate}
 
+which leads to:
+
+$$ \mathcal{A}  =  \mathcal{B} \mathcal{C} \mathcal{D} =
+      \left( \begin{array}{ccc}
+
+           cos\theta cos\phi & -cos\theta sin\phi & sin\theta \\
+           sin\psi sin\theta cos\phi + cos\psi sin\phi & -sin\psi
+           sin\theta sin\phi+cos\psi cos\phi & -cos\theta sin\psi \\
+           -cos\psi sin\theta cos\phi+sin\psi sin\phi & cos\psi
+           sin\theta sin\phi + sin\psi cos\phi & cos\theta cos\psi
+
+      \end{array} \right) $$
+
+\subsection{Use of \ROOT geometry functionality}
+\label{sec:ROOT}
+The ALICE geometry is implemented via the \ROOT geometrical modeller
+(often referred to as \tgeo), a framework for building, browsing,
+navigating and visualising a detector's geometry, which is independent
+from the Monte Carlo transport (see Ref.~\cite{tgeo} and the dedicated
+chapter in Ref.~\cite{rootUG}). This choice allows the \FR\ to take
+advantage of using \ROOT features such as its I/O,
+histogramming, browsing, GUI, \ldots.  However, the main advantage of
+this choice is that the \FR\ can provide its specific functionality as
+a rather thin layer on
+top of already existing features which allow to consistently and
+efficiently manage the complexity related to modifying a tree of some
+million of physical nodes.\\ The \FR\ takes in particular advantage of
+the possibility:
+\begin{itemize}
+  \item to save the geometry to a file and upload it from a file
+  \item to check the geometry for overlaps and extrusions exceeding a
+  given threshold
+  \item to query the geometry for the global and local matrix of a given
+  physical volume
+  \item to make a physical node out of a specific physical volume and
+  change the local and global transformation associated to it, while
+  keeping track of the original transformations
+  \item to store a hash table of links between symbolic volume
+  names and volume paths which can be queried in an efficient way
+\end{itemize}
+Concerning this last issue, the class representing the objects linking
+the symbolic volume names and the volume paths provides in addition
+the possibility to store a transformation. This feature turns out to be very
+useful if it is used to store the matrix relating the RS stored in the
+geometry (global transformation matrix for that volume) with the RS
+used in simulation and reconstruction (the two things in general differ).
+
+
+\subsection{Application of the alignment objects to the geometry}
+
+The base class provides a method to apply the single alignment object
+to the geometry present in memory, loaded from file or constructed;
+the method accesses the geometry to change the position of the volume
+referred by the unique volume identifier according to
+Equation~(\ref{eq:gadeltag}).  However this method alone cannot
+guarantee that the single object is applied correctly; the most common
+case is indeed the application of a set of alignment objects. In this
+case the framework has to check that the application of each object in
+the set does not invalidate the application of the others; when
+applying a set of alignment objects during a simulation or
+reconstruction run the framework transparently performs the following
+two checks:
+\begin{enumerate}
+\item in case of alignment objects referring to physical volumes on
+  the same branch, they have to be applied starting from the one which
+  refers to a volume at the uppermost level in the physical tree
+  (container volume) down to the one at the lowest level (contained
+  volume). On the contrary, if the contained volume is displaced first
+  the subsequent displacement of the container volume would change its
+  temporarily correct position;
+\item in no case two alignment objects should be applied to the same
+  physical volume separately.
+\end{enumerate}
+The reason for the first limitation is in short that the position of
+the contained volumes depend on the position of the container volumes.
+The reason for the second limitation is that the delta-transformations
+are relative to the ideal global position of the given volume (see
+Eq.~(\ref{eq:gadeltag})), which then need not to have been previously
+modified by the previous application of an alignment object referring to
+the same volume.
+The tools used by the framework for checking that the two previous
+conditions are fulfilled are respectively:
+\begin{enumerate}
+\item sorting the alignment objects based on a method which compares
+  the depth of the physical
+  volume to which the given alignment object refers.
+\item combining more alignment objects referring to the same volume
+  before applying them to the geometry.
+\end{enumerate}
+During a simulation or reconstruction run the user
+can consistently apply the objects to the geometry, having the two
+checks described above transparently performed.
+
+An additional check is performed during a simulation or reconstruction
+run to verify that the
+application of the alignment objects did not introduce big overlaps
+or extrusions which would invalidate the geometry (hiding some
+sensitive parts or changing the material budget during tracking). This
+check is done by means of the overlap checker provided by the
+\ROOT geometry package; a default threshold below which overlaps and
+extrusions are accepted is fixed; the \tgeo\ overlap checker favours speed
+(checks the whole ALICE geometry in few seconds) at the expense of
+completeness, thus same rare overlap topologies can eventually escape
+the check.
+
+\subsection{Access to the Conditions Data Base}
+\label{sec:CDBaccess}
+An important task of the \FR\ is to intermediate between the
+simulation and reconstruction jobs and the objects residing on the
+Offline Conditions Data Base (OCDB), both for defining a default
+behaviour and for managing specific use cases. The OCDB is filled
+with conditions (calibration and alignment) objects; the alignment
+objects in the OCDB are presently created by macros to reproduce two
+possible misalignment scenarios: the initial misalignment, according
+to expected deviations from the ideal geometry just after the
+sub-detectors are positioned and the residual misalignment, trying to
+reproduce the deviations which can not be resolved by the alignment
+procedures. The next step is to fill the OCDB with the alignment
+objects produced from the survey procedures, as soon as survey data
+are available to the offline. Finally these objects and those produced
+by alignment procedures will fill the OCDB to be used by the
+reconstruction of the real data in its different passes.
+
+The OCDB stores the conditions making use of the database capabilities
+of a file system three-level directory structure; the run and the
+version are stored in the file name.
+If not otherwise specified, the OCDB returns the last version of the 
+required object and in case of an object being uploaded it is
+automatically saved with increased version number.
+
+The \FR\ defines a specific default storage from which to load the
+alignment objects for all the sub-detectors; the user can set a
+different storage, either residing locally or on the grid if he has
+the permissions to access it. The definition of a non-default storage
+for the OCDB, as well as its deactivation can also be given for
+specific sub-detectors only, The user can also just switch off the
+loading of alignment objects from a OCDB storage or as a side-effect
+of passing to the simulation or reconstruction run an array of
+alignment objects available in memory.
+
+\subsection{Summary}
+\label{sec:Summary}
+
+The \FR, based on the \ROOT geometry package (see
+Refs.~\cite{rootUG,tgeo}), aims at allowing a consistent and flexible
+management of the alignment information, while leaving the related
+complexity as much as possible hidden to the user.  The framework
+allows to:
+\begin{itemize}
+  \item save and retrieve the alignment constants relative
+  to a specific alignable volume (automatic retrieval from a
+  Conditions Data Base is handled);
+  \item apply the alignment objects to the
+  current (ideal) geometry;
+  \item get from the current geometry the
+  alignment object for a specified alignable volume;
+  \item transform positions in the ideal global
+  RS into positions in the aligned global RS;
+  \item set the objects by means of both global and local
+  delta-transformations. 
+\end{itemize}
+These functionalities are built on the \lstinline!AliAlignObj! base
+class and its two derived classes, which store the
+delta-transformation by means of the transformation matrix
+(\lstinline!AliAlignObjMatrix!) or by means of the six transformation
+parameters (\lstinline!AliAlignObjAngles!). The user interface is the
+same in both cases; it fixes the representation of the
+delta-transformation while leaving several choices to the user which
+have been explained in this note together with their implementation.
+
+The \FR\ fixes the following conventions:
+\begin{itemize}
+  \item the transformations are interpreted according to the
+    local-to-global convention;
+  \item the delta-transformation stored is the global delta-transformation;
+  \item the three parameters to specify the rotation are the
+   roll-pitch-yaw Euler angles, with the ``active-transformations'' convention.
+\end{itemize}
+The framework fixes also the following default behaviours in
+simulation and reconstruction runs:
+\begin{itemize}
+  \item objects are loaded from a default Conditions Data Base
+    storage, on a sub-detector basis;
+  \item the set of loaded objects is sorted for assuring the consistency
+    of its application to the geometry;
+  \item the ideal and aligned geometries are saved.
+\end{itemize}
+Several choices related to the delta-transformation are left to the user, who:
+\begin{itemize}
+\item can choose to set the alignment object either by passing a
+     \lstinline!TGeoMatrix! or by giving the six parameters which uniquely
+     identify the global delta-transformation;
+\item can choose if he wants the object to store either the
+  \lstinline!TGeoMatrix!, using an \lstinline!AliAlignObjMatrix! or the six
+  parameters, using an \lstinline!AliAlignObjAngles!;
+\item can choose if the transformation he is passing is the global
+  delta-transformation or the local delta-transformation; in this
+  latter case the framework converts it to the global one to set the
+  internal data members.
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%%%
+\newpage
 \section{Glossary}
 
 \begin{description}
@@ -4856,6 +5844,39 @@ K. Odagiri, P. Richardson, M.H. Seymour and B.R. Webber, JHEP 0101
 \bibitem{PiotrPhD}
   P.Skowronski, PhD Thesis.
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\bibitem{EventTag} P.~Christakoglou, P.~Hristov, ALICE-INT-2006-023
+
+\bibitem{STAR} \url{http://www.star.bnl.gov/}
+
+\bibitem{GC1} A.~Shoshani, A.~Sim, and J.~Wu, "Storage resource
+  managers: Middleware components for grid storage", in Proceedings of
+  Nineteenth IEEE Symposium on Mass Storage Systems, 2002 (MSS 2002).
+
+\bibitem{GC2} K.~Wu et al, "Grid collector: An event catalog with
+  automated file management".
+
+\bibitem{RootSelector}
+  \url{http://agenda.cern.ch/fullAgenda.php?ida=a055638}
+
+\bibitem{EventTagWeb} \url{http://pcaliweb02.cern.ch/Offline/Analysis/RunEventTagSystem/}
+
+\bibitem{RootApi}
+  \url{http://agenda.cern.ch/askArchive.php?base=agenda\&categ=a045061\&id=a045061s0t5/transparencies} \\
+  \url{http://project-arda-dev.web.cern.ch/project-arda-dev/alice/apiservice/AA-UserGuide-0.0m.pdf}
+
+\bibitem{RootTGridResult}
+  \url{http://root.cern.ch/root/htmldoc//TGridResult.html}
+
+\bibitem{CAF} \url{http://pcaliweb02.cern.ch/Offline/Analysis/CAF/}
+
+\bibitem{mathworld} \url{http://mathworld.wolfram.com/EulerAngles.html}
+
+\bibitem{rootUG}
+    \ROOT User's Guide, \url{http://root.cern.ch/root/doc/RootDoc.html}
+
+\bibitem{tgeo} R. Brun, A. Gheata and M. Gheata, The \ROOT geometry package, NIM A502 (2003) 676-680
+
 \end{thebibliography}
 
 \end{document}