The L\-C\-F\-I Vertex Package provides the vertex finder Z\-V\-T\-O\-P, originally developed for S\-L\-D by D. Jackson \mbox{[}\hyperlink{index_LitList1}{1}\mbox{]}, flavour tagging as well as vertex charge determination for b-\/ and c-\/jets. By default, the flavour tag provided is obtained from the algorithm by R. Hawkings \mbox{[}\hyperlink{index_LitList2}{2}\mbox{]}. It is based on a neural net approach, combining track and vertex information to distinguish b, c-\/ and light jets. The algorithm to determine vertex charge follows the S\-L\-D-\/approach \mbox{[}\hyperlink{index_LitList3}{3}\mbox{]}, with modifications for b-\/jets developed by S. Hillert \mbox{[}\hyperlink{index_LitList4}{4}\mbox{]}.

In addition to the algorithms, the package provides an object-\/oriented framework, in which the default approach can easily be modified and extended. Care was taken to make all main parameters of the code accessible to the user as steering parameters. The code was interfaced to the Marlin\-Reco analysis framework and uses L\-C\-I\-O for input and output, permitting it to be used in conjunction with algorithms from other reconstruction frameworks.

The code was implemented by Ben Jeffery (Z\-V\-T\-O\-P, L\-C\-I\-O/\-Marlin interface, working classes design and testing), Erik Devetak (Flavour tag inputs calculation and testing, M\-C Jet flavour, Vertex Charge Processor), Mark Grimes (Flavour tag procedure, Vertex fitter), Dave Bailey (neural network code), Victoria Martin (A\-I\-D\-A Plot Processor), Tomas Lastovicka (Kalman filter for vertex fitting), Kristian Harder (use G\-E\-A\-R-\/geometry for suppression of hadronic interactions, Purity -\/ Efficiency macro) and Sonja Hillert (coordination, system test). The authors thank the L\-C\-F\-I physics group for help and advice during the development phase, in particular D. Jackson (advice on Z\-V\-T\-O\-P), K. Harder(testing, Mokka/\-Gear interface) V. Martin (test of vertex charge procedure for c-\/jets), T. Lastovicka (testing), R. Walsh (testing), Clare Lynch (testing).

We would also like to thank F. Gaede, T. Behnke and N. Graf for fruitful discussions, D. Martsch for producing a test sample on the G\-R\-I\-D and A. Raspereza for advice and for extending the track cheater functionality to provide the input required by the Vertex Package.


\begin{DoxyImage}
\includegraphics[width=\textwidth]{VtxPackageDirStruct}
\caption{Vertex Package directory structure}
\end{DoxyImage}


Directories of the package are organised as follows\-: the top-\/level directories contain the Marlin processors (src) and the include-\/ and steering files they require, as well as macros (macro) that can be run on output created by some of the processors. For example, a root macro is provided to make comparison plots of purity vs efficiency obtained from two subsequent runs of the \hyperlink{classPlotProcessor}{Plot\-Processor}. (Note, that the package provides root output only if compiled with root option). The top-\/level directories provide an interface to the main part of the code, which is located in the directory vertex\-\_\-lcfi. The Marlin processors access a set of algorithm classes for Z\-V\-T\-O\-P, flavour tag and vertex charge calculation which can be found in the subdirectory algo. These algorithm classes all inherit from a simple interface Algo, providing parameters and the method \char`\"{}calculate\-For\char`\"{}, returning the output of the algorithm. Input to the algorithm classes are objects like jets or events. The implementation of these object classes can be found in the directories vertex\-\_\-lcfi/inc and vertex\-\_\-lcfi/src. Working classes specific to the vertex finder Z\-V\-T\-O\-P, providing functionality like vertex finding, vertex resolving and vertex fitting, are located in the directory vertex\-\_\-lcfi/zvtop. The neural network code is kept in the directory vertex\-\_\-lcfi/nnet.

