\href{#UsefulLinks}{\tt Useful links}\hypertarget{index_MAIN}{}\section{D\-D4hep -\/ A Detector Description Toolkit for High Energy Physics Experiments}\label{index_MAIN}
\hypertarget{index_INTRO}{}\section{Introduction}\label{index_INTRO}
The development of a coherent set of software tools for the description of High Energy Physics detectors from a single source of information has been on the agenda of many experiments for decades. Providing appropriate and consistent detector views to simulation, reconstruction and analysis applications from a single information source is crucial for the success of the experiments. Detector description in general includes not only the geometry and the materials used in the apparatus, but all parameters describing e.\-g. the detection techniques, constants required by alignment and calibration, description of the readout structures, conditions data, etc.

The design of the \hyperlink{namespace_d_d4hep}{D\-D4hep} toolkit is shaped on the experience of detector description systems, which were implemented for the L\-H\-C experiments, in particular the L\-H\-Cb experiment, as well as the lessons learnt from other implementations of geometry description tools developed for the Linear Collider. Designing a coherent set of tools, with most of the basic components already existing in one form or another, is an opportunity for getting the best of all existing solutions. \hyperlink{namespace_d_d4hep}{D\-D4hep} aims to widely reuse used existing software components, in particular the \hyperlink{namespace_r_o_o_t}{R\-O\-O\-T} geometry, part of the \hyperlink{namespace_r_o_o_t}{R\-O\-O\-T} project, a tool for building, browsing, navigating and visualizing detector geometries. The code is designed to optimize particle transport through complex structures and works standalone with respect to any Monte-\/\-Carlo simulation engine. The \hyperlink{namespace_r_o_o_t}{R\-O\-O\-T} geometry package provides sophisticated 3\-D visualization functionality, which is ideal for building detector and event displays. The second component is the Geant4 simulation toolkit, which is used to simulate the detector response from particle collisions in complex designs. In \hyperlink{namespace_d_d4hep}{D\-D4hep} the geometrical representation provided by \hyperlink{namespace_r_o_o_t}{R\-O\-O\-T} is the main source of information. In addition \hyperlink{namespace_d_d4hep}{D\-D4hep} provides the automatic conversions to other geometrical representations, such as Geant4, and the convenient usage of these components without the reinvention of the existing functionality.\hypertarget{index_SCOPE}{}\section{Project Scope and Requirements}\label{index_SCOPE}
The detector description should fully describe and qualify the detection apparatus and must expose access to all information required to interpret event data recorded from particle collisions. Experience from the L\-H\-C experiments has shown that a generalized view, not limited only to geometry, is very beneficial in order to obtain a coherent set of tools for the interpretation of collision data. This is particularly important in later stages of the experiment's life cycle, when a valid set of detector data must be used to analyze real or simulated detector response from particle collisions. An example would be an alignment application, where time dependent precise detector positions are matched with the detector geometry.

The following main requirements influenced the design of the toolkit\-:


\begin{DoxyItemize}
\item {\bfseries Full Detector Description.} The toolkit should be able to manage the data describing the detector geometry, the materials used when building the structures, visualization attributes, detector readout information, alignment, calibration and environmental parameters -\/ all that is necessary to interpret event data recorded from particle collisions.
\item {\bfseries The Full Experiment Life Cycle} should be supported. The toolkit should support the development of the detector concepts, detector optimizations, construction and later operation of the detector. The transition from one phase to the next should be simple and not require new developments. The initial phases are characterized by very \$ideal\$ detector descriptions, i.\-e. only very few parameters are sufficient to describe new detector designs. Once operational, the detector will be different from the ideal detector, and each part of the detector will have to have its own specific parameters and conditions, which are exposed by the toolkit.
\item {\bfseries One single source of detector information} must be sufficient to perform all data processing applications such as simulation, reconstruction, online trigger and data analysis. This ensures that all applications see a coherent description. In the past attempts by experiments to re-\/synchronize parallel detector descriptions were always problematic. Consequently, the detector description is the union of the information needed by all applications, though the level of detail may be selectable.
\item {\bfseries Ease of Use} influenced both the design and the im-\/ple-\/men-\/tation. The definition of sub-\/detectors, their geometrical description and the access to con-\/ditions and alignment data should follow a minimalistic, simple and intuitive interface. Hence, the of the developer using the toolkit is focused on specifics of the detector design and not on technicalities handled transparently by the toolkit.
\end{DoxyItemize} {\bfseries The components of the \hyperlink{namespace_d_d4hep}{D\-D4hep} detector geometry toolkit.}\hypertarget{index_DESIGN}{}\section{Toolkit Design}\label{index_DESIGN}
The Figure above shows the architecture of the main components of the toolkit and their interfaces to the end-\/user applications, namely the simulation, reconstruction, alignment and visualization. The central element of the toolkit is the so-\/called generic detector description model. This is an in-\/memory model, i.\-e., a set of C++ objects holding the data describing the geometry and other information of the detector. The rest of the toolkit consists of tools and interfaces to input or output information from this generic detector model. The model and its components will be described in subsequence sections.\hypertarget{index_COMPACT}{}\section{The Compact Detector Description}\label{index_COMPACT}
Inspired from the work of the linear collider detector simulation, the compact detector description is used to define an ideal detector as typically used during the conceptual design phase of an experiment. The compact description in its minimalistic form is probably not going to be adequate later in the detector life cycle and is likely to be replaced or refined when a more realistic detector with deviations from the ideal would be needed by the experiment.

In the compact description the detector is parametrized in minimalistic terms with user provided parameters in X\-M\-L. X\-M\-L is an open format, the \hyperlink{namespace_d_d4hep}{D\-D4hep} parsers do not validate against a fix schema and hence allow to easily introduce new elements and attributes to describe detectors. This feature minimizes the burden on the end-\/user while still supporting flexibility. Such a compact detector descriptions cannot be interpreted in a general manner, therefore so called \$\-Detector\$ \$\-Constructors\$ are needed.

 {\bfseries Class diagram with the main classes and their relations for the Generic Detector Description Model. The implementing \hyperlink{namespace_r_o_o_t}{R\-O\-O\-T} classes are shown in brackets. }\hypertarget{index_DETECTORS}{}\section{Detector Constructors}\label{index_DETECTORS}
Detector Constructors are relatively small code fragments that get as input an X\-M\-L element from the compact description that represents a single detector instance. The code interprets the data and expands its geometry model in memory using the elements from the generic detector description model described in section$\sim$subsec\-:generic-\/model\}. The toolkit invokes these code fragments in a data driven way using naming conventions during the initialization phase of the application. Users focus on one single detector type at the time, but the toolkit supports them to still construct complex and large detector setups. Two implementations are currently supported\-: One is based on C++, which performs better and is able to detect errors at compiler time, but the code is slightly more technical. The other is based on Python fragments, the code is more readable and compact but errors are only detected at execution time.

