Back to home page

EIC code displayed by LXR

 
 

    


Warning, /DD4hep/doc/usermanuals/DDRec/DDRecManual.tex is written in an unsupported language. File is not indexed.

0001 %=============================================================================
0002 \documentclass[10pt,a4paper]{article}
0003 %
0004 \input{./setup/DD4hep-setup.tex}
0005 \input{./setup/AIDA2020-setup.tex}
0006 %
0007 \pagestyle{fancyplain}{\fancyfoot[C]{\sffamily{DDRec User Manual}}}
0008 %
0009 \usepackage{amsmath}
0010 \graphicspath{{./figs/}}
0011 \begin{document}   
0012 %
0013 \mytitle{
0014 DDRec
0015 }{
0016 Reconstruction Interface for the \\
0017 \vspace{0.5cm}
0018 DD4hep Geometry Description \\
0019 \vspace{0.5cm}
0020 Toolkit
0021 \vspace{2cm}
0022 }{
0023 %M.Frank%\textsuperscript{1},
0024 F.Gaede%\textsuperscript{2},
0025 %C.Grefe\textsuperscript{1},
0026 %P.Mato\textsuperscript{1}
0027 
0028 %{\textsuperscript{1} 
0029 {CERN, 1211 Geneva 23, Switzerland}
0030 
0031 %{\textsuperscript{2} 
0032 {Desy, 22607 Hamburg, Germany}
0033 }
0034 %
0035 %
0036 %==  Abstract  ===============================================================
0037 \pagestyle{plain}
0038 \pagenumbering{Roman}
0039 \setcounter{page}{1}
0040 \begin{abstract}
0041 %=============================================================================
0042 
0043 \noindent
0044 \normalsize
0045 The reconstruction of particle tracks and clusters in an High Energy Physics detector
0046 requires information about the geometrical and material properties of the various 
0047 tracking and calorimeter subdetectors.
0048 In general, a higher level view on the detector geometry is needed than for the purpose
0049 of simulating the detailed detector response with tools such as Geant4\cite{bib:geant4}.
0050 This higher level view typically involves the abstraction of detector layers, the corresponding
0051 measurement surfaces, accumulation of dead material along a path and conversion between cellIDs and 
0052 positions.
0053 While in principle it is of course possible to extract this information from the detailed 
0054 detector geometry model used for simulation, doing so would tightly couple the reconstruction
0055 code to the specific implementation of the simulation model. 
0056 \DDR provides a generalized API for reconstruction that can be used to decouple the details of 
0057 the \DDH\cite{bib:DD4hep} detector geometry model from the reconstruction algorithms.
0058  
0059 \end{abstract}
0060 
0061 \vspace{8cm}
0062 
0063 \begin{center}
0064 {\large{\bf{
0065 \begin{tabular} {| l | l | l |}
0066 \hline
0067 \multicolumn{3}{| c |}{} \\[0.2cm]
0068 \multicolumn{3}{| c |}{Document History} \\[0.2cm]
0069 \multicolumn{3}{| c |}{} \\[0.2cm]
0070 \hline
0071                  &      &        \\
0072 Document         &      &        \\
0073 version          & Date & Author \\[0.2cm] \hline
0074                  &      &        \\
0075 1.0              & 11/11/2014 & Frank Gaede CERN/DESY  \\
0076                  &      &        \\        \hline 
0077 \end{tabular}
0078 }}}
0079 \end{center}
0080 
0081 \clearpage
0082 %
0083 %
0084 %==  TOC  ====================================================================
0085 \tableofcontents
0086 \clearpage
0087 %
0088 %
0089 %=============================================================================
0090 % Manual
0091 %=============================================================================
0092 \pagenumbering{arabic}
0093 \setcounter{page}{1}
0094 
0095 %=============================================================================
0096 \section{Introduction}
0097 \label{sec:ddrec-manual-introduction}
0098 %=============================================================================
0099 \noindent
0100 This manual introduces the \DDR package which is part of \DDH and provides the 
0101 high level view on the HEP detector geometry that is needed during reconstruction and 
0102 analysis. 
0103 In the detailed simulation of the response of a typical High Energy Physics detector
0104 very little information is needed in principle on the actual structure of the material
0105 distribution in the detector. This becomes obvious if one considers the fact that
0106 the Geant4 program is also used in medical applications where the human body 
0107 is approximated by a voxelised phantom.
0108 During the reconstruction of particle trajectories and calorimeter clusters, in particular 
0109 in the phase of pattern recognition, one typically regards the detector as an abstract
0110 structure of measurement surfaces or volumes that generally follow a layering structure.
0111 \DDR contains an API that provides this information for reconstruction algorithms, thereby
0112 decoupling the details of the actual simulation model used from the reconstruction code.
0113 \noindent
0114 The \DDR API provides the following functionality:
0115 
0116 \begin{itemize}\itemcompact
0117 \item description of measurement surfaces with coordinate systems for 
0118   track finding and fitting
0119 \item description of non-active surfaces with material properties in
0120   order to take effects of multiple scattering and energy loss
0121   into account
0122 \item conversion of cellIDs assigned to simulated tracker and calorimeter hits
0123   to positions of readout cells and vice versa
0124 \item access to a list of materials between any two points inside the world
0125   volume of the detector
0126 \item access to the materials at any given point or along a straight line between two points
0127 \item averaged material properties for a list of materials
0128 \item computation of radiation and interaction lengths for detector layers, modules
0129   or arbitrary sections through the detector
0130 \end{itemize}
0131 
0132 \noindent
0133 In this manual we describe the different classes in \DDR and how they should be
0134 used in the detector geometry constructors as well as in the reconstruction
0135 code. 
0136 
0137 \subsection*{Doxygen code documentation}
0138 Please also refer to the code documentation that is created with doxygen for more
0139 details on the classes and their members. This documentation can be build with:
0140 
0141 \begin{unnumberedcode} 
0142    cmake -D INSTALL_DOC=ON ${path_to_dd4hep_source}
0143    make install
0144 \end{unnumberedcode}
0145 
0146 \noindent
0147 and will then be available at
0148 \begin{unnumberedcode} 
0149    ${DD4hepINSTALL}/doc/html/index.html
0150 \end{unnumberedcode}
0151 
0152 %=============================================================================
0153 \section{Surfaces}
0154 \label{sec:ddrec-manual-surfaces}
0155 %=============================================================================
0156 For fitting the trajectories of charged particle tracks one generally needs to know 
0157 the measurement surfaces on which the hits where deposited. Additionally the material 
0158 properties along the trajectory need to be known in order to correct for effects
0159 from multiple scattering and energy loss. 
0160 \DDR provides an abstract interface for surfaces and materials in the namespace
0161 {\em DDSurfaces} and a concrete implementation, described below, in the namespace
0162 {\em DDRec}. This is done in order to separate interface and implementation and allow
0163 other software tools, e.g. tracking packages to just use the interface.
0164  
0165 %=============================================================================
0166 \subsection{namespace DDSurfaces}
0167 \label{subsec:ddrec-ddsurfaces}
0168 %=============================================================================
0169 The basic concept of surfaces in \DDR is expressed with the two main interfaces
0170 {\em ISurface} and {\em IMaterial}. They are shown together with helper classes in
0171 the {\em DDSurfaces} in figure:\ref{fig:ddrec_ddsurfaces_classes}
0172 and are briefly described in the following.
0173 
0174 \begin{figure}[h]
0175   \begin{center}
0176     \includegraphics[width=120mm] {DDRec_ISurface_classes}
0177     \caption{Classes in namespace DDSurfaces: abstract interfaces {\em ISurface, IMaterial, ICylinder}
0178       and helper classes {\em Vector3D, ISurface::Vector2D, SurfaceType}. }
0179     \label{fig:ddrec_ddsurfaces_classes}
0180   \end{center}
0181 \end{figure}
0182 
0183 \noindent{\em \bf ISurface}: Defines the surface by means of an origin, a normal vector n and two, 
0184 typically orthogonal, direction vectors u and v, where all of the vectors n,u,v might depend 
0185 on the actual position on (or close to) the surface. In order to describe material properties
0186 two thicknesses are assigned to the surface - one in direction of the normal vector (outerThickness) 
0187 and one in the opposite direction (innerThickness). There are two materials assigned to these
0188 thicknesses, where these materials could be averaged along the normal and thickness.
0189 The method {\em isInsideBounds} allows in principle to implement arbitrary bounds for the surface.
0190 Two methods allow the conversion between global 3d coordinates (on the surface) and local 2d coordinates 
0191 in the coordinate system of the surface.
0192  
0193 \noindent
0194 {\em \bf IMaterial}: Interface to describe the relevant material properties: atomic number and weight, 
0195 density and radiation- and interaction lengths. These can be real materials or averaged materials along
0196 a given direction and length (thickness assigned to the surface).
0197 
0198 \noindent
0199 {\em \bf ICylinder}: Simple interface for cylindrical surfaces adding the cyliner radius to a surface
0200 through multiple inheritance.
0201 
0202 \noindent
0203 {\em \bf ISurface::Vector2D} Helper struct inside ISurface for 2d vectors with coordinates u and v.
0204 
0205 \noindent
0206 {\em \bf Vector3D}: Generic 3d vector class with cartesian coordinates x,y,z that allows initialization
0207 from other 3d vector implementations or using cylindircal or spherical coordinates. Provides acces to
0208 quantities often needed, such as magnitude, transversal component, representation in non-cartesian
0209 coordinates.
0210 
0211 \noindent
0212 {\em \bf SurfaceType}: Helper class using an {\em std::bitfield<32>} to encode the 
0213 following properties of the surface: {\em isCylinder, isPlane, isSensitive, isHelper} (dead material),
0214 {\em isParallelToZ, isOrthogonalToZ, isInvisible, isMeasurement1D}.
0215 
0216 %=============================================================================
0217 \subsection{Surface implementation}
0218 \label{subsec:ddrec-ddsurfaces}
0219 %=============================================================================
0220 \DDR provides classes that implement the interface defined in {\em DDSurfaces}.
0221 The main classes for implementing {\em ISurface} are shown in 
0222 figure \ref{fig:ddrec_surfaces_classes}.
0223 
0224 \begin{figure}[h]
0225   \begin{center}
0226     \includegraphics[width=100mm] {DDRec_surface_classes}
0227     \caption{Class diagram with the main classes describing detector
0228       surfaces and their relations.}
0229     \label{fig:ddrec_surfaces_classes}
0230   \end{center}
0231 \end{figure}
0232 
0233 \noindent
0234 The implementation of the surfaces in \DDR is done in two parallel hierarchies 
0235 of implementation classes. The first hierarchy is based on the {\em VolSurface}
0236 class which connects a surface with its surrounding volume.
0237 This volume then provide the boundaries of the surface and gives access to 
0238 the local to global coordinate transformations inside the coordinate system
0239 of the volume. There are currently two concrete implementations: 
0240 {\em VolCylinder} and {\em VolPlane} that can be used in the detector construction
0241 code as described in\ref{subsec:ddrec-surfaces-constructors}.
0242 The second hierarchy is the actual implementation of the surface concept in \DDR
0243 to be used by reconstruction code as described in \ref{subsec:ddrec-surfaces-reconstruction}.
0244 It uses the extension and views concept described in the main \DDH manual\cite{bib:DD4hepManual}.
0245 The {\em Surface} class has a {\em VolSurface} object and a {\em DetElement} and 
0246 uses these to establish the local to global coordinate transforms, the surface boundaries
0247 and the material properties. The materials on both sides of the surface are
0248 the averaged materials along the direction of the normal with the given thicknesses.
0249 It is thus possible to also take material effects into account for materials
0250 that lay outside of the actual volume the surface is attached to.
0251 This is in particular useful for compound materials that consist of a larger number
0252 of thin slices.
0253 
0254 %=============================================================================
0255 \subsection{Using surfaces in geometry constructors}
0256 \label{subsec:ddrec-surfaces-constructors}
0257 %=============================================================================
0258 The surfaces that should be available in the reconstruction code, 
0259 have to be assigned to their corresponding volume and detector element by the 
0260 user in the detector geometry construction code. 
0261 This is done by specifying the coordinate system
0262 and orientation of the surface inside the volume with vectors o,n,u and v 
0263 and then instantiating one of the two types {\em VolCylinder} or {\em VolPlane} for a 
0264 given volume.
0265 After the placement of the corresponding DetElement, the surface is added to the
0266 list of surfaces for this DetElement.
0267 
0268 \noindent
0269 This is demonstrated in the  following example code:
0270 
0271 \begin{code}
0272   #include "DDRec/Surface.h"
0273   //...
0274   // base vectors for surfaces:
0275   DDSurfaces::Vector3D o(0,0,0) ;
0276   DDSurfaces::Vector3D u(1,0,0) ;
0277   DDSurfaces::Vector3D v(0,1,0) ;
0278   DDSurfaces::Vector3D n(0,0,1) ;
0279 
0280   // --- loop over layers ----
0281   // ...
0282 
0283     DD4hep::Geometry::Box  box( dimX/2, dimY/2, dimZ/2 ) ;
0284     DD4hep::Geometry::Volume vol( volumeName, lcdd.material( x_layer.materialStr() )) ;
0285 
0286     DD4hep::Geometry::DetElement layerDetElement( parentDetElement , "layer"+_toString(i,"_%02d") , det_id ) ;
0287 
0288     // add a measurement surface to the layer for every sensitive slice:
0289 
0290     DD4hep::DDRec::VolPlane surf( vol , 
0291                           DDSurfaces::SurfaceType(DDSurfaces::SurfaceType::Sensitive),
0292                           dimZ, dimZ, 
0293                           u, v, n , o ) ; 
0294 
0295     // place the layer
0296     DD4hep::Geometry::PlacedVolume pv = parentVol.placeVolume(  vol, layerPlacement );
0297 
0298     layerDetElement.setPlacement( pv ) ;
0299 
0300     DD4hep::DDRec::volSurfaceList( layerDetElement )->push_back( surf ) ;
0301 
0302   // --- end loop over layers ----
0303 
0304 \end{code}
0305 In this example a planar ({\em VolPlane}) measurement ({\em SurfaceType(Sensitive)})
0306 surface is attached to the box volume of a detector layer.
0307 The thickness of the surface corresponds to that of the box and is given by its half length in z
0308 ( Vector3D n(0,0,1) runs along z). Thus the surface is completely contained in 
0309 the box and no averaging of materials will be done, unless additional volumes
0310 are placed inside the box at a later stage. 
0311 The origin of the coordinate system of the surface coinsides with that of the box
0312 ({\em Vector3D o(0,0,0); })
0313 and the two measurememnt directions u,v run along the x and y axis of the box
0314 respectively.
0315 
0316 \noindent
0317 The following code snipped shows the creation of a cylindrical surface attached
0318 to a tube volume for the inner field cage of a tpc. The radius of the cylindrical
0319 surface is given by the transversal component of the origin vector {\em ocyl}.
0320 The volume {\em innerWallVol} is filled with air and will be later populated
0321 with slices of a compound material, thus the material properties will be
0322 averaged along the thickness of the tube.
0323 
0324 \begin{code}
0325   //...
0326   DD4hep::Geometry::Tube innerWallSolid(rInner ,rInner + dr_InnerWall ,dz_Wall / 2.0 ) ;
0327 
0328   DD4hep::Geometry::Volume innerWallVol( "TPCInnerWallVol", innerWallSolid, materialAir ) ; 
0329 
0330   pv = tpc_motherLog.placeVolume( innerWallVol ) ;
0331 
0332   DDSurfaces::Vector3D ocyl(  rInner + 0.5*dr_InnerWall , 0. , 0. ) ;
0333 
0334   DD4hep::DDRec::VolCylinder surfI( innerWallVol , 
0335                                     SurfaceType( SurfaceType::Helper ) ,
0336                                     0.5*dr_InnerWall, 0.5*dr_InnerWall, 
0337                                     ocyl ) ;
0338 
0339   volSurfaceList( tpc )->push_back(  surfI ) ;
0340   //...
0341 \end{code}
0342 
0343 
0344 
0345 
0346 %=============================================================================
0347 \subsection{Using surfaces in reconstruction code}
0348 \label{subsec:ddrec-surfaces-reconstruction}
0349 %=============================================================================
0350 Accessing and using the surfaces in reconstruction code is very easy. 
0351 There are two possibilities to access the surfaces:
0352 \begin{itemize}
0353 \item use the {\em DetectorSurfaces} view class to get a list of 
0354  all surfaces that have been assigned to a particular {\em DetElement}
0355  object.
0356 \item or use the {\em SurfaceManager} class to get a list of all
0357  surfaces of a given {\em DetElement} and all its daughters.
0358 \end{itemize}
0359 
0360 \noindent
0361 The following code snippet uses the {\em SurfaceManager}, initialized
0362 with the world  {\em DetElement}, to get a list of all surfaces 
0363 defined for a given detector model.
0364 The surfaces are then printed to {\em std::cout} and filled 
0365 into a map, using the surfaces ID as a key.
0366 For sensitive surfaces, attached to sensitive volumes, the ID
0367 will be that of the sensitve volume and thus such a map provides
0368 a very easy lookup from the hitID to its corresponding measurement
0369 surface.
0370 
0371 \begin{code}
0372   // ...
0373 
0374   DD4hep::Geometry::LCDD& lcdd = DD4hep::Geometry::LCDD::getInstance();
0375 
0376   lcdd.fromCompact( inFile );
0377 
0378   DD4hep::Geometry::DetElement world = lcdd.world() ;
0379 
0380   // create a list of all surfaces in the detector:
0381   DD4hep::DDRec::SurfaceManager surfMan(  world ) ;
0382 
0383   const DD4hep::DDRec::SurfaceList& sL = surfMan.surfaceList() ;
0384 
0385   // map of surfaces
0386   std::map< long64, DD4hep::DDRec::Surface* > surfMap ;
0387 
0388   for( DD4hep::DDRec::SurfaceList::const_iterator it = sL.begin() ; it != sL.end() ; ++it ){
0389     
0390     DD4hep::DDRec::Surface* surf =  *it ;
0391     
0392     std::cout << " ------------------------- " 
0393               << " surface: "  << *surf         << std::endl
0394               << " ------------------------- "  << std::endl ;
0395     
0396     surfMap[ surf->id() ] = surf ;
0397   }
0398 
0399 \end{code}
0400 
0401 \noindent
0402 And similarily this code uses the {\em DetectorSurfaces} class to just access the surfaces 
0403 for a particular detector element:
0404 
0405 \begin{code}
0406   // ...
0407 
0408   DD4hep::Geometry::DetElement ladderDE = lcdd.detector("VXD_layer02_ladder42") ;
0409 
0410   // create surfaces
0411   DD4hep::DDRec::DetectorSurfaces ds( ladderDE ) ;
0412 
0413   const DD4hep::DDRec::SurfaceList& detSL = ds.surfaceList() ;
0414 
0415   for( DD4hep::DDRec::SurfaceList::const_iterator it = detSL.begin() ; it != detSL.end() ; ++it ){
0416 
0417     DD4hep::DDRec::Surface* surf =  *it ;
0418 
0419     std::cout << " ------------------------- " 
0420               << " surface: "  << *surf         << std::endl
0421               << " ------------------------- "  << std::endl ;
0422   }
0423 \end{code}
0424 
0425 %=============================================================================
0426 \subsection{Visualizing detector surfaces}
0427 \label{subsec:ddrec-surfaces-visualization}
0428 %=============================================================================
0429 
0430 The detector surfaces and the vectors defining their coordinate system can be
0431 visualized with the program {\em teveDisplay} that is part of \DDH. In a future
0432 version of \DDH this visualization might be included in \DDE.
0433 Currently a full 3d view of the detector surfaces as well as a $\rho-\phi$-view
0434 and a $\rho$-z view are available. See figure~\ref{fig:ddrec_surfaces_visualization}.
0435 
0436 \begin{figure}[h]
0437   \begin{center}
0438     \includegraphics[width=0.48\hsize]{DDRec_rhoz_surfaces} \includegraphics[width=0.48\hsize]{DDRec_inner_tracking_surfaces}
0439     \caption{Example of surface visualization. Left: $\rho$-z view of the tracking surfaces in the ILD detector, Right: 3D view of the 
0440     surfaces in the inner tracking detectors in ILD.}
0441     \label{fig:ddrec_surfaces_visualization}
0442   \end{center}
0443 \end{figure}
0444  
0445 
0446 
0447 %=============================================================================
0448 \section{Materials}
0449 \label{sec:ddrec-manual-materials}
0450 %=============================================================================
0451 The surfaces classes described above provide a way that allows to
0452 augment a detector geometry description with a high level view on the detector
0453 that should be sufficient for most reconstruction tasks, such as pattern
0454 recognition, track fitting and calorimeter reconstruction as in a particle 
0455 flow algorithm. However they require that care has been taken to assign all
0456 relevant surfaces with corresponding thicknesses to the volumes and detector
0457 elements. For cases where this is not possible or where other reconstruction
0458 geometries should be instantiated, \DDR provides the possibility to access
0459 the materials at any given point in the world volume of the detector or 
0460 to retrieve a list of materials along a straight line between any two points.
0461 
0462 \noindent
0463 This is done with the class {\em MaterialManager}, which also allows to
0464 create an averaged material for a list of materials ({\em MaterialVector}).
0465 The usage of this class is simple and best demonstrated with an example:
0466 
0467 \begin{code}
0468 
0469   DD4hep::Geometry::LCDD& lcdd = DD4hep::Geometry::LCDD::getInstance();
0470 
0471   lcdd.fromCompact( inFile );
0472 
0473   DDSurfaces::Vector3D p0( x0, y0, z0 ) ;
0474   DDSurfaces::Vector3D p1( x1, y1, z1 ) ;
0475 
0476   DD4hep::DDRec::MaterialManager matMgr ;
0477 
0478   const DD4hep::DDRec::MaterialVec& materials = matMgr.materialsBetween( p0 , p1  ) ;
0479         
0480   std::cout  << std::endl  
0481              << " #######  materials between the two  points : " 
0482              << p0 << "*cm  and " << p1 << "*cm :  "  
0483              << std::endl ;
0484 
0485   double sum_x0 = 0 ;
0486   double sum_lambda = 0 ;
0487   double path_length = 0 ;
0488   for( unsigned i=0,n=materials.size();i<n;++i){
0489 
0490     DD4hep::DDRec::Material mat =  materials[i].first  ;
0491     double length = materials[i].second  ;
0492 
0493     double nx0 = length / mat.radLength()  ;
0494     sum_x0 += nx0 ;
0495 
0496     double nLambda = length / mat.intLength()  ;
0497     sum_lambda += nLambda ;
0498 
0499     path_length += length ;
0500 
0501     std::cout << "      "               << mat 
0502               << " thickness: "         << length 
0503               << " path_length:"        << path_length
0504               << " integrated_X0: "     << sum_x0 
0505               << " integrated_lambda: " << sum_lambda 
0506               <<  std::endl ;
0507   }
0508 
0509 \end{code}
0510 
0511 \noindent
0512 Creation of an averaged material:
0513 
0514 \begin{code}
0515   // ...
0516   const DD4hep::DDRec::MaterialVec& materials = matMgr.materialsBetween( p0 , p1  ) ;
0517         
0518   const DD4hep::DDRec::MaterialData& avMat = matMgr.createAveragedMaterial( materials ) ;
0519 
0520   std::cout << " averaged Material : " << " Z: " << avMat.Z() << " A: " << avMat.A() 
0521             << " densitiy: "           << avMat.density()
0522             << " radiationLength: "    << avMat.radiationLength() 
0523             << " interactionLength: "  << avMat.interactionLength()  
0524             << std::endl ;
0525 \end{code}
0526 
0527 \noindent
0528 There is a utility program {\em print\_materials} that can be used to debug detector
0529 geometries:
0530 
0531 \begin{verbatim}
0532  $ print_materials
0533  usage: print_materials compact.xml x0 y0 z0 x1 y1 z1
0534         -> prints the materials on a straight line between the two given points ( unit is cm)
0535 \end{verbatim}
0536 
0537 
0538 \noindent
0539 {\bf Note: accessing the materials using the {\em MaterialManager} is a rather
0540 costly operation and should only be done at the initialization phase 
0541 of a reconstruction program for caching material properties !}
0542 
0543 
0544 
0545 %=============================================================================
0546 \section{IDDecoder}
0547 \label{sec:ddrec-manual-iddecoder}
0548 %=============================================================================
0549 Sensitive volumes in a \DDH geometry model are assigned a unique volume-ID. 
0550 This ID is then used by the corresponding {\em DDSegmentation} object
0551 to create a unique cellID for tracker and calorimeter hits, allowing
0552 to uniquely match hits to their sensitive volumes and also to their
0553 {\em DetElements} if they have been defined appropriately.
0554 During reconstruction tasks, including digitization of simulated hits,
0555 one often needs to convert between a cellID assigned to the hit and 
0556 the position of the corresponding detector cell. 
0557 For example one could write out simulated calorimeter hits without position
0558 information in order to save disk space and retrieve the position information
0559 based on the cellID. Another application might be a clustering algorithm
0560 where one looks for hits in the neighbor cells of a given hit.
0561 
0562 \noindent
0563 The functionality to do this is provided by the {\em IDDecoder} class with
0564 the following interface:
0565 
0566 \begin{code}
0567   class IDDecoder {
0568   public:
0569      /// Default constructor using the name of the corresponding readout collection
0570     IDDecoder(const std::string& collectionName);
0571     
0572      /// Default constructor using a readout object
0573     IDDecoder(const Geometry::Readout& readout);
0574     
0575      /// Destructor
0576     virtual ~IDDecoder();
0577     
0578      /// Returns the cell ID from the local position in the given volume ID.
0579     CellID cellIDFromLocal(const Geometry::Position& local, const VolumeID volumeID) const;
0580     
0581      /// Returns the global cell ID from a given global position
0582     CellID cellID(const Geometry::Position& global) const;
0583     
0584      /// Returns the global position from a given cell ID
0585     Geometry::Position position(const CellID& cellID) const;
0586     
0587      /// Returns the local position from a given cell ID
0588     Geometry::Position localPosition(const CellID& cellID) const;
0589     
0590      /// Returns the volume ID of a given cell ID
0591     VolumeID volumeID(const CellID& cellID) const;
0592     
0593      /// Returns the volume ID of a given global position
0594     VolumeID volumeID(const Geometry::Position& global) const;
0595     
0596      /// Returns the placement for a given cell ID
0597     Geometry::PlacedVolume placement(const CellID& cellID) const;
0598     
0599      /// Returns the placement for a given global position
0600     Geometry::PlacedVolume placement(const Geometry::Position& global) const;
0601     
0602      /// Returns the subdetector for a given cell ID
0603     Geometry::DetElement subDetector(const CellID& cellID) const;
0604     
0605      /// Returns the subdetector for a given global position
0606     Geometry::DetElement subDetector(const Geometry::Position& global) const;
0607     
0608      /// Returns the closest detector element in the hierarchy for a given cell ID
0609     Geometry::DetElement detectorElement(const CellID& cellID) const;
0610     
0611      /// Returns the closest detector element in the hierarchy for a given global position
0612     Geometry::DetElement detectorElement(const Geometry::Position& global) const;
0613     
0614      /// Calculates the neighbours of the given cell ID and adds them to the list of neighbours
0615     void neighbours(const CellID& cellID, std::set<CellID>& neighbours) const;
0616     
0617      /// Checks if the given cell IDs are neighbours
0618     bool areNeighbours(const CellID& cellID, const CellID& otherCellID) const;
0619 }
0620 \end{code}
0621 
0622 
0623 
0624 
0625 %=============================================================================
0626 \section{Detectors}
0627 \label{sec:ddrec-manual-detectors}
0628 %=============================================================================
0629 To be done ...
0630 
0631 
0632 
0633 \newpage
0634 %=============================================================================
0635 \begin{thebibliography}{9}
0636 \bibitem{bib:DD4hep} M. Frank et al, "DD4hep: A Detector Description Toolkit 
0637                 for High Energy Physics Experiments",
0638                 International Conference on Computing in High Energy and Nuclear Physics  
0639                 (CHEP 2013), \\
0640                 Amsterdam, Netherlands, 2013, proceedings.
0641                 
0642 \bibitem{bib:DD4hepManual} M. Frank et al, "DD4hep: A Detector Description Toolkit 
0643                 for High Energy Physics Experiments", Users manual (DD4hepManual.pdf).
0644                 
0645 
0646 \bibitem{bib:ROOT-tgeo} R.Brun, A.Gheata, M.Gheata, "The ROOT geometry package",\\
0647                     Nuclear Instruments and Methods {\bf{A}} 502 (2003) 676-680.
0648 
0649 \bibitem{bib:geant4}  S. Agostinelli et al., 
0650                    "Geant4 - A Simulation Toolkit", \\
0651                     Nuclear Instruments and Methods {\bf{A}} 506 (2003) 250-303.
0652 
0653 \end{thebibliography}
0654 %=============================================================================
0655 \end{document}