The following Marlin processors are provided\-: 
\begin{DoxyItemize}
\item \hyperlink{classTrueAngularJetFlavourProcessor}{True\-Angular\-Jet\-Flavour\-Processor}\-: provides the true jet flavour using M\-C information  
\item \hyperlink{classPerEventIPFitterProcessor}{Per\-Event\-I\-P\-Fitter\-Processor}\-: determines the event vertex (I\-P) 
\item \hyperlink{classRPCutProcessor}{R\-P\-Cut\-Processor}\-: flexible processor for applying various track selection cuts  
\item \hyperlink{classZVTOPZVRESProcessor}{Z\-V\-T\-O\-P\-Z\-V\-R\-E\-S\-Processor}\-: find vertices running the Z\-V\-R\-E\-S branch of Z\-V\-T\-O\-P  
\item \hyperlink{classZVTOPZVKINProcessor}{Z\-V\-T\-O\-P\-Z\-V\-K\-I\-N\-Processor}\-: find vertices running the Z\-V\-K\-I\-N branch of Z\-V\-T\-O\-P (ghost track algorithm)  
\item \hyperlink{classFlavourTagInputsProcessor}{Flavour\-Tag\-Inputs\-Processor}\-: calculate input variables for the flavour tag neural net and the vertex charge  
\item \hyperlink{classNeuralNetTrainerProcessor}{Neural\-Net\-Trainer\-Processor}\-: train neural networks for flavour tag  
\item \hyperlink{classFlavourTagProcessor}{Flavour\-Tag\-Processor}\-: use pretrained neural nets to obtain flavour tag  
\item \hyperlink{classVertexChargeProcessor}{Vertex\-Charge\-Processor}\-: calculate vertex charge for b-\/ and/or c-\/jets  
\item \hyperlink{classPlotProcessor}{Plot\-Processor}\-: calculate purity and efficiency and produce performance plot (if compiled with root)  
\item \hyperlink{classLCFIAIDAPlotProcessor}{L\-C\-F\-I\-A\-I\-D\-A\-Plot\-Processor}\-: diagnostic plots and tables for flavour tag inputs and outputs  
\end{DoxyItemize}

The example steering files provided show how the package could be run in a typical analysis. The order in which the steering files would be called is as follows\-: 
\begin{DoxyItemize}
\item \href{../cheattracks+jetfind.xmlsteer}{\tt cheattracks+jetfind.xml} -\/ note that hit collection names in this file are geometry specific, the default detector geometry assumed in this example file is L\-D\-C01\-\_\-05\-Sc. 
\item \href{../truejetflavour.xmlsteer}{\tt truejetflavour.\-xml} 
\item \href{../ipfit.xmlsteer}{\tt ipfit.\-xml} 
\item \href{../zvres.xmlsteer}{\tt zvres.\-xml} 
\item \href{../fti.xmlsteer}{\tt fti.\-xml} 
\item \href{../trainNeuralNets.xmlsteer}{\tt train\-Neural\-Nets.\-xml} (optional, only needed for special training run to obain new flavour tag neural nets) 
\item \href{../ft.xmlsteer}{\tt ft.\-xml} 
\item \href{../Bvertexcharge.xmlsteer}{\tt Bvertexcharge.\-xml} 
\item \href{../Cvertexcharge.xmlsteer}{\tt Cvertexcharge.\-xml} 
\item \href{../ftplot.xmlsteer}{\tt ftplot.\-xml} 
\end{DoxyItemize}

The first of these steering files calls event reconstruction processors from Marlin\-Reco that are not part of the package but need to be run in order to obtain the collections required. Running Marlin with this steering file creates an input L\-C\-I\-O file for the package, by default called cheatout.\-slcio. It contains collections with M\-C particles, jets and the Reconstructed\-Particles within the jets. The execution flow diagram shows how these collections are used by the L\-C\-F\-I\-Vertex package, as well as processors used and collections created if using the example steering files above. (The training of new neural nets is not covered in the diagram, as this would be done in a dedicated training run; the typical application uses networks that have already been trained). Unless otherwise indicated, all collections shown in the diagram are of type Reconstructed\-Particle.


\begin{DoxyImage}
\includegraphics[width=\textwidth]{VertexPackageExeFlow}
\caption{Vertex Package execution flow obtained from the example steering files}
\end{DoxyImage}