The compact description together with the detector constructors are sufficient to build the detector model and to visualize it. If during the lifetime of the experiment the detector model changes, the corresponding constructors will need to be adapted accordingly. \hyperlink{namespace_d_d4hep}{D\-D4hep} provides already a palette of basic pre-\/implemented geometrical detector concepts to design experiments. In view of usage of \hyperlink{namespace_d_d4hep}{D\-D4hep} as a detector description toolkit, this library may in the future also adopt generic designs of detector components created by end users e.\-g. during the design phase of future experiments.



{\bfseries An example sniplett of the compact detector description. The example shows the description of a 2 layered silicon vertex detector. }\hypertarget{index_DETDESCMODEL}{}\section{Generic Detector Description Model}\label{index_DETDESCMODEL}
This is the heart of the \hyperlink{namespace_d_d4hep}{D\-D4hep} detector description toolkit. Its purpose is to build in memory a model of the detector including its geometrical aspects as well as structural and functional aspects. The design reuses the elements from the \hyperlink{namespace_r_o_o_t}{R\-O\-O\-T} geometry package and extends them in case required functionality is not available. The Figure above describing the detector model illustrates the main players and their relationships. Any detector is modeled as a tree of \$\-Detector\$ \$\-Elements\$, the entity central to this design, which is represented in the implementation by the \$\-Det\-Element\$ class. It offers all applications a natural entry point to any detector part of the experiment and represents a complete sub-\/detector (e.\-g. T\-P\-C), a part of a sub-\/detector (e.\-g. T\-P\-C-\/\-Endcap), a detector module or any other convenient detector device. The main purpose is to give access to the data associated to the detector device. For example, if the user writes some T\-P\-C reconstruction code, accessing the T\-P\-C detector element from this code will provide access the all T\-P\-C geometrical dimensions, the alignment and calibration constants and other slow varying conditions such as the gas pressure, end-\/plate temperatures etc. The \$\-Detector\$ \$\-Element\$ acts as a data concentrator. Applications may access the full experiment geometry and all connected data through a singleton object called \$\-L\-C\-D\-D\$, which provides management, bookkeeping and ownership to the model instances.

