1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 % AliFemto Documentation - User Guide and Reference Manual -- LaTeX source
4 % ALICE Experiment Femtoscopic Analysis framework
5 % Mike Lisa 17 May 2006
6 % [Based on similar document for StHbt (STAR framework), Mike Lisa 22 May 2006]
8 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
9 \documentclass[twoside]{article}
11 \newcommand {\DocumentVersionNumber} {1.1} %%% this is the Version Number
17 %\usepackage[T1]{fontenc}
18 %\renewcommand*\ttdefault{txtt}
19 %\renewcommand*\familydefault{\ttdefault}
25 \advance\textwidth by 80pt%
26 \advance\evensidemargin by -80pt%
28 %\renewcommand{\familydefault}{cmss}
31 %%%%%%\usepackage{pdffig}
43 \usepackage{subfigure}
44 %%%\usepackage[dvips=true,hyperindex=true,colorlinks=true,linkcolor=blue,bookmarks=true]{hyperref}
45 \usepackage[hyperindex=true,colorlinks=true,linkcolor=blue,bookmarks=true]{hyperref}
47 \PScommands % init boxit
50 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
52 % Define header and footer style
54 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
55 \pagestyle{fancyplain}
56 \rhead[\fancyplain{}{\bfseries\leftmark}]
57 {\fancyplain{}{\bfseries\rightmark}}
58 \lhead[\fancyplain{}{\bfseries\rightmark}]
59 {\fancyplain{}{\bfseries\leftmark}}
60 \rfoot[{}]{\fancyplain{}{\bfseries\thepage}}
61 \lfoot[\fancyplain{}{\bfseries\thepage}]{}
64 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
66 % Typographic Conventions
68 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
69 \newcommand{\name}[1]{\textsf{#1}}% or class-, function-, package names
70 \newcommand{\comp}[1]{\texttt{#1}}% computer font
71 \newcommand{\args}[1]{\textit{#1}}% command arguments
72 \newcommand{\meth}[1]{\textsf{#1}}% class methods
74 %%% font for package names
76 \newcommand{\AliEn}{{\tt AliEn }}
77 \newcommand{\AliFemto}{{\tt AliFemto }}
78 \newcommand{\AliRoot}{{\tt AliRoot }}
79 \newcommand{\ROOT}{{\tt ROOT }}
80 \newcommand{\StHbt}{{\tt StHbt }}
81 \newcommand{\cvs}{{\tt StHbt }}
84 %% removed a bunch of unused (?) \newcommand statements
87 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
89 % Define multiline labels for class reference
91 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
92 \newcommand{\entrylabel}[1]{\mbox{\textbf{{#1}}}\hfil}%
93 \newenvironment{entry}
95 {\renewcommand{\makelabel}{\entrylabel}%
96 \setlength{\labelwidth}{90pt}%
97 \setlength{\leftmargin}{\labelwidth}
98 \advance\leftmargin by \labelsep%
103 \newcommand{\Entrylabel}[1]%
104 {\raisebox{0pt}[1ex][0pt]{\makebox[\labelwidth][l]%
105 {\parbox[t]{\labelwidth}{\hspace{0pt}\textbf{{#1}}}}}}
106 \newenvironment{Entry}%
107 {\renewcommand{\entrylabel}{\Entrylabel}\begin{entry}}%
113 %%% font for AliFemto class/method/attribute names
114 %%% ---- at some point, let's find some nice font...
116 \newcommand{\acf}[1]{{\tt \bf #1}}
120 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
124 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
129 {\Large\bf AliFemto - A Femtoscopic Analysis Framework for ALICE}
130 \hfill\mbox{}\\[4.5cm]
131 \mbox{\includegraphics[width=\textwidth]{AliFemtoTitle.pdf}}
133 {\LARGE User Guide and Reference Manual}\\[2cm]
134 {\LARGE Revision \DocumentVersionNumber} \\[5mm]
135 {\LARGE \today} % replaced by cvs with current revision
140 \pagenumbering{roman}
142 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
146 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
151 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
155 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
156 \pagenumbering{arabic}
159 \setcounter{section}{-1}
160 \section{About this document}
162 This is the Users' Guide and Reference Manual for the \AliFemto software package,
163 for use in the ALICE experiment at the Large Hadron Collider.
164 The femtoscopy analysis effort in ALICE is in the Physics Working Group 2. Thus,
165 the software described here may be found in the {\tt PWG2/FEMTOSCOPY } area when
166 \AliRoot is checked out.
168 The files (.tex, .pdf, etc.) for this documentation are cvs-controlled along with
169 the \AliFemto code in the ALICE repository under the {\tt PWG2/FEMTOSCOPY/Documentation } area.
170 While earth-moving changes in the framework are not anticipated, this manuscript will be to some
171 extent a ``living document.'' The reposisory version of the documentation
172 should be considered the ``official'' source of information on the package at any given time.
174 This document consists of two parts. The Users' Guide introduces the package and, perhaps most
175 interestingly to the reader, provides a blow-by-blow example of its use. The Reference Manual
176 is essentially a listing and short description of the classes and the limited inheritance
179 \AliFemto will often be run in a larger framework than a simple \ROOT or \AliRoot session, e.g.
180 \AliEn and the Task-Train framework in ALICE. This manual focusses only on \AliFemto itself.
181 For tutorials on how to run \AliFemto within these contexts, see
182 the ALICE femtoscopy web pages\\
183 {\tt http://aliceinfo.cern.ch/Collaboration/PhysicsWorkingGroups/PWG2/Femtoscopy/}.
194 \section{Introduction - Basics and Motivation}
197 Femtoscopy-- the measurement of the space-time structure of dynamic systems at the fermi scale--
198 is an integral tool in studies in high-energy particle (e.g. p+p) and heavy ion (e.g. Pb+Pb)
199 collisions. It can also be a non-trivial, somewhat subtle tool, with nonobvious experimental
200 ``traps'' which are periodically redisovered as expertise evaporates and algorithms are lost.
202 Especially in large modern high energy experimental collaborations, complex experimental
203 issues impact on this already-delicate tool. Furthermore, by the nature of such collaborations,
204 ``Physics Working Groups'' (PWGs) are commonly formed, in which several collaborators work on
205 similar physics topics (e.g. femtoscopy) which share common techniques and problems. Sharing
207 solutions among PWG members is invaluable to work through problems quickly and to assure quality
208 and consistency in physics results. In addition to regular discussions by phone/vrvs/email, sharing
209 a common software analysis infrastructure allows for rapid and collaborative development, testing
210 and sharing of solutions. Production of quality physics results in a timely manner demands the
211 use of all available collaborative tools; while cross-checks are always crucial to an analysis,
212 re-creating the many aspects of a wheel is sometimes a (all-too-common) waste of valuable manpower.
214 Just as code-sharing {\it within} a collaboration or PWG is desirable when analysis techniques
215 are similar, code-sharing {\it between} collaborations or PWGs may be equally beneficial, if the
216 similarities are sufficiently great. Code reusability is often claimed as one of the most important
217 benefits of well-designed object-oriented programming. Through the development of standardized tools
218 and inheritance schemes, high-energy physics has largely moved away from perpetual re-implementation
219 of established algorithms.
220 Previously, the student who needed a particular ``twist'' to, say a resonance-finding technique,
221 would often find it easiest to start from scratch in a self-contained Fortran code. This was due
222 to the fact that the {\it previous} student's Fortran code lacked extensibility; e.g. interfaces
223 and common blocks were specialized for a particular, narrow purpose. With care, languages such as
224 C++ provide a natural solution. The student can focus on {\it new} aspects of her problem (the purpose,
225 after all, of research) and the science behind it. The {\it same} objects and elements of the {\it same}
226 code, developed and refined by others, are at her disposal; likewise, she will make her own contributions
227 and everybody benefits.
228 Likewise, so long as the detector and reconstruction configurations of two experiments
229 are sufficiently similar, both collaborations may benefit by sharing some code.
231 This document discusses a two-particle correlation software package for use in the ALICE experiment
232 at the LHC. It is based largely on the framework (StHbt) used since 1999 in the STAR experiment at
233 RHIC, an experiment remarkably similar to ALICE in all respects. StHbt, itself, was developed by
234 femtoscopy experts from earlier heavy ion experiments at the AGS and SPS; as such, it distills the
235 generic features of any heavy ion femtoscopic analysis. The femtoscopy group in ALICE is arguably
236 the most complete collection of the world's experts in this sub-field ever assembled. It is hoped
237 that this common analysis software will enable a maximum positive superposition of the experience
241 \subsection{Femtoscopy, HBT, and heavy ions}
243 The feature distinguishing heavy ion from particle physics is the dominance of space-time
245 This is manifest in the fact that we seek the geometrically-largest systems in order to approximate
246 the infinite system in which thermodynamic variables and phases of matter become meaningful.
247 At all stages of the the dynamic system's evolution, geometry rules.
248 The geometric overlap anisotropy of the entrance channel is known to dominate the subsequent
249 evolution of the bulk, and focusing systematics of geometric entrance-channel quantities
250 (e.g. reaction-plane, impact parameter) yields much more information than geometric averages
251 over these quantities. In the intermediate stage of the collision, path-lengh considerations
252 are crucial to determine the physics of so-called ``jet quenching'' at the highest energies.
253 Further, we seek a system in which coloured degrees of freedom
254 are relevant over ``large'' length scales. Much of the dynamic bulk physics is reflected in the
255 end freeze-out stage in collective observables (e.g. flow) which are usually defined in terms
256 of space-momentum correlations.
257 Clearly, geometry is a key defining feature of our field; momentum space alone is less than
260 However, particle momentum is precisely what we measure. Geometrical information must be
261 inferred. The most direct and common method of doing so is through femtoscopy, the use of
262 two-particle momentum-space correlations to probe fermi-scale emission zones. Experimental
263 and theoretical aspects of femtoscopy are discussed at length
264 elsewhere~\citep[][and references within]{Lisa:2005dd}. Without becoming mathematical, the
265 main point is to measure the increase (or decrease) of the likelihood of measuring a particle
266 with a particular momentum, given the presence of another particle; in other words, the effect
267 on the conditional probability. The effect to be measured is driven by the two-particle wavefunction, which
268 depends on relative momentum (measured) and relative position (inferred). The probability $A$
269 as a function of a measured relative quantity (typically relative momentum
270 ${\bf q}$, so $A \sim dN/d{\bf q}$) is usually dominated by detector acceptance and single-particle
271 phasespace; the modification due to two-particle effects represent only a small perturbation.
272 Thus, some sort of comparison to a reference distribution $B({\bf q})$ is usually performed.
273 Ideally, $B$ contains all single- and two-particle acceptance and efficiency effects and lacks
274 only the sought-for correlation. The distribution $B$ is often generated by so-called ``mixed-event''
275 techniques, and the correlation function $C$, ideally containing only 2-particle
276 correlations due to the relative wavefunction, given by
279 C({\bf q})=\frac{A({\bf q})}{B({\bf q})}
281 It should be stressed, however, that neither using ${\bf q}={\bf p_1}-{\bf p_2}$ as a two-particle
282 variable, generating histrograms/distributions $A$ or $B$, nor taking any ratio $C$ must be associated
283 with a correlation analysis, in general. See Section~\ref{sec:bones} below.
285 Briefly, some terminology which the reader may encounter. Two-particle femtoscopic measurements
286 are related to the pioneering work of Hanbury-Brown and Twiss over half a century ago, to measure
287 the angular size of stars~\cite{HanburyBrown:1954}. (The relationship, however, is somewhat more
288 oblique than often realized.) Thus, similar analyses in high-energy physics
289 are often referred to as ``HBT'' studies. For reference,
290 the first actual application to high-energy physics was performed by Goldhaber, Goldhaber,
291 Lee and Pais~\cite{Goldhaber:1960sf} shortly thereafter; thus correlations for pions reflect
292 the ``GGLP effect.'' The rubrik of femtoscopy~\cite{Lednicky:2002fq} is nowadays
298 \subsection{The bones of a femtoscopic analysis}
300 Similar algorithmic requirements and characteristics appear in a wide range of femtoscopic (and non-femtoscopic)
301 analyses. AliFemto was designed as a common analysis framework for collaborators conducting diverse
302 analyses sharing nevertheless a large overlap of techniques.
304 The design was driven by asking two questions: ``What {\it is} a femtoscopy-style analysis, in general?'' and
305 ``What sorts of actions will be common to most analyses and what sorts will be person-specific?''
307 The first question may be answered with the following rough procedure. Names of class types inside square brackets []
308 are discussed in Sections~\ref{sec:AliFemtoDiagramEtc} and~\ref{sec:coreUser}.
311 \item\label{it:read} Obtain an event (usually, data associated with one collision) from somewhere. [\name{AliFemtoEventReader}]
312 \item\label{it:write} (Optional) Write the event (or portions thereof) to a file, [\name{AliFemtoEventReader}]\\
313 The output file does not neccessarily use the same format as the input.
314 \item\label{it:EvCut} Decide to use or discard (``cut on'') the event in the analysis. [\name{AliFemtoEventCut}]
315 \item\label{it:TrCut} Select (``cut on'') the particles of interest. [\name{AliFemtoParticleCut}]
316 \item\label{it:Reals} Form pairs of particles coming from the present event. [\name{AliFemtoAnalysis}]
317 \item\label{it:PrCut} Cut on these pairs. [\name{AliFemtoPairCut}]
318 \item\label{it:Num} Do ``something'' with these pairs. [\name{AliFemtoCorrFctn}]\\
319 {\it Usually}, but not neccessarily, this involves calculation of some relative
320 variable (e.g. a relative momentum) and incrementing a histogram.
321 %%\item\label{it:Num} Send pairs passing the PairCut to the several CorrFctns for further processing.
322 \item\label{it:Mix} {\it Usually,} form other pairs of particles to construct a reference pair
323 distribution. [\name{AliFemtoAnalysis}]\\
324 {\it Usually} this is related to generating pairs (``mixed'' pairs) of
325 particles between the present event and similar events which are sitting in
327 \item\label{it:PrCut2} Cut on these pairs. [\name{AliFemtoPairCut}]\\
328 {\it Almost always}, it is an identical cut as used in step~\ref{it:PrCut}.
329 \item\label{it:Den} Do ``something'' with these pairs. [\name{AliFemtoCorrFctn}]\\
330 {\it Usually}, but not neccessarily, this involves calculation of some relative
331 variable (usually the same one as in step~\ref{it:Num}) and incrementing a histogram.
332 \item\label{it:Store} Store the present event into the EventBuffer. [\name{AliFemtoAnalysis}]
333 \item\label{it:loop} Return to step~\ref{it:read} for the next event. [\name{AliFemtoManager}]
336 The first question is thus addressed by implementing the above basic functionality in methods of common classes.
337 Considerations about the second question are reflected in the class inheritance structure and division of classes
338 into ``central'' and User classes. We discuss this below.
340 \section{The Structure and use of \AliFemto}
341 \label{sec:AliFemtoDiagramEtc}
343 \AliFemto is a flexible and extendable software package in the \ROOT framework for performing two-particle
344 femtoscopic studies. The basic design and structure of the package is essentially unchanged since its
345 original deployment in the STAR Experiment at RHIC in 1999. However, its functionality and features
346 have been developed considerably by continuous use in experimental and model analyses by the STAR-HBT
347 group since then. The package was designed from the beginning to be independent of the STAR analysis framework
348 (root4star). Thus, it is easily used for ALICE-specific analyses (either in \AliRoot or ``vanilla'' \ROOT)
349 or for model studies in any root flavor.
351 {\bf Important note:}
352 In this Section, we discuss the structure of the code, and a specific example of how to use it in ``vanilla'' or pure \AliRoot
353 mode. In other words, here we run with a simple \ROOT macro. If we run instead in the ALICE {\tt task} framework, then the
354 operations described here are performed by the {\tt AliFemtoTask}, rather than the user directly. Translation between these
355 modes of operation is transparent. For tutorials on how to run \AliFemto within the {\tt task} framework, \AliEn, etc, see
356 the ALICE femtoscopy web pages\\
357 {\tt http://aliceinfo.cern.ch/Collaboration/PhysicsWorkingGroups/PWG2/Femtoscopy/}.
360 \subsection{Top level}
362 The top-level structure of AliFemto is shown in Figure~\ref{fig:TopLevelUML} in simplified Unified Modeling Language (UML)~\cite{UMLreference} format.
363 Here, we describe generally the classes shown, and their interaction. See the Reference Manual for details.
366 \includegraphics[width=\textwidth]{TopLevelUML.pdf}
367 \caption{The large-view structure of the code.
368 Yellow classes at the periphery are bases for user-written
369 classes.\label{fig:TopLevelUML}
374 \subsubsection{AliFemtoManager}
376 There is a single \name{AliFemtoManager} object for any \AliFemto session.
377 \name{AliFemtoManager} controls all \AliFemto actions; it is this (through
378 the four methods \meth{Init()}, \meth{ProcessEvent()}, \meth{Report()}, and \meth{Finish()}) with which the user
380 There is only one AliFemtoManager, instantiated by the user (or the {\tt AliFemtoTask}-- see beginning of
381 Section~\ref{sec:AliFemtoDiagramEtc}), and objects are ``plugged into'' it by the user at runtime;
382 see Section~\ref{sec:example} for an example.
384 In order to proceed with an \AliFemto study, the \name{AliFemtoManager} must have an \name{AliFemtoEventReader}, which passes event information
385 to it. Optionally, the \name{AliFemtoManager} may also have one or more {\it other} \name{AliFemtoEventReader}
386 objects, which are in ``Write'' mode and
387 which takes the event data and writes it to a fiile. This is useful in order to change data format or to write out only a selection
388 of the events or information within events. Also optionally (but usually the case), the \name{AliFemtoManager} will have one or more
389 \name{AliFemtoAnalysis}
390 objects; it is these which perform correlation studies. In principle, the \name{AliFemtoManager} may have neither Writers or Analyses, but
391 in this case nothing gets done with the data.
393 \subsubsection{AliFemtoEventReader}
394 \label{sec:AliFemtoEventReader}
396 Typical users will not need to write \name{AliFemtoEventReader}s, but will instead use a standard one. We discuss its basics here
400 The job of the \name{AliFemtoEventReader} is to pass events, upon request, to the \name{AliFemtoManager}.
401 How the events are obtained (reading from
402 a data or simulation file, reading from some location in memory filled by someone else, random generation within the \name{AliFemtoReader} itself...) is
403 immaterial. Regardless
404 of the data format read in by the \name{AliFemtoReader}, the data is passed to the \name{AliFemtoManager} in the form of an \name{AliFemtoEvent}.
405 (See the Reference Manual for full details on the content and structure of \name{AliFemtoEvent}.)
407 of \AliFemto code is unaware of external data sources or formats; all such dependency is confined to the \name{AliFemtoEventReader}-derived classes.
410 \name{AliFemtoEventReader} is, itself, a base class, with a pure virtual method \meth{ReturnHbtEvent()}. For any given application/datasource (e.g.
411 ALICE ESDs, Geant kine banks, RQMD files), a class must be written which inherits from AliFemtoEventReader.
412 In the simillar STAR package, of order 10 specific Reader classes
413 are available for use now; they will be developed for ALICE as needed.
414 It is expected that the typical user will not need to write his own \name{AliFemtoEventReader} class, but simply select one already written.
415 It is one of these derived classes which is ``plugged into'' the \name{AliFemtoManager}. Once the user instantiates and configures
416 the Reader, she typically does not interact with it anymore. A specific example is given in Section~\ref{sec:example}
420 \subsubsection{AliFemtoAnalysis}
421 \label{sec:AliFemtoAnalysis}
423 Typical users will not need to write \name{AliFemtoAnalysis} objects, but will instead select among standard ones. We discuss the basics here
427 The most important element of an \AliFemto study is the Analysis. All Analysis classes derive from the interface class
428 \name{AliFemtoAnalysis}, which has three important pure virtual methods.
429 They must implement (even if it is a ``do-nothing'' method) a \meth{Finish()} method, which will be invoked by
430 the \name{AliFemtoManager} just before the session ends. Also, each \{name{AliFemtoAnalysis} class must generate
431 a \meth{Report()} (c.f. Section~\ref{sec:reports}).
434 Finally and most importantly, an \name{AliFemtoAnalysis} class must be able to \meth{Process()}
435 an \name{AliFemtoEvent}. What it does with the \name{AliFemtoEvent}, even if it simply ignores it, is
436 of course not important to the \name{AliFemtoManager}.
437 In practice, naturally, an Analysis {\it does} process the data, making cuts and extracting correlations.
438 The simplest \name{AliFemtoAnalysis}-derived class, \name{AliFemtoSimpleAnalysis}, is a good example of this. We discuss this in
439 Section~\ref{sec:analysisLevel}.
441 \subsubsection{Action flow}
442 Briefly, each time \name{AliFemtoManager}::\meth{ProcessEvent()} is invoked by the user (or Task, or whatever),
443 it obtains an \name{AliFemtoEvent} from its \name{AliFemtoEventReader}.
444 It then passes this \name{AliFemtoEvent} to each of its Writers through the \meth{WriteHbtEvent()} method.
445 Finally, it passes the \name{AliFemtoEvent} to each of its {\name AliFemtoAnalysis::}{\meth ProcessEvent({\args AliFemtoEvent*})}.
449 \subsection{Analysis level}
450 \label{sec:analysisLevel}
452 The \name{AliFemtoAnalysis} is usually the focus of any \AliFemto session. As discussed in Section~\ref{sec:AliFemtoAnalysis},
453 the only requirement of such an object in principle is that it must accept an \name{AliFemtoEvent} object via its \meth{ProcessEvent} method.
454 However, in practice, \name{AliFemtoAnalysis}-derived classes almost always contain Cuts, CorrFctns, etc. We describe these
457 A UML representation of the class structure of an Analysis is shown in Figure~\ref{fig:analysisUML}.
460 \includegraphics[width=\textwidth]{Analysis.pdf}
461 \caption{The basics of an Analysis configuration in UML representation. Most classes shown are base classes.
462 Appending ``= 0'' to a method name denotes pure virtuality-- the method is not defined in the base class, but must
463 be defined in any instantiated class which derives from it. Yellow classes at the periphery are bases for user-written
464 classes.\label{fig:analysisUML}
468 \subsubsection{AliFemtoEventCut}
470 The first action of an \name{AliFemtoAnalysis} is usually to invoke the method \name{AliFemtoEventCut::{\meth Pass(\args{AliFemtoEvent*})}}.
472 a boolean value (and may, internally, store information about the \name{AliFemtoEvent} passed to it). If the event does not
473 Pass, no further processing is done by the AliFemtoAnalysis-- control returns to the \name{AliFemtoManager}.
475 The Reference Manual gives the full implementation of a simple \name{AliFemtoEventCut}.
478 \subsubsection{AliFemtoParticleCuts}
479 \label{sec:AliFemtoParticleCuts}
481 Depending on the topological nature of the particles being selected,
482 one uses the class \name{AliFemtoTrackCut}, \name{AliFemtoV0Cut}, \name{AliFemtoKinkCut}, or \name{AliFemtoXiCut}.
483 All of these inherit from \name{AliFemtoParticleCut};
484 see Figure~\ref{fig:analysisUML}. As with all cuts, these classes have pure virtural \meth{Pass()} methods.
485 An Analysis has two \name{AliFemtoParticle} cuts, corresponding to the two particles used in the correlation analysis.
487 There is ``special'' behaviour when the \name{AliFemtoParticle} cuts are applied. For each AliFemtoTrack/V0/Kink/Xi which Passes the cuts,
488 an \name{AliFemtoParticle} is created. (The \name{AliFemtoParticle} objects themselves
489 are created and used within the Analysis-- the user is not concerned with them.)
490 It is the \name{AliFemtoParticle} objects (not \name{AliFemtoTracks} etc) which are used at further steps in the Analysis
491 for the current event. {\bf Important:} all \name{AliFemtoParticleCut}-derived objects set the mass of the particle it selects. Based on
492 kinematic and PID information, the user, through the \name{AliFemtoParticleCut}, decides e.g. that the Track is a proton; the user needs to
493 tell the \name{AliFemtoParticleCut} the mass of the proton; c.f. Section~\ref{sec:example}. When the \name{AliFemtoParticle} corresponding to this
494 \name{AliFemtoTrack} is created, it is at this point that the mass of the proton is assigned to the particle.
496 \subsubsection{AliFemtoPairCut}
498 As the name suggests, user-written classes which derive from \name{AliFemtoPairCut} must have a \meth{Pass()} method selecting
499 \name{AliFemtoPairs} for further processing. (\name{AliFemtoPair}s are created and used internally; the user does not interact with them.)
500 These cuts may, for example, try to discriminate ``fake'' pairs caused by splitting or (for the reference pair distribution)
501 those tracks which would merge.
503 Importantly, the Analysis will automatically apply the {\it same} \name{AliFemtoPair} cut to pairs generated from ``real'' and from ``mixed''
504 events. Almost always, this is very important for femtoscopic analyses. However, if neccessary, one may circumvent this behaviour
505 by attaching \name{AliFemtoPairCut} objects to the correlation function object itself. In this case, different PairCuts may be applied to ``real'' and
506 reference distributions.
508 \subsubsection{AliFemtoCorrFctn}
510 The ``end result'' of most femtoscopic studies is the correlation function. These compare somehow (often via a ratio of
511 distributions, c.f. Equation~\ref{eq:usualC}) ``real'' and reference pairs. In general, then, a user-written class which
512 derives from \name{AliFemtoCorrFctn} should implement \meth{AddRealPair(\args{AliFemtoPair})} and \meth{AddMixedPair(\args{AliFemtoPair})}
513 methods. These methods may do whatever the user
516 Most CorrFctn classes are rather simple. See the Reference Manual for a full listing of an example.
518 Often, one wishes to construct several correlation functions simultaneously (e.g. one in $Q_{inv}$, $\vec{q}_{3D}$, $\Theta_{opening}$ etc).
519 For this reason, every \name{AliFemtoAnalysis} may have several \name{AliFemtoCorrFctn} objects.
520 The same \name{AliFemtoPair}s are sent to each \name{AliFemtoCorrFctn}.
523 \subsubsection{Action flow}
525 The most important action of each \name{AliFemtoAnalysis} is in its \meth{ProcessEvent(\args{AliFemtoEvent*})} method.
526 corresponds approximately to steps~\ref{it:EvCut}-\ref{it:Store} of the list in Section~\ref{sec:bones}.
527 Upon being given an Event by the Manager, it first sends it to its EventCut. If \name{AliFemtoEventCut::\meth{Pass(\args{AliFemtoEvent*})}}
528 returns false, the method returns with no further action.
530 Otherwise, an \name{AliFemtoPicoEvent} (essentially two lists of \name{AliFemtoParticle}s, c.f. Section~\ref{sec:AliFemtoParticleCuts}) is formed from
531 the particles which Pass the \name{AliFemtoParticleCuts}. All possible pairs of these Particles are tested by the
532 \name{AliFemtoPairCut::\meth{Pass()}} method,
533 and those which Pass are sent to each of the \name{AliFemtoCorrFctn}'s \meth{AddRealPair(\args{AliFemtoPair*})} methods.
535 Then, ``mixed'' \name{AliFemtoPair}s are formed by combining all \name{AliFemtoParticles} from the present event with those of previously-processed
536 events, which have been stored in a collection of \name{AliFemtoPicoEvents}. (C.f. Figure~\ref{fig:analysisUML}; the user need not interact
537 with this aspect of the code.) All such Pairs are formed. These are evaluated by the \name{AliFemtoPairCut} and those which Pass are sent to
538 each of the \name{AliFemtoCorrFctn::\meth{AddMixedPair(\args{AliFemtoPair*})}} methods.
540 Finally, the AliFemtoPicoEvent is put into the list (c.f. Figure~\ref{fig:analysisUML}) of such objects for mixing with future events,
541 and control returns to the AliFemtoManager.
543 As mentioned previously, the above procedure is just one typical of Analyses. In principle, one's specific Analysis class might
544 email the user each pair, or each particle at random.
550 Note that most classes above have \meth{Report()} methods. These are simple user-written methods returning strings which can tell something about
551 what happened to that class during the study. E.g. a \name{AliFemtoEventCut} might Report on how many events passed/failed the
552 cut. The content of the Report is up to the user; it might be even an empty string or your spouse's name.
555 At the end of the session, the Reports of the various objects are concatenated in the following way.
557 Each AliFemtoAnalysis
558 collects Reports from its AliFemtoEventCut, AliFemtoParticleCut (for both the first and second particle), AliFemtoPairCut, and all
559 of its AliFemtoCorrFctn objects. These are concatenated with any other information coming from the AliFemtoAnalysis itself.
560 This constitutes the Report of the AliFemtoAnalysis.
562 The AliFemtoManager collects Reports from each of its AliFemtoEventReader objects (both those in read and write mode)
563 and from each of its AliFemtoAnalysis objects. These are concatenated and constitute the final Report
564 printed to the screen (or log file).
566 %==========================================================
567 %==================== Example =============================
568 %==========================================================
571 \subsection{Example macro}
574 Here, we show a specific macro which may be used to perform two Analyses which produce several CorrFctns. The example
575 shown is for use in ``pure'' root. It may also be used as a simple macro in AliRoot or, as been previously mentioned,
576 it is straightforward to wrap it in a Task or Train (or, in STAR, the BFC Chain).
578 Figures~\ref{fig:exampleMacroGload}-\ref{fig:exampleEventLoop} in this Section are only cartoons suggesting what the
579 code in the macro does-- they are not UML. All classes in this specific example are user-written
580 classes, with the exception of AliFemtoManager. (Several of them such as the \name{AliFemtoEventReaderESD} class,
581 have already been written and are provided in the \cvs checkout.)
582 For details, see Sections~\ref{sec:topLevel} and~\ref{sec:analysisLevel}.
585 \subsubsection{Initialization and plugging in the Reader}
586 %--------------------- Example Step 1 ----------------------
589 \includegraphics[width=\textwidth]{ExampleMacro1.pdf}
590 \caption{The preliminaries in a \AliFemto macro: loading of the libraries, instantiation of top-level structure, and
591 instantiating and plugging in a Reader.
592 The cartoon is meant so suggest the action of the macro commands; it is not a UML diagram.
593 \label{fig:exampleMacroGload}
598 \includegraphics[width=\textwidth]{ExampleMacro2.pdf}
599 \caption{The construction of a specific \name{AliFemtoAnalysis}, including its cuts and collection of three CorrFctn
600 objects. The dark shaded region in the cartoon denotes a collection.
601 \label{fig:exampleFirstAnalysisStart}
606 \includegraphics[width=\textwidth]{ExampleMacro3.pdf}
607 \caption{The final step in configuring the first Analysis is to set the number of events to mix when constructing
608 the ``background'' distribution. This finished Analysis (dark grey box) is then added to the collection of Analyses
609 for the \name{AliFemtoManager} (large light grey box), thus making the connection between these objects.
610 \label{fig:exampleFirstAnalysisFinish}
615 \includegraphics[width=\textwidth]{ExampleMacro4.pdf}
616 \caption{A second Analysis is instantiated, configured, and added to the collection. The same
617 proceedure is followed as for the fist Analysis (Figures~\ref{fig:exampleFirstAnalysisStart}
618 and~\ref{fig:exampleFirstAnalysisFinish}), though the two Analyses know nothing about each other.
619 \label{fig:exampleSecondAnalysis}
624 \includegraphics[width=\textwidth]{ExampleMacro5.pdf}
625 \caption{Construction of the AliFemto study complete, event looping is trivial. Note that all
626 interaction with the code is through only a few methods of the AliFemtoManager object.
627 \label{fig:exampleEventLoop}
631 Figure~\ref{fig:exampleMacroGload} shows the beginning of the macro.
632 As usual in a root macro, libraries are loaded first. For the femtoscopic analysis itself, only the AliFemto and AliFemtoUser
633 libraries need be loaded. All internal \AliFemto classes such as \name{AliFemtoPair} are found in the AliFemto directory.
634 That directory also has a few simple CorrFcn, Reader, and Cut classes. The user will probably want to start with these and
635 elaborate upon them; in this case, her new classes should go into the AliFemtoUser area.
638 we use the specific \name{AliFemtoEventReader}-derived class \name{AliFemtoEventReaderESD}; not surprisingly, this Reader needs
639 the ESD library loaded as well.
643 Since all Readers are user-written, their configuration
644 methods will be specific to the class used. This is as it should be, since attempts to ``foresee'' all possible
645 uses of the Reader classes will ultimately result in limitations later on, and sloppy work-arounds.
647 The \name{AliFemtoManager} is instantiated; note that its pointer is declared outside the scope of the macro, at the top.
648 Finally, the \name{AliFemtoEventReaderESD} object is ``plugged in'' to the \name{AliFemtoManager}. This is indicated by the arrow
649 in the cartoon; recall that this is not a UML diagram.
651 \subsubsection{Adding Analyses}
652 %--------------------- Example Step 2 ----------------------
655 In Figure~\ref{fig:exampleFirstAnalysisStart} we see construction of a specific Analysis (c.f.
656 Section~\ref{sec:analysisLevel}).
657 An \name{AliFemtoAnalysis}-derived class, \name{AliFemtoVertexAnalysis}, is
658 instantiated. (For reference, this class takes care to ``mix'' only those events close to each other in
659 primary vertex position; it is very commonly used.) All configuration (vertex range, number of bins) takes
660 place in the constructor, in this specific class.
662 The Cuts are (i) instantiated, (ii) configured, and (iii) ``plugged into'' this Analysis.
663 Finally, three correlation functions are instantiated, configured, and added to the collection
664 of CorrFctns for this analysis. (The collection is suggested by the dark-shaded box in the cartoon.)
665 We note that one of the CorrFctn classes there is \name{OpeningAngleCorrFctn}. The fact that its name
666 does not begin with ``AliFemto'' is a clue that this class is user-written, for her own purposes; it would
667 not be included in ALICE nightly builds and would sit in the AliFemtoUser area.
669 Two notes: Firstly, we see that the same AliFemtoTrackCut is used for both the first and second particle-- this
670 is an analysis of identical pions. Secondly, as mentioned in Section~\ref{sec:AliFemtoParticleCuts}, all AliFemtoParticleCuts
671 {\it must} define a particle mass. This is not special to this specific example.
673 %--------------------- Example Step 3 ----------------------
676 In Figure~\ref{fig:exampleFirstAnalysisStart}, the conglomeration of Analysis-related objects is not related to
677 the AliFemtoManager instantiated in the previous Figure. In Figure~\ref{fig:exampleFirstAnalysisFinish}, the connection
678 is made. Firstly, the ``final detail'' for the Analysis is completed-- the number of events to mix for the reference
679 distribution is set, and the now-fully-configured Analysis is added to the collection of Analyses (denoted by the large
682 %--------------------- Example Step 4 ----------------------
685 The structure is now complete in principle-- a useful correlation study may proceed.
686 We may add one or more completely seperate Analyses, if we wish. This is shown in
687 Figure~\ref{fig:exampleSecondAnalysis}. The only points here are that the second
688 (and any subsequent) Analyses are set up similarly to the first one discussed above, and
689 there is no connection the Analyses in the AliFemtoManager's collection of Analyses.
692 \subsubsection{Processing data}
693 \label{sec:ProcessingData}
694 %--------------------- Example Step 5 ----------------------
697 Finally, Figure~\ref{fig:exampleEventLoop} moves beyond construction of the collection
698 of objects, and commands a processing of the data. We note that all ``external'' interaction
699 is with the AliFemtoManager class. If the Reader needs to interact with the ``outside world''
700 (e.g. by opening a file or pointing to a location in memory), then it is up to that specific
701 class, using its own specific methods, to take care of that.
703 In Figure~\ref{fig:exampleEventLoop}, the processing is ordered within a ``pure root'' macro
704 directly. This can be different in other frameworks. For example, in the STAR Maker schema~\cite{StarMaker},
705 the AliFemtoManager Init(), ProcessEvent(), Report() and Finish() methods will be invoked by the AliFemtoMaker
706 Init(), Make(), and Finish() methods. Indeed, the AliFemtoMaker does almost nothing else than perform these
710 \section{Code Organization}
713 \subsection{Directory structure: core and user classes}
716 The femtoscopy analysis effort in ALICE falls in the soft physics working group (PWG2).
717 Thus, when checking out the full \AliRoot from \cvs, it will be found in the {\tt PWG2/FEMTOSCOPY/}
718 area. (One may also check out only PWG2 files using\\
719 {\tt cvs -qz2 -d :pserver:cvs@alisoft.cern.ch:/soft/cvsroot co PWG2}.\\ This is useful if running
720 \AliFemto in ``standalone'' mode.)
722 In this directory are found two subdirectories. The first is {\tt AliFemto/},
723 which holds about 80 classes (as of \today), such as \name{AliFemtoManager}, \name{AliFemtoPair}, etc.
724 It also holds all of the base classes for user-derived code (e.g. \name{AliFemtoCorrFctn}) and one
725 or two simple examples of classes which derive from these (e.g. \name{AliFemtoQinvCorrFctn}). These
726 last might be useful templates for users writing more sophisticated Cuts, CorrFctns, Readers, Analyses, etc.
727 The {\tt AliFemto/} subdirectory is included in the official nightly build. Files there must obey
728 ALICE coding standards, and limited \cvs access is anticipated.
730 The second directory is {\tt AliFemtoUser/}. Files in this subdirectory are not included in the nightly
731 build. This area is meant to be a repository for user code, typically Cuts, CorrFctns, etc, which might
732 be of interest to others working on some analysis. It is \cvs archived, and widespread read/write \cvs access
735 Seperate shared object (.so) libraries are built for the {\tt AliFemto/} and {\tt AliFemtoUser/}
736 area; c.f. the macro snip in Figure~\ref{fig:exampleMacroGload}.
739 \section{Known problems}
741 As of \today, there are no known problems with \AliFemto. However, this Users' Guide is incomplete, in that
742 it does not discuss so-called ``theoretical'' correlation studies covered in the \name{AliFemtoModel*} classes.
743 This will be remedied in the next version of the Users' Guide. In the meantime, see an excellent tutorial
744 on the subject on the ALICE femtoscopy webpage\\
745 {\tt http://aliceinfo.cern.ch/Collaboration/PhysicsWorkingGroups/PWG2/Femtoscopy/}.
751 \part{Reference Manual}
754 The Reference Manual is being finalized.
760 %%%%%%%%\section{References}
761 \begin{thebibliography}{99}
763 \bibitem{UMLreference}
764 The Unified Modeling Language (UML),
765 http://www.omg.org/technology/documents/formal/uml.htm ;
766 http://en.wikipedia.org/wiki/Unified\_Modeling\_Language
768 \bibitem{Lisa:2005dd}
769 M.~A.~Lisa, S.~Pratt, R.~Soltz and U.~Wiedemann,
770 %``Femtoscopy in relativistic heavy ion collisions,''
771 Ann.\ Rev.\ Nucl.\ Part.\ Sci.\ {\bf 55}, 357 (2005)
772 [arXiv:nucl-ex/0505014].
773 %%CITATION = NUCL-EX 0505014;%%
775 \bibitem{HanburyBrown:1954}
776 Hanbury-Brown, R., and Twiss, R.Q.
777 %''A new type of interferometer for use in radio-astronomy'',
778 Phil. Mag. {\bf 45}, 663 (1954).
780 \bibitem{Goldhaber:1960sf}
781 Goldhaber, Gerson and Goldhaber, Sulamith and Lee, Won-Yong
783 %''Influence of Bose-Einstein statistics on the antiproton
784 proton annihilation process''
785 Phys. Rev. {\bf 120} 300 (1960).
787 \bibitem{Lednicky:2002fq}
789 %''Progress in correlation femtoscopy,''
794 %Unfortunately, the best (!?!?) documentation of the basic STAR Maker analysis framework is
795 %a brief presentation by Victor Perevoztchikov which may be found on the STAR computing
797 Tutorial by Victor Perevoztchikov
798 http://www.star.bnl.gov/STAR/comp/train/tut/Maker-in-STAR/Victor-Makers.html
800 \end{thebibliography}
803 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
807 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%