Some processors depend on others to have run before, e.\-g. Z\-V\-T\-O\-P and the flavour tag inputs processor each require their own track selection implemented by the \hyperlink{classRPCutProcessor}{R\-P\-Cut\-Processor}. Further details are provided in the documentation for each of the processors (see above) and in the \hyperlink{Tutorials}{tutorial section}. Information on the internal Z\-V\-T\-O\-P classes can be found in the \hyperlink{ZVTOP}{Z\-V\-T\-O\-P documentation}. Scope and usage of the neural network code (which can also be used for purposes other than flavour tagging) is described in the \hyperlink{NeuralNet}{neural net documentation}.

In addition to code and example steering files, the package provides a set of pre-\/trained networks for the Hawkings default flavour tag. These have been trained using the fast M\-C S\-G\-V and are located in a new repository {\bfseries  tagnet } in the \href{http://www-zeuthen.desy.de/linear_collider/}{\tt Zeuthen C\-V\-S repository} (Use 'tagnet' as project name when checking out the directory). {\bfseries We strongly recommend submitting any new networks that users train with different boundary conditions to this directory along with a detailed description of training conditions. } A form for providing training information can be found in the same directory in order to make I\-L\-C physics studies more transparent and ease comparisons of analyses performed within different groups, frameworks or detector concepts.\par
\par


{\bfseries  Summary of changes in release versions\-: } 
\begin{DoxyItemize}
\item v00-\/02-\/01 
\end{DoxyItemize}

\label{index_LitList1}%
\hypertarget{index_LitList1}{}%
\mbox{[}1\mbox{]} D. Jackson, N\-I\-M A 388 (1997) 247\par
 \label{index_LitList2}%
\hypertarget{index_LitList2}{}%
\mbox{[}2\mbox{]} R. Hawkings, L\-C-\/\-P\-H\-S\-M-\/2000-\/021\par
 \label{index_LitList3}%
\hypertarget{index_LitList3}{}%
\mbox{[}3\mbox{]} J. Thom, S\-L\-A\-C-\/\-R-\/585 (2002), T. Wright, S\-L\-A\-C-\/\-R-\/602 (2002) \par
 \label{index_LitList4}%
\hypertarget{index_LitList4}{}%
\mbox{[}4\mbox{]} S. Hillert, proceedings L\-C\-W\-S 2005\par


In case of comments or questions {\bfseries  not answered by the documentation } please contact the development and maintenance team\-:

Erik Devetak (\href{mailto:E.Devetak1@physics.ox.ac.uk}{\tt E.\-Devetak1@physics.\-ox.\-ac.\-uk})\par
 Mark Grimes (\href{mailto:Mark.Grimes@bristol.ac.uk}{\tt Mark.\-Grimes@bristol.\-ac.\-uk})\par
 Kristian Harder (\href{mailto:K.Harder@rl.ac.uk}{\tt K.\-Harder@rl.\-ac.\-uk})\par
 Sonja Hillert (\href{mailto:S.Hillert1@physics.ox.ac.uk}{\tt S.\-Hillert1@physics.\-ox.\-ac.\-uk})\par
 Talini Pinto Jayawardena (\href{mailto:T.S.Pinto.Jayawardena@rl.ac.uk}{\tt T.\-S.\-Pinto.\-Jayawardena@rl.\-ac.\-uk})\par
 Ben Jeffery (\href{mailto:B.Jeffery1@physics.ox.ac.uk}{\tt B.\-Jeffery1@physics.\-ox.\-ac.\-uk})\par
 Tomas Lastovicka (\href{mailto:T.Lastovicka1@physics.ox.ac.uk}{\tt T.\-Lastovicka1@physics.\-ox.\-ac.\-uk})\par
 Clare Lynch (\href{mailto:Clare.Lynch@bristol.ac.uk}{\tt Clare.\-Lynch@bristol.\-ac.\-uk})\par
 Victoria Martin (\href{mailto:victoria.martin@ed.ac.uk}{\tt victoria.\-martin@ed.\-ac.\-uk})\par
 Roberval Walsh (\href{mailto:r.walsh@ed.ac.uk}{\tt r.\-walsh@ed.\-ac.\-uk})\par
 