The geometry is implemented using the \hyperlink{namespace_r_o_o_t}{R\-O\-O\-T} geometry classes, which are used directly without unnecessary interfaces to isolate the end-\/user from the actual \hyperlink{namespace_r_o_o_t}{R\-O\-O\-T} based implementation. There is one exception\-: The constructors are wrapped to facilitate a very compact and readable notation to end-\/users building custom \$\-Detector\$ \$\-Constructors\$.\hypertarget{index_MORE_INFO}{}\section{Still interested in more ?}\label{index_MORE_INFO}
\label{_UsefulLinks}%
Some useful Links\-:

Here you can find the manuals\-:


\begin{DoxyItemize}
\item The basic \href{../DD4hepManual.pdf}{\tt D\-D4hep manual}.
\item The \href{../DDG4Manual.pdf}{\tt D\-D\-G4 manual} to invoke the simulation toolkit Geant4 taking advantage of detector descriptions implemented in \hyperlink{namespace_d_d4hep}{D\-D4hep}.
\item The D\-D\-Align manual. A \hyperlink{namespace_geometry}{Geometry} alignment toolkit to handle geometrical imperfections.
\item The D\-D\-Cond manual to handle detector conditions for \hyperlink{namespace_d_d4hep}{D\-D4hep} based deytector descriptions. (Under construction though).
\item The \href{../DDEveManual.pdf}{\tt D\-D\-Eve manual} to visualize \hyperlink{namespace_d_d4hep}{D\-D4hep} geometries. (Under construction though).
\item \href{../DD4hep_Diagrams.pdf}{\tt U\-M\-L diagrams} from the design phase
\item \href{../refman.pdf}{\tt Doxygen Manual} in pdf format
\item \href{../DD4hep_Tutorial.pdf}{\tt Tutorial}. Relatively old...
\item \href{http://cds.cern.ch/record/1473120/files/AIDA-D2_3.pdf}{\tt Design document}
\item \href{https://sft.its.cern.ch/jira/browse/DDFORHEP}{\tt D\-D4hep bug tracker}
\end{DoxyItemize}C\-E\-R\-N intra-\/web\-:
\begin{DoxyItemize}
\item \hyperlink{namespace_d_d4hep}{D\-D4hep} mails \href{https://groups.cern.ch/group/dd4hep-developers/Lists/Archive/100.aspx}{\tt archive}.
\item \href{http://aidasoft.web.cern.ch/DD4hep}{\tt D\-D4hep A\-I\-D\-A software page}
\end{DoxyItemize}Desy\-:
\begin{DoxyItemize}
\item \href{https://svnsrv.desy.de/websvn/wsvn/General.aidasoft/DD4hep}{\tt Web svn}
\end{DoxyItemize}Markus Frank C\-E\-R\-N/\-L\-H\-Cb 