From a6a3887992abd9dda3b816868cdfb987239028aa Mon Sep 17 00:00:00 2001
From: Marko Petric <marko.petric@cern.ch>
Date: Wed, 28 Mar 2018 11:41:53 +0200
Subject: [PATCH] Update DD4hepManual
---
doc/usermanuals/DD4hep/Bibliography.tex | 46 -
doc/usermanuals/DD4hep/CMakeLists.txt | 17 +-
doc/usermanuals/DD4hep/DD4hepManual.tex | 2255 +----------------
doc/usermanuals/DD4hep/chapters/basics.tex | 1419 +++++++++++
doc/usermanuals/DD4hep/chapters/overview.tex | 131 +
doc/usermanuals/DD4hep/config.tex | 88 +
doc/usermanuals/DD4hep/figures/AIDA-2020.png | Bin 0 -> 22883 bytes
.../{figs => figures}/DD4hep-AIDA-logo.png | Bin
.../DD4hep-Lumical-detailed.png | Bin
.../{figs => figures}/DD4hep-Lumical.png | Bin
.../DD4hep-detelement-drawing.png | Bin
.../{figs => figures}/DD4hep-extensions.png | Bin
.../{figs => figures}/DD4hep-materials.png | Bin
.../{figs => figures}/DD4hep-readout.png | Bin
.../DD4hep-sensitive-detectors.png | Bin
.../{figs => figures}/DD4hep-solids.png | Bin
.../{figs => figures}/DD4hep-volmgr.png | Bin
.../{figs => figures}/DD4hep-volume-code.png | Bin
.../DD4hep-xml-code-snippet.png | Bin
.../DD4hep-xml-data-snippet.png | Bin
.../DD4hep-xml-data-structure.png | Bin
.../{figs => figures}/DD4hep_big_picture.png | Bin
.../{figs => figures}/DD4hep_classes.png | Bin
.../{figs => figures}/DD4hep_compact_xml.png | Bin
.../DD4hep_detelement_tree.png | Bin
doc/usermanuals/DD4hep/figures/cc-by.png | Bin 0 -> 12588 bytes
doc/usermanuals/DD4hep/figures/logo.eps | 142 ++
doc/usermanuals/DD4hep/html/css/custom.css | 8 +
doc/usermanuals/DD4hep/html/dd4hep.cfg | 15 +-
doc/usermanuals/DD4hep/references.bib | 135 +
doc/usermanuals/DD4hep/sections/Abstract.tex | 17 -
doc/usermanuals/DD4hep/sections/Overview.tex | 418 ---
.../DD4hep/setup/AIDA2020-logo.png | Bin 121803 -> 0 bytes
.../DD4hep/setup/AIDA2020-setup.tex | 98 -
doc/usermanuals/DD4hep/setup/DD4hep-setup.tex | 36 -
.../DD4hep/setup/Horizon2020-grant-logo.png | Bin 10152 -> 0 bytes
doc/usermanuals/DDAlign/html/css/custom.css | 8 +
doc/usermanuals/DDCond/html/css/custom.css | 8 +
doc/usermanuals/DDEve/html/css/custom.css | 8 +
doc/usermanuals/DDG4/html/css/custom.css | 8 +
doc/usermanuals/DDRec/html/css/custom.css | 8 +
41 files changed, 2088 insertions(+), 2777 deletions(-)
delete mode 100644 doc/usermanuals/DD4hep/Bibliography.tex
mode change 100644 => 100755 doc/usermanuals/DD4hep/DD4hepManual.tex
create mode 100644 doc/usermanuals/DD4hep/chapters/basics.tex
create mode 100644 doc/usermanuals/DD4hep/chapters/overview.tex
create mode 100755 doc/usermanuals/DD4hep/config.tex
create mode 100644 doc/usermanuals/DD4hep/figures/AIDA-2020.png
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep-AIDA-logo.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep-Lumical-detailed.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep-Lumical.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep-detelement-drawing.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep-extensions.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep-materials.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep-readout.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep-sensitive-detectors.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep-solids.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep-volmgr.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep-volume-code.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep-xml-code-snippet.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep-xml-data-snippet.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep-xml-data-structure.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep_big_picture.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep_classes.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep_compact_xml.png (100%)
rename doc/usermanuals/DD4hep/{figs => figures}/DD4hep_detelement_tree.png (100%)
create mode 100755 doc/usermanuals/DD4hep/figures/cc-by.png
create mode 100644 doc/usermanuals/DD4hep/figures/logo.eps
create mode 100755 doc/usermanuals/DD4hep/references.bib
delete mode 100644 doc/usermanuals/DD4hep/sections/Abstract.tex
delete mode 100644 doc/usermanuals/DD4hep/sections/Overview.tex
delete mode 100644 doc/usermanuals/DD4hep/setup/AIDA2020-logo.png
delete mode 100644 doc/usermanuals/DD4hep/setup/AIDA2020-setup.tex
delete mode 100644 doc/usermanuals/DD4hep/setup/DD4hep-setup.tex
delete mode 100644 doc/usermanuals/DD4hep/setup/Horizon2020-grant-logo.png
diff --git a/doc/usermanuals/DD4hep/Bibliography.tex b/doc/usermanuals/DD4hep/Bibliography.tex
deleted file mode 100644
index 1985339d4..000000000
--- a/doc/usermanuals/DD4hep/Bibliography.tex
+++ /dev/null
@@ -1,46 +0,0 @@
-\bibitem{bib:DD4hep} DD4Hep web page, http://aidasoft.web.cern.ch/DD4hep.
-
-\bibitem{bib:LHCb} LHCb Collaboration,
- "LHCb, the Large Hadron Collider beauty experiment, reoptimised detector
- design and performance", CERN/LHCC 2003-030
-
-\bibitem{bib:LHCb-geometry} S. Ponce et al.,
- "Detector Description Framework in LHCb",
- International Conference on Computing in High Energy and Nuclear Physics (CHEP 2003),
- La Jolla, CA, 2003, proceedings.
-
-\bibitem{bib:ILD} The ILD Concept Group,
- "The International Large Detector: Letter of Intent",\\
- ISBN 978-3-935702-42-3, 2009.
-
-\bibitem{bib:SiD} H. Aihara, P. Burrows, M. Oreglia (Editors),
- "SiD Letter of Intent",
- arXiv:0911.0006, 2009.
-
-\bibitem{bib:ROOT-tgeo} R.Brun, A.Gheata, M.Gheata, "The ROOT geometry package",\\
- Nuclear Instruments and Methods {\bf{A}} 502 (2003) 676-680.
-
-\bibitem{bib:ROOT} R.Brun et al.,
- "Root - An object oriented data analysis framework",\\
- Nuclear Instruments and Methods {\bf{A}} 389 (1997) 81-86.
-
-\bibitem{bib:geant4} S. Agostinelli et al.,
- "Geant4 - A Simulation Toolkit", \\
- Nuclear Instruments and Methods {\bf{A}} 506 (2003) 250-303.
-
-\bibitem{bib:LCDD} T.Johnson et al.,
- "LCGO - geometry description for ILC detectors",
- International Conference on Computing in High Energy and Nuclear Physics (CHEP 2007),
- Victoria, BC, Canada, 2012, Proceedings.
-
-\bibitem{bib:lcsim} N.Graf et al.,
- "lcsim: An integrated detector simulation,
- reconstruction and analysis environment",
- International Conference on Computing in High Energy and Nuclear Physics (CHEP 2012),
- New York, 2012, Proceedings.
-
-\bibitem{bib:GDML} R. Chytracek et al.,
- "Geometry Description Markup Language for Physics Simulation and Analysis
- Applications",
- IEEE Trans. Nucl. Sci., Vol. 53, Issue: 5, Part 2, 2892-2896,
- http://gdml.web.cern.ch.
diff --git a/doc/usermanuals/DD4hep/CMakeLists.txt b/doc/usermanuals/DD4hep/CMakeLists.txt
index aa8c88a9e..588468898 100755
--- a/doc/usermanuals/DD4hep/CMakeLists.txt
+++ b/doc/usermanuals/DD4hep/CMakeLists.txt
@@ -1,16 +1,19 @@
SET(LATEX_OUTPUT_PATH ${CMAKE_BINARY_DIR}/DD4hepManual)
ADD_LATEX_DOCUMENT(
DD4hepManual.tex
+
+ BIBFILES
+ references.bib
+ USE_BIBLATEX
+
IMAGE_DIRS
- figs
- setup
+ figures
INPUTS
- sections/Abstract.tex
- sections/Overview.tex
- setup/AIDA2020-setup.tex
- setup/DD4hep-setup.tex
- Bibliography.tex
+ config.tex
+ chapters/basics.tex
+ chapters/overview.tex
+ figures/logo.eps
html/dd4hep.cfg
html/tools.sty
diff --git a/doc/usermanuals/DD4hep/DD4hepManual.tex b/doc/usermanuals/DD4hep/DD4hepManual.tex
old mode 100644
new mode 100755
index bfb0c00b5..b68c28020
--- a/doc/usermanuals/DD4hep/DD4hepManual.tex
+++ b/doc/usermanuals/DD4hep/DD4hepManual.tex
@@ -1,2169 +1,128 @@
-%=============================================================================
-\documentclass[10pt,a4paper]{article}
-%
-\input{./setup/DD4hep-setup.tex}
-\input{./setup/AIDA2020-setup.tex}
-%
-\pagestyle{fancyplain}{\fancyfoot[C]{\sffamily{DD4hep User Manual}}}
-%
-%
-\graphicspath{{./figs/}}
-\begin{document}
-%
-\mytitle{
-DD4hep
-}{
-A Detector Description Toolkit\\
-for High Energy Physics\\
-\vspace{0.3cm}
-Experiments
+%----------------------------------------------------------------------------------------
+% PACKAGES AND DOCUMENT CONFIGURATIONS
+%----------------------------------------------------------------------------------------
+
+\documentclass[captions=tableheading,a4paper,11pt,numbers=noenddot,headsepline,titlepage,twoside,openright,DIV=14,BCOR=8mm,parskip=half]{scrbook}
+\PassOptionsToPackage{obeyspaces}{url}
+\usepackage[backend=biber,
+ autocite=plain,
+ sorting=none,
+ url=false
+ ]{biblatex}
+\usepackage[T1]{fontenc}
+\usepackage[shortlabels]{enumitem}
+\usepackage{siunitx}
+\usepackage{array}
+\usepackage{ccicons}
+\usepackage{booktabs}
+\usepackage{xspace}
+\usepackage{xcolor}
+\usepackage{minted}
+%\usemintedstyle{emacs}
+\usepackage{a4wide}
+\usepackage{listings}
+\usepackage{graphicx}
+\usepackage{seqsplit}
+\usepackage{multirow}
+\usepackage[unicode=true]{hyperref}
+\usepackage{microtype}
+\usepackage{pgffor}
+\usepackage{lmodern}
+\usepackage{amssymb,amsmath}
+\usepackage{ifxetex,ifluatex}
+\usepackage{fixltx2e}
+\usepackage[utf8]{inputenc}
+\usepackage{eurosym}
+\usepackage{fancyvrb}
+\urlstyle{same}
+\usepackage{longtable,booktabs}
+\usepackage[normalem]{ulem}
+
+\newcommand{\DDE}{{$\texttt{DDEve}$\xspace}}
+\newcommand{\DDhep}{{$\texttt{DD4hep}$\xspace}}
+\newcommand{\DDH}{{$\texttt{DD4hep}$\xspace}}
+\newcommand{\DDG}{{\texttt{DDG4}\xspace}}
+\newcommand{\DDA}{{\texttt{DDAlign}\xspace}}
+\newcommand{\DDC}{{\texttt{DDCond}\xspace}}
+\newcommand{\DDR}{{\texttt{DDRec}\xspace}}
+
+
+\newcommand{\detdesc}[2]
+{
+ \href{http://www.cern.ch/frankm/DD4hep/#1}{#2}
}
-{M. Frank \\
-{CERN, 1211 Geneva 23, Switzerland}}
-%
-%
-%== Abstract ===============================================================
-\pagestyle{plain}
-\pagenumbering{Roman}
-\setcounter{page}{1}
-
-\begin{abstract}
-\normalsize
-\input{sections/Abstract.tex}
-\end{abstract}
-
-\vspace{8cm}
-
-\begin{center}
-{\large{\bf{
-\begin{tabular} {| l | l | l |}
-\hline
-\multicolumn{3}{| c |}{} \\[0.2cm]
-\multicolumn{3}{| c |}{Document History} \\[0.2cm]
-\multicolumn{3}{| c |}{} \\[0.2cm]
-\hline
- & & \\
-Document & & \\
-version & Date & Author \\[0.2cm] \hline
- & & \\
-1.0 & 19/11/2013 & Markus Frank CERN/LHCb \\
- & & \\ \hline
-\end{tabular}
-}}}
-\end{center}
-
-\clearpage
-%
-%
-%== TOC ====================================================================
-\tableofcontents
-\clearpage
-%
-%
-%== Introduction ===========================================================
-\pagenumbering{arabic}
-\setcounter{page}{1}
-\input{sections/Overview.tex}
-
-\noindent
-The eqnarrayment support will be subject to a separate development line of the
-\DDhep toolkit, called \DDA and hence will be discussed in another
-manual~\cite{bib:DDeqnarray}.
-%
-\newpage
-%=============================================================================
-% Manual
-%=============================================================================
-\section{User Manual}
-\label{sec:dd4hep-user-manual}
-%=============================================================================
-\noindent
-This chapter describes how supply a physics application developed with all the
-information related to the detector which is necessary to process data from
-particle collisions and to qualify the detecting apparatus in order to
-interpret these event data.
-
-\noindent
-The clients of the detector description are the algorithms residing in the
-event processing framework that need this information in order to perform
-their job (reconstruction, simulation, etc.).
-The detector description provided by \DDhep is a framework for developers
-to provide the specific detector information to software algorithms, which
-process data from particle collisions.
-
-\noindent
-In the following sections an overview is given over the various independent
-elements of \DDhep followed by the discussion of an example which leads to
-the description of a detector when combining these elements.
-This includes a discussion of the features of the \DDhep detector description
-and of its structure.
-
-%=============================================================================
-\subsection{Building DD4hep}
-\label{sec:dd4hep-user-manual-building}
-%=============================================================================
-
-\noindent
-The \DDhep source code is freely available. See the
-\detdesc{doc/LICENSE}{licence conditions}.
-Please read the \detdesc{doc/release.notes}{Release Notes}
-before downloading or using this release.
-
-\noindent
-The \DDhep project consists of several packages. The idea
-has been to separate the common parts of
-the detector description toolkit from concrete detector examples.
-
-\noindent
-The package {\tw{DDCore}} contains the definition of the basic classes
-of the toolkit: \tw{Handle}, \tw{DetElement}, \tw{Volume}, \tw{PlacedVolume},
-\tw{Shapes}, \tw{Material}, etc. Most of these classes are \tw{handles}
-to ROOT's TGeom classes.
-
-%=============================================================================
-\subsubsection{Supported Platforms}
-\label{sec:dd4hep-user-manual-platforms}
-%=============================================================================
-\noindent
-Supported platforms for DD4hep are the CERN Linux operating systems:
-\begin{itemize}
-\item \tw{Scientic} \tw{Linux} \tw{CERN} \tw{6}
-\item \tw{Scientic} \tw{Linux} \tw{CERN} \tw{7} - once approved.
-\end{itemize}
-Support for any other platform will well be taken into account, but can only
-be actively supported by users who submit the necessary patches.
-
-%=============================================================================
-\subsubsection{Prerequisites}
-\label{sec:dd4hep-user-manual-prerequisites}
-%=============================================================================
-\noindent
-DD4hep depends on a number of $external$ packages.
-The user will need to install these in his/her
-system before building and running the examples
-\begin{itemize}\itemcompact
-\item Mandatory are recent \tw{CMake} (version 2.8 or higher) and
-\item \tw{ROOT} (version 5.34 or higher) installations.~\footnote{Please
-not, that due to the removal of the Reflex plugin mechanism from ROOT 6,
-version 6 of ROOT is currently not supported. This deficiency will be waved
-in the future.}
-\item If the \tw{Xerces-C} is used to parse compact descriptions and
- installation of {Xerces-C} will be required.
-\item To build \DDG it is mandatory to have an installation of the Boost
- header files.
-\item To build and run the simulation examples \tw{Geant4} will be required.
-\end{itemize}
-
-\newpage
-%=============================================================================
-\subsubsection{CMake Build Options for DD4hep}
-\label{sec:dd4hep-user-manual-building}
-%=============================================================================
-\noindent
-The package provides the basic mechanisms for constructing the
-{\it{Generic Detector Description Model}} in memory from XML compact detector
-definition files. Two methods are currently supported: one based
-on the C++ \tw{Xerces}-C parser, and another one based on Python and using the
-\tw{PyROOT} bindings to ROOT~\footnote{I will not continue
-the support using PyROOT. \\
-If there is a desire that it stays alive
-someone else should take care -- M.Frank}.
-\tw{PyROOT} may be enabled using the switch:
-
-\begin{unnumberedcode}
- -DD4HEP_USE_PYROOT:BOOL
-\end{unnumberedcode}
-
-\noindent
-The XML parsing method is enabled by default using the \tw{TiXML} parser. Optionally
-instead of \tw{TiXML} the \tw{Xerces}-C parser may be chosen by setting the
-two configuration options appropriately:
-
-\begin{unnumberedcode}
- -DD4HEP_USE_XERCESC:BOOL
- -DXERCESC_ROOT_DIR=<path to Xerces-C-installation-directory>
-\end{unnumberedcode}
-
-\noindent
-{\bf{DDG4}} is the package that contains the conversion of \DDhep geometry
-into Geant4 geometry to be used for simulation.
-The option \tw{DD4HEP\_WITH\_GEANT4:BOOL} controls the building or not of
-this package that has the dependency to Geant4. The Geant4 installation
-needs to be located using the variable:
-
-\begin{unnumberedcode}
- -DDD4HEP_WITH_GEANT4=on -D
- -DGeant4_DIR=<path to Geant4Config.cmake>
-\end{unnumberedcode}
-
-\noindent
-To properly handle component properties using \tw{boost::spirit},
-access to the Boost header files must be provided.
-\vspace{0.3cm}
-\begin{unnumberedcode}
- -DDD4HEP_USE_BOOST=ON
- -DBOOST_INCLUDE_DIR=<path to the boost include directory>
-\end{unnumberedcode}
-
-\noindent
-Other useful build options:
-\begin{itemize}
-\item build doxygen documentation ( after 'install' open ./doc/html/index.html)
-\begin{unnumberedcode}
- -D INSTALL_DOC=on
-\end{unnumberedcode}
-
-\item {\bf{note:}} you might have to update your environment beforehand to have all needed
- libraries in the shared lib search path (this will vary with OS, shell, etc.) e.g
-\begin{unnumberedcode}
- . /data/ilcsoft/geant4/9.5/bin/geant4.sh
- export CLHEP_BASE_DIR="/data/ilcsoft/HEAD/CLHEP/2.1.0.1"
- export CLHEP_INCLUDE_DIR="$CLHEP_BASE_DIR/include"
- export PATH="$CLHEP_BASE_DIR/bin:$PATH"
- export LD_LIBRARY_PATH="$CLHEP_BASE_DIR/lib:$LD_LIBRARY_PATH"
-\end{unnumberedcode}
-\end{itemize}
-
-%=============================================================================
-\subsubsection{Build From Source}
-\label{sec:dd4hep-user-manual-building-from-source}
-%=============================================================================
-\noindent
-The following steps are necessary to build \DDhep:
-\begin{itemize}
-\item Set the environment, at least ROOT needs to be initialized, e.g.
- \begin{unnumberedcode}
- source /data/ilcsoft/root/5.34.03/bin/thisroot.sh
- \end{unnumberedcode}
- \vspace{-0.6cm}
- (the bare minimum is: \tw{export ROOTSYS=<path to root installation>}).
-
-\item First checkout code from the repository:
- \begin{unnumberedcode}
- svn co https://svnsrv.desy.de/public/aidasoft/DD4hep/trunk DD4hep
- \end{unnumberedcode}
- \vspace{-0.6cm}
-
-\item We refer to the directory \DDhep as the source directory. The
-next step is to create a directory in which to configure and run the build
-and store the build products. This directory should not be the same as, or
-inside, the source directory. In this guide, we create this build directory
-alongside our source directory:
- \begin{unnumberedcode}
- mkdir build
- cd build
- cmake -DCMAKE_INSTALL_PREFIX=<dd4hep-install-pasth> <CMake-options> ../DD4hep
- make -j 4
- make install
- \end{unnumberedcode}
-\end{itemize}
-The CMake Variable \tw{CMAKE\_INSTALL\_PREFIX} is used to set the install directory,
-the directory under which the \DDhep libraries, headers and support files
-will be installed.
-
-%=============================================================================
-\subsubsection{Tutorial}
-\label{sec:dd4hep-user-manual-tutorial}
-%=============================================================================
-\noindent
-In January 2013 an introductory tutorial was given at CERN to members of the
-linear collider community. The slides to the tutorial can be found
-\detdesc{doc/DD4hep_Tutorial.pdf}{here}.
-The tutorial is not entirely up to date. Please take the content with a
-grain of salt.
-
-%=============================================================================
-\subsubsection{Doxygen Code Documentation}
-\label{sec:dd4hep-user-manual-doxygen}
-%=============================================================================
-\noindent
-The \DDhep source code is instrumented with tags understood by doxygen.
-The generated code documentation can be found
-\detdesc{html/index.html}{here}.
-
-%=============================================================================
-\subsubsection{Remarks}
-\label{sec:dd4hep-user-manual-remarks}
-%=============================================================================
-\noindent
-The main reference is the doxygen information of \DDhep and the ROOT documentation.
-Please refer to these sources for a detailed view of the capabilities of
-each component and/or its handle.
-For coherence reasons, the description of the
-interfaces is limited to examples which illustrate the usage of the basic
-components.
-
-%=============================================================================
-\subsubsection{Caveat}
-\label{sec:dd4hep-user-manual-caveat}
-%=============================================================================
-\noindent
-The atomic units in of Geant4 are (millimeter, nanosecond and MeV and radians).
-The atomic units of ROOT-TGeo are (centimeter, seconds, GeV and degrees).
-Unfortunately the authors could not agree on a common system of units
-and mixing the two can easily result in a chaos.
-Users must be aware of this fact.
-
-
-\newpage
-%=============================================================================
-\subsection{DD4hep Handles}
-\label{sec:dd4hep-user-manual-handles}
-%=============================================================================
-\noindent
-Handles are the means of clients accessing \DDhep detector description data.
-The data itself is not held by the handle itself, the handle only allows the
-access to the data typically held by a pointer. The template handle class
-(see for details the \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_handle.html}{header file}).
-allows type safe assignment of other unrelated handles and supports standard
-data conversions to the underlying object in form of the raw pointer,
-a reference etc. The template handle class:
-
-\begin{code}
-template <typename T> class Handle {
-public:
- // Type definitions and class specific abbreviations and forward declarations
- typedef T Implementation;
- typedef Handle<Implementation> handle_t;
-public:
- // Single and only data member: pointer to the underlying object
- T* m_element;
-
-public:
- Handle() : m_element(0) { }
- Handle(T* e) : m_element(e) { }
- Handle(const Handle<T>& e) : m_element(e.m_element) { }
- template<typename Q> Handle(Q* e)
- : m_element((T*)e) { verifyObject(); }
- template<typename Q> Handle(const Handle<Q>& e)
- : m_element((T*)e.m_element) { verifyObject(); }
- Handle<T>& operator=(const Handle<T>& e) { m_element=e.m_element; return *this;}
- bool isValid() const { return 0 != m_element; }
- bool operator!() const { return 0 == m_element; }
- void clear() { m_element = 0; }
- T* operator->() const { return m_element; }
- operator T& () const { return *m_element; }
- T& operator*() const { return *m_element; }
- T* ptr() const { return m_element; }
- template <typename Q> Q* _ptr() const { return (Q*)m_element; }
- template <typename Q> Q* data() const { return (Q*)m_element; }
- template <typename Q> Q& object() const { return *(Q*)m_element; }
- const char* name() const;
-};
-\end{code}
-
-\noindent
-effectively works like a pointer with additional object validation during assignment
-and construction. Handles support direct access to the held object: either by using
-the
-
-\begin{verbatim}
- operator->() (See line 16 above)
-\end{verbatim}
-
-\noindent
-or the automatic type conversions:
-
-\begin{verbatim}
- operator T& () const (See line 17-18 above)
- T& operator*() const.
-\end{verbatim}
-
-\noindent
-All entities of the \DDhep detector description are exposed as handles -
-raw pointers should not occur in the code.
-The handles to these objects serve two purposes:
-\begin{itemize}\itemcompact
-\item Hold a pointer to the object and extend the functionality of a raw
- pointer.
-\item Enable the creation of new objects using specialized constructors
- within sub-classes. To ensure memory integrity and avoid resource
- leaks these created objects should always be stored in the
- detector description data hub $LCDD$ described in
- section~\ref{sec:dd4hep-user-manual-LCDD-hub}.
-\end{itemize}
-
-\newpage
-%=============================================================================
-\subsection{The Data Extension Mechanism}
-\label{sec:dd4hep-user-manual-data-extensions}
-%=============================================================================
-\noindent
-Data extensions are client defined C++ objects aggregated to basic \DDhep objects.
-The need to introduce such data extensions results from the simple fact that
-no data structure can be defined without the iterative need in the long term
-to extend it leading to implementations, which can only satisfy a subset of
-possible clients. To accomplish for this fact a mechanism was put in place
-which allows any user to attach any supplementary information provided
-the information is embedded in a polymorph object with an accessible destructor.
-There is one limitation though: object extension must differ by their
-interface type.
-There may not be two objects attached with the identical interface type.
-The actual implemented sub-type of the extension is not relevant.
-Separating the interface type from the implementation type keeps client
-code still functional even if the implementation of the extension changes
-or is a plug-able component.
-
-\noindent
-The following code snippet shows the extension interface:
-
-\begin{code}
- /// Extend the object with an arbitrary structure accessible by the type
- template <typename IFACE, typename CONCRETE> IFACE* addExtension(CONCRETE* c);
- /// Access extension element by the type
- template <class T> T* extension() const;
-\end{code}
-
-Assuming a client class of the following structure:
-\begin{code}
- class ExtensionInterface {
- virtual ~ExtensionInterface();
- virtual void foo() = 0;
- };
-
- class ExtensionImplementation : public ExtensionInterface {
- ExtensionImplementation();
- virtual ~ExtensionImplementation();
- virtual void foo();
- };
-\end{code}
-is then attached to an extensible object as follows:
-\begin{code}
- ExtensionImplementation* ptr = new ExtensionImplementation();
- ... fill the ExtensionImplementation instance with data ...
- module.addExtension<ExtensionInterface>(ptr);
-\end{code}
-The data extension may then be retrieved whenever the instance of the
-extensible object "module" is accessible:
-\begin{code}
- ExtensionInterface* ptr = module.extension<ExtensionInterface>();
-\end{code}
-The lookup mechanism is rather efficient. Though it is advisable to
-cache the pointer withing the client code if the usage is very frequent.
-
-
-\noindent
-There are currently three object types present which support this mechanism:
-\begin{itemize}\itemcompact
-\item the central object of \DDhep, the \tw{LCDD} class discussed in
- section~\ref{sec:dd4hep-user-manual-LCDD-hub}.
-\item the object describing subdetectors or parts thereof, the
- \tw{DetElement} class discussed in
- section~\ref{sec:dd4hep-user-manual-detector-elements}.
- Detector element extensions in addition require the presence
- of a copy constructor to support e.g. reflection operations.
- Without a copy mechanism detector element hierarchies could
- cloned.
-\item the object describing sensitive detectors,
- the \tw{SensitiveDetector} class discussed in
- section~\ref{sec:dd4hep-user-manual-sensitive-detectors}.
-\end{itemize}
-
-
-\newpage
-%=============================================================================
-\subsection{XML Tools and Interfaces}
-\label{sec:dd4hep-user-manual-xml-tools}
-%=============================================================================
-\noindent
-Using native tools to interpret XML structures is rather tedious and lengthy.
-To easy the access to XML data considerable effort was put in place to easy
-the life of clients as much as possible using predefined constructs to
-access XML attributes, elements or element collections.
-
-\noindent
-The functionality of the XML tools is perhaps best shown with a small example.
-Imagine to extract the data from an XML snippet like the following:
-\begin{code}
- <detector name="Sometthing">
- <tubs rmin="BP_radius - BP_thickness" rmax="BP_radius" zhalf="Endcap_zmax/2.0"/>
- <position x="0" y="0" z="Endcap_zmax/2.0" />
- <rotation x="0.0" y="CrossingAngle/2.0" z="0.0" />
- <layer id="1" inner_r="Barrel_r1"
- outer_r="Barrel_r1 + 0.02*cm" inner_z="Barrel_zmax + 0.1*cm">
- <slice material = "G10" thickness ="0.5*cm"/>
- </layer>
- <layer id="2" inner_r="Barrel_r2"
- outer_r="Barrel_r2 + 0.02*cm" inner_z="Barrel_zmax + 0.1*cm">
- <slice material = "G10" thickness ="0.5*cm"/>
- </layer>
- ....
- </detector>
-\end{code}
-
-The variable names used in the XML snippet are evaluated when interpreted.
-Unless the attributes are accessed as strings, the client never sees the
-strings, but only the evaluated numbers.
-The anatomy of the C++ code snippets to interpret such a data section
-looks very similar:
-\begin{code}
- static void some_xml_handler(xml_h e) {
- xml_det_t x_det (e);
- xml_comp_t x_tube = x_det.tubs();
- xml_dim_t pos = x_det.position();
- xml_dim_t rot = x_det.rotation();
- string name = x_det.nameStr();
-
- for(xml_coll_t i(x_det,_U(layer)); i; ++i) {
- xml_comp_t x_layer = i;
- double zmin = x_layer.inner_z();
- double rmin = x_layer.inner_r();
- double rmax = x_layer.outer_r();
- double layerWidh = 0;
-
- for(xml_coll_t j(x_layer,_U(slice)); j; ++j) {
- double thickness = xml_comp_t(j).thickness();
- layerWidth += thickness;
- }
- }
- }
-\end{code}
-In the above code snippet an XML (sub-)tree is passed to the executing
-function as a handle to an XML element ({\tt{xml\_h}}). Such handles may seamlessly be
-assigned to any supporting helper class inheriting from the
-class {\tt{XML::Element}}, which encapsulates the functionality required to
-interpret the XML structures.
-Effectively the various XML attributes and child nodes
-are accessed using functions with the same
-name from a convenience handle.
-In lines 3-5 child nodes are extracted, lines 10-12,16 access element attributes.
-Element collections with the same tag names \tw{layer} and \tw{slice} are exposed
-to the client code using an iteration mechanism.
-
-\noindent
-Note the macros $\tt{\_U(layer)}$ and $\tt{\_U(slice)}$:
-When using Xerces-C as an XML parser,
-it will expand to the reference to an object containing the unicode value
-of the string "layer". The full list of predefined tag names can be found in the
-include file \detdesc{html/_unicode_values_8h.html}{DD4hep/UnicodeValues.h}.
-If a user tag is not part in the precompiled tag list, the corresponding Unicode
-string may be created with the macro \tw{\_Unicode(layer)} or the function
-\tw{Unicode("layer")}.
-
-\noindent
-The convenience handles actually implement
-these functions to ease life. There is no magic - newly created attributes
-with new names obviously cannot be accessed with convenience mechanism.
-Hence, either you know what you are doing and you create your own
-convenience handlers or you restrict yourself a bit in the creativity
-of defining new attribute names.
-
-\noindent
-There exist several utility classes to extract data from predefined XML tags:
-\begin{itemize}\itemcompact
-\item Any XML element is described by an XML handle
- \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_handle.html}{\tt{XML::Handle\_t}}
- ({\tt{xml\_t}}). Handles are the basic structure for the support
- of higher level interfaces described above. The assignment of a handle
- to any of the interfaces below is possible.
-\item The class \detdesc{html/struct_d_d4hep_1_1_x_m_l_1_1_element.html}{\tt{XML::Element}}
- ({\tt{xml\_elt\_t}})
- supports in a simple way the navigation through the hierarchy of the
- XML tree accessing child nodes and attributes. Attributes at this
- level are named entities and the tag name must be supplied.
-\item The class \detdesc{html/struct_d_d4hep_1_1_x_m_l_1_1_dimension.html}{\tt{XML::Dimension}}
- with the type definition {\tt{xml\_dim\_t}},
- supports numerous access functions named identical to the
- XML attribute names. Such helper classes simplify the tedious
- string handling required by the
-\item The class \detdesc{html/struct_d_d4hep_1_1_x_m_l_1_1_component.html}{\tt{XML::Component}}
- ({\tt{xml\_comp\_t}}) and \\
- the class \detdesc{html/struct_d_d4hep_1_1_x_m_l_1_1_det_element.html}{\tt{XML::Detector}}
- ({\tt{xml\_det\_t}}) resolving other issues useful to construct detectors.
-\item Sequences of XML elements with an identical tag name may be handled
- as iterations as shown in the Figure above using the class
- \detdesc{html/struct_d_d4hep_1_1_x_m_l_1_1_collection__t.html}{\tt{XML::Collection\_t}}.
-\item Convenience classes, which allow easy access to element attributes
- may easily be constructed using the methods of the {\tt{XML::Element}}
- class. This allows to construct very flexible thou non-intrusive
- extensions to \DDhep. Hence there is a priori no need to modify
- these helpers for the benefit of only one single client.
- In the presence of multiple requests such extensions may though be adopted.
-\end{itemize}
-It is clearly the responsibility of the client to only request attributes
-from an XML element, which exist. If an attribute, a child node etc. is not
-found within the element an exception is thrown.
-
-\noindent
-The basic interface of the \tw{XML::Element} class allows to access tags
-and child nodes not exposed by the convenience wrappers:
-\begin{code}
- /// Access the tag name of this DOM element
- std::string tag() const;
- /// Access the tag name of this DOM element
- const XmlChar* tagName() const;
-
- /// Check for the existence of a named attribute
- bool hasAttr(const XmlChar* name) const;
- /// Retrieve a collection of all attributes of this DOM element
- std::vector<Attribute> attributes() const;
- /// Access single attribute by it's name
- Attribute getAttr(const XmlChar* name) const;
- /// Access attribute with implicit return type conversion
- template <class T> T attr(const XmlChar* tag) const;
- /// Access attribute name (throws exception if not present)
- const XmlChar* attr_name(const Attribute attr) const;
- /// Access attribute value by the attribute (throws exception if not present)
- const XmlChar* attr_value(const Attribute attr) const;
-
- /// Check the existence of a child with a given tag name
- bool hasChild(const XmlChar* tag) const;
- /// Access child by tag name. Thow an exception if required in case the child is not present
- Handle_t child(const Strng_t& tag, bool except = true) const;
- /// Add a new child to the DOM node
- Handle_t addChild(const XmlChar* tag) const;
- /// Check if a child with the required tag exists - if not create it and add it to the current node
- Handle_t setChild(const XmlChar* tag) const;
-\end{code}
-
-%=============================================================================
-\subsection{The Detector Description Data Hub: LCDD}
-\label{sec:dd4hep-user-manual-LCDD-hub}
-%=============================================================================
-\noindent
-As shown in Figure~\ref{fig:dd4hep-detector-model}, any access to the detector
-description data is done using a standardized interface called \tw{LCDD}.
-During the configuration phase of the detector the interface is used to populate
-the internal data structures.
-Data structures present in the memory layout of the detector description
-may be retrieved by clients at any time using the
-\detdesc{html/struct_d_d4hep_1_1_geometry_1_1_l_c_d_d.html}{\tw{LCDD} interface class}.
-This includes of course, the access during the actual detector construction.
-The following code listing shows the accessor method to retrieve
-detector description entities from the interface. Not shown are access methods
-for groups of these entities and the methods to add objects:
-
-\begin{code}
-struct LCDD {
-
- ///+++ Shortcuts to access often used quantities
-
- /// Return handle to material describing air
- virtual Material air() const = 0;
- /// Return handle to material describing vacuum
- virtual Material vacuum() const = 0;
- /// Return handle to "invisible" visualization attributes
- virtual VisAttr invisible() const = 0;
-
- ///+++ Access to the top level detector elements and the corresponding volumes
-
- /// Return reference to the top-most (world) detector element
- virtual DetElement world() const = 0;
- /// Return reference to detector element with all tracker devices.
- virtual DetElement trackers() const = 0;
-
- /// Return handle to the world volume containing everything
- virtual Volume worldVolume() const = 0;
- /// Return handle to the volume containing the tracking devices
- virtual Volume trackingVolume() const = 0;
-
- ///+++ Access to geometry and detector description objects
-
- /// Retrieve a constant by it's name from the detector description
- virtual Constant constant(const std::string& name) const = 0;
- /// Retrieve a matrial by it's name from the detector description
- virtual Material material(const std::string& name) const = 0;
- /// Retrieve a field component by it's name from the detector description
- virtual DetElement detector(const std::string& name) const = 0;
- /// Retrieve a sensitive detector by it's name from the detector description
- virtual SensitiveDetector sensitiveDetector(const std::string& name) const = 0;
- /// Retrieve a readout object by it's name from the detector description
- virtual Readout readout(const std::string& name) const = 0;
- /// Retrieve a id descriptor by it's name from the detector description
- virtual IDDescriptor idSpecification(const std::string& name) const = 0;
- /// Retrieve a subdetector element by it's name from the detector description
- virtual CartesianFieldfield(const std::string& name) const = 0;
-
- ///+++ Access to visualisation attributes and Geant4 processing hints
-
- /// Retrieve a visualization attribute by it's name from the detector description
- virtual VisAttr visAttributes(const std::string& name) const = 0;
-
- /// Retrieve a region object by it's name from the detector description
- virtual Region region(const std::string& name) const = 0;
- /// Retrieve a limitset by it's name from the detector description
- virtual LimitSet limitSet(const std::string& name) const = 0;
- /// Retrieve an eqnarrayment entry by it's name from the detector description
- virtual eqnarraymentEntryeqnarrayment(const std::string& path) const = 0;
- ...
-
- ///+++ Extension mechanism:
-
- /// Extend the sensitive detector element with an arbitrary structure accessible by the type
- template <typename IFACE, typename CONCRETE> IFACE* addExtension(CONCRETE* c);
- /// Access extension element by the type
- template <class T> T* extension() const;
-};
-\end{code}
-
-\noindent
-As shown in the above listing, the \tw{LCDD} interface is the main access point to access
-a whole set
-\begin{itemize}\itemcompact
-\item often used predefined values such as the material "air" or "vacuum" (line 5-10).
-\item the top level objects "world", "trackers" and the corresponding volumes (line 14-22).
-\item items in the constants table containing named definitions also used during the
- interpretation of the XML content after parsing (line 27)
-\item named items in the the material table (line 29)
-\item named subdetectors after construction and the corresponding (line 31)
-\item named sensitive detectors with their (line 33)
-\item named readout structure definition using a (line 35)
-\item named readout identifier descriptions (line 37)
-\item named descriptors of electric and/or magnetic fields (line 39).
-\end{itemize}
-Additional support for specialized applications is provided by the interface:
-\begin{itemize}\itemcompact
-\item Geant4: named region settings (line 47)
-\item Geant4: named limits settings (line 49)
-\item Visualization: named visualization attributes (line 44)
-\item eqnarrayment: named eqnarrayment entries to correct displaced volumes (line 51)
-\item User defined extensions (line 56-59) are supported with the extension mechanism
- described in section~\ref{sec:dd4hep-user-manual-data-extensions}.
-\end{itemize}
-All the values are populated either directly from XML or from
-\tw{detector-constructors} (see section~\ref{sec:detector-constructors}). The interface
-also allows to load XML configuration files of any kind provided an appropriate
-interpretation plugin is present. In the next section we describe the functionality
-of the "lccdd" plugin used to interpret the compact detector description.
-This mechanism can easily be extended using ROOT plugins, where the
-plugin name must corrspond to the XML root element of the document to
-be interpreted.
-
-\newpage
-%=============================================================================
-\subsection{Detector Description Persistency in XML}
-\label{sec:compact-xml-structure}
-%=============================================================================
-\noindent
-As explained in a previous section, the mechanism involved in the data loading
-allow an application to be fairly independent of the technology used to populate
-the transient detector representation. However, if one wants to use a given tech-
-nology, she/he has to get/provide the corresponding conversion mechanism.
-Though \DDhep also supports the population of the detector description using
-python constructs, we want to focus here on the XML based population.
-The choice of XML was driven mainly by its easiness of use and the number
-of tools provided for its manipulation and parsing. Moreover, XML data
-can be easily translated into many other format using tools like \tw{XSLT}
-processors.
-The grammar used for the XML data is pretty simple and straight forward,
-actually very similar to other geometry description languages based
-on XML. For example the material description is nearly identical
-to the material description in \tw{GDML}~\cite{bib:GDML}.
-The syntactic structure of the compact XML description was taken from
-the SiD detector description~\cite{bib:LCDD}.
-The following listing shows the basic layout of any
-the compact detector description file with its different sections:
-
-\begin{code}
-<lccdd>
- <info> ... </info> Auxiliary detector model information
- <includes> ... </includes> Section defining GDML files to be included
- <define> ... </define> Dictionary of constant expressions and varables
- <materials> ... </materials> Additional material definitions
- <display> ... </display> Definition of visualization attributes
- <detectors> ... </detectors> Section with sub-detector definitions
- <readouts> ... </readouts> Section with readout structure definitions
- <limits> ... </limits> Definition of limit sets for Geant4
- <fields> ... </fields> Field definitions
-</lccdd>
-\end{code}
-
-\noindent
-The root tag of the XML tree is {\tw{lccdd}}. This name is fixed.
-In the following the content of the various sections is discussed.
-The XML sections are filled with the following information:
-\begin{itemize}
-\item {\bf{The \tw{<info>} sub-tree}} contains auxiliary information about
- the detector model:
-
-\begin{code}
-<info name="clic_sid_cdr"
- title="CLIC Silicon Detector CDR"
- author="Christian Grefe"
- url="https://twiki.cern.ch/twiki/bin/view/CLIC/ClicSidCdr"
- status="development"
- version="$Id: compact.xml 665 2013-07-02 18:49:26Z markus.frank $">
- <comment>The compact format for the CLIC Silicon Detector used
- for the conceptual design report</comment>
-</info>
-\end{code}
-
-\item {\bf{The \tw{<includes>} section}} allows to include GDML sub-trees containing
- material descriptions. These files are processed {\it{before}} the
- detector constructors are called:
-
-\begin{code}
-<includes>
- <gdmlFile ref="elements.xml"/>
- <gdmlFile ref="materials.xml"/>
- ...
-</includes>
-\end{code}
-
-\item {\bf{The \tw{<define>} section}} contains all variable definitions
- defined by the client to simplify the definition of subdetectors.
- These name-value pairs are fed to the expression evaluator
- and MUST evaluate to a number. String constants are not allowed.
- These variables can be combined to formulas e.g. to automatically
- re-dimension subdetectors if boundaries are changed:
-
-\begin{code}
-<define>
- <constant name="world_side" value="30000"/>
- <constant name="world_x" value="world_side"/>
- <constant name="world_y" value="world_side"/>
- <constant name="world_z" value="world_side"/>
- ....
-</define>
-\end{code}
-
-\item {\bf{The $\tt<materials>$ sub-tree}} contains additional materials, which
- are not contained in the default materials tables. The snippet below shows
- an example to extend the table of known materials. For more details please see
- section~\ref{sec:compact-material-description}.
-
-\begin{code}
-<materials>
- <!-- The description of an atomic element or isotope -->
- <element Z="30" formula="Zn" name="Zn" >
- <atom type="A" unit="g/mol" value="65.3955" />
- </element>
- ...
- <!-- The description of a new material -->
- <material name="CarbonFiber_15percent">
- ...
- </material>
- ...
-</materials>
-\end{code}
-
-\item {\bf{The visualization attributes}} are defined in the $\tt<display>$ section.
- Clients access visualization settings by name. The possible attributes are shown
- below and essentially contain the RGB color values, the visibility and the drawing style:
-
-\begin{code}
-<display>
- <vis name="InvisibleNoDaughters" showDaughters="false" visible="false"/>
- <vis name="SiVertexBarrelModuleVis"
- alpha="1.0" r="1" g="1" b="0.6"
- drawingStyle="solid"
- showDaughters="true"
- visible="true"/>
- ....
-</display>
-\end{code}
-
-\item {\bf{Limisets}} contain parameters passed to Geant4:
-
-\begin{code}
-<limits>
- <limitset name="cal_limits">
- <limit name="step_length_max" particles="*" value="5.0" unit="mm" />
- </limitset>
-</limits>
-\end{code}
-
-\item {\bf{The $\tt<detectors>$}} section contains subtrees of the type $\tt<detector>$
- which contain all parameters used by the $detector constructors$
- to actually expand the geometrical structure. Each subdetector has a name and a type,
- where the type is used to call the proper constructor plugin. If the subdetector
- element is sensitive, a forward reference to the corresponding readout structure
- is mandatory. The remaining parameters are user defined:
-
-\begin{code}
-<detectors>
- <detector id="4" name="SiTrackerEndcap" type="SiTrackerEndcap" readout="SiTrackerEndcapHits">
- <comment>Outer Tracker Endcaps</comment>
- <module name="Module1" vis="SiTrackerEndcapModuleVis">
- <trd x1="36.112" x2="46.635" z="100.114/2" />
- <module_component thickness="0.00052*cm" material="Copper" />
- <module_component thickness="0.03*cm" material="Silicon" sensitive="true" />
- ...
- </module>
- ...
- <layer id="1">
- <ring r="256.716" zstart="787.105+1.75" nmodules="24" dz="1.75" module="Module1"/>
- <ring r="353.991" zstart="778.776+1.75" nmodules="32" dz="1.75" module="Module1"/>
- <ring r="449.180" zstart="770.544+1.75" nmodules="40" dz="1.75" module="Module1"/>
- </layer>
- ...
- </detector>
-</detectors>
-\end{code}
-
-\item {\bf{The $\tt<readouts>$ section}} defined the encoding of sensitive volumes
- to so-called cell-ids, which are in \DDhep 64-bit integer numbers. The encoding
- is subdetector dependent with one exception: to uniquely identity each subdetector,
- the width of the system field must be the same. The usage of these data is
- discussed in section~\ref{dd4hep-sensitive-detectors}.
-\begin{code}
-<readouts>
- <readout name="SiTrackerEndcapHits">
- <id>system:8,barrel:3,layer:4,module:14,sensor:2,side:32:-2,strip:20</id>
- </readout>
- ...
-</readouts>
-\end{code}
-
-\item {\bf{Electromagnetic fields}} are described in the $\tt<fields>$ section.
- There may be several fields present. In \DDhep the resulting field vectors
- may be both electric and magnetic. The strength of the overall field is calculated
- as the superposition of the individual components:
-\begin{code}
-<fields>
- <field name="GlobalSolenoid" type="solenoid"
- inner_field="5.0*tesla"
- outer_field="-1.5*tesla"
- zmax="SolenoidCoilOuterZ"
- outer_radius="SolenoidalFieldRadius">
- </field>
- ...
-</fields>
-\end{code}
-\end{itemize}
-
-
-
-\newpage
-%=============================================================================
-\subsection{Material Description}
-\label{sec:compact-material-description}
-%=============================================================================
-\noindent
-Materials are needed by logical volumes. They are defined as isotopes,
-elements or mixtures.
-Elements can optionally be composed of isotopes. Composition is always done
-by specifying the fraction of the mass. Mixtures can be composed of elements
-or other mixtures. For a mixture the user can specify composition either by
-number of atoms or by fraction of mass. The materials sub-tree
-in section~\ref{sec:compact-xml-structure}
-shows the representation of an element, a simple material and a
-composite material in the XML format identical to GDML~\cite{bib:GDML}.
-The snippet below shows how to define new material instances:
-\begin{code}
-<materials>
- ...
- <!-- (1) The description of an atomic element or isotope -->
- <element Z="30" formula="Zn" name="Zn" >
- <atom type="A" unit="g/mol" value="65.3955" />
- </element>
- <!-- (2) A composite material -->
- <material name="Kapton">
- <D value="1.43" unit="g/cm3" />
- <composite n="22" ref="C"/>
- <composite n="10" ref="H" />
- <composite n="2" ref="N" />
- <composite n="5" ref="O" />
- </material>
- <!-- (3) A material mixture -->
- <material name="PyrexGlass">
- <D type="density" value="2.23" unit="g/cm3"/>
- <fraction n="0.806" ref="SiliconOxide"/>
- <fraction n="0.130" ref="BoronOxide"/>
- <fraction n="0.040" ref="SodiumOxide"/>
- <fraction n="0.023" ref="AluminumOxide"/>
- </material>
- ...
-</materials>
-\end{code}
-The $\tt<materials>$ sub-tree contains additional materials, which
-are not contained in the default materials tables. The snippet above shows
-different kinds of materials:
-\begin{description}
-\item{(1)} Atomic elements as they are in the periodic table. The number of elements
- is finite. It is unlikely any client will have to extend the known elements.
-\item{(2)} Composite materials, which consists of one or several elements
- forming a molecule. These materials have a certain density under normal
- conditions described in the child element \tw{D}.
- For each \tw{composite} the attribute \tw{ref} denotes the element type by name,
- the attribute \tw{n} denotes the atomic multiplicity.
- Typically each of the elements in (1) also forms such a material representing
- objects which consist of pure material like e.g. iron magnet yokes or copper wires.
-\item{(3)} Last there are mixtures of composite materials to describe
- for example alloys, solutions or other mixtures of solid materials.
- This is the type of material used to actually create mechanical structures
- forming the assembly of an experiment. Depending on the maufactering
- these materials have a certain density (\tw{D}) and are composed
- of numerous molecules contributing to the resulting material with a given
- \tw{fraction}. The sum of all fractions (attribute \tw{n}) is 1.0.
-\end{description}
-"Real" materials i.e. those you can actually touch are described in TGeo
-by the class \tgeo{TGeoMedium}{\tt{TGeoMedium}}
-\footnote{Typical beginner's mistake: Do not mix up the
-two classes \tw{TGeoMaterial} and \tw{TGeoMedium}!
-The material to define volumes is of type \tw{TGeoMedium}, which also includes the
-description of the material's finish.}.
-Materials are not constructed by any client. Materials and elements are
-either already present in the the corresponding tables of the ROOT geometry
-package or they are added during the interpretation of the XML input.
-Clients access the description of material using the \tw{LCDD} interface.
-
-
-\newpage
-\begin{figure}[t]
- \begin{center}
- \includegraphics[width=160mm] {DD4hep-solids}
- \caption{Extensions may be attached to common Detector Elements which
- extend the functionality of the common DetElement
- class and support e.g. caching of precomputed values.}
- \label{fig:dd4hep-solids}
- \end{center}
- \vspace{-0.6cm}
-\end{figure}
-%=============================================================================
-\subsection{Shapes}
-\label{dd4hep-basic-shapes}
-%=============================================================================
-\noindent
-Shapes are abstract objects with a bounding surface and fixed dimensions.
-There are primitive, atomic shapes
-and complex boolean shapes as shown in Figure~\ref{fig:dd4hep-solids}.
-TGeo and similarly Geant4 offer a whole palette of
-primitive shapes, which can be used to construct more complex shapes:
-\begin{itemize}\itemcompact
-\item \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_box.html}{Box} shape
- represented by the \tgeo{TGeoBBox}{\tt TGeoBBox} class. To create a new box
- object call one of the following constructors:
-\begin{code}
-/// Constructor to be used when creating an anonymous new box object
-Box(double x, double y, double z);
-/// Constructor to be used when creating an anonymous new box object
-template<typename X, typename Y, typename Z> Box(const X& x, const Y& y, const Z& z);
-\end{code}
-\item \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_sphere.html}{Sphere} shape
- represented by the \tgeo{TGeoSphere}{\tt TGeoSphere} class. To create a new sphere
- object call one of the following constructors:
-\begin{code}
-\end{code}
-\item \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_cone.html}{Cone} shape
- represented by the \tgeo{TGeoCone}{\tt TGeoCone} class. To create a new cone
- object call one of the following constructors:
-\begin{code}
-/// Constructor to create a new anonymous object with attribute initialization
-Cone(double z,double rmin1,double rmax1,double rmin2,double rmax2);
-template<typename Z, typename RMIN1, typename RMAX1, typename RMIN2, typename RMAX2>
-Cone(const Z& z, const RMIN1& rmin1, const RMAX1& rmax1, const RMIN2& rmin2, const RMAX2& rmax2);
-\end{code}
-\item \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_cone_segment.html}{Cone segment} shape
- represented by the \tgeo{TGeoConeSeg}{\tt TGeoConeSeg} class. To create a new cone segment
- object call one of the following constructors:
-\begin{code}
-/// Constructor to create a new ConeSegment
-ConeSegment(double dz, double rmin1, double rmax1, double rmin2, double rmax2,
- double phi1=0.0, double phi2=2.0*M_PI);
-\end{code}
-\item \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_polycone.html}{Polycone} shape
- represented by the \tgeo{TGeoPcon}{\tt TGeoPcon} class. To create a new polycone
- object call one of the following constructors:
-\begin{code}
-/// Constructor to create a new polycone object
-Polycone(double start, double delta);
-followed by a call to:
-void addZPlanes(const std::vector<double>& rmin,
- const std::vector<double>& rmax,
- const std::vector<double>& z);
-/// Constructor to create a new polycone object. Add at the same time all Z planes
-Polycone(double start, double delta,
- const std::vector<double>& rmin,
- const std::vector<double>& rmax,
- const std::vector<double>& z);
-\end{code}
-\item \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_tube.html}{Tube segment} shape
- represented by the \tgeo{TGeoTubeSeg}{\tt TGeoTubeSeg} class. To create a new tube segment
- object call one of the following constructors:
-\begin{code}
-Tube(double rmin, double rmax, double z, double deltaPhi=2*M_PI)
-Tube(double rmin, double rmax, double z, double startPhi, double deltaPhi)
-
-template<typename RMIN, typename RMAX, typename Z, typename DELTAPHI>
-Tube(const RMIN& rmin, const RMAX& rmax, const Z& z, const DELTAPHI& deltaPhi)
-
-template<typename RMIN, typename RMAX, typename Z, typename STARTPHI, typename DELTAPHI>
-Tube(const std::string& name, const RMIN& rmin, const RMAX& rmax, const Z& z,
- const STARTPHI& startPhi, const DELTAPHI& deltaPhi)
-\end{code}
-\item \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_trapezoid.html}{Trapezoid} shape
- represented by the \tgeo{TGeoTrd2}{\tt TGeoTrd} class. To create a new trapezoid
- object call one of the following constructors:
-\begin{code}
-/// Constructor to create a new anonymous object with attribute initialization
-Trapezoid(double x1, double x2, double y1, double y2, double z);
-\end{code}
-\item \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_trap.html}{Trap} shape
- represented by the \tgeo{TGeoTrap}{\tt TGeoTrap} class. To create a new trap
- object call one of the following constructors:
-\begin{code}
-/// Constructor to create a new anonymous object with attribute initialization
-Trap(double z,double theta,double phi,
- double y1,double x1,double x2,double alpha1,
- double y2,double x3,double x4,double alpha2);
-/// Constructor to create a new anonymous object for right angular wedge from STEP (Se G4 manual for details)
-Trap( double pz, double py, double px, double pLTX);
-\end{code}
-\item \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_torus.html}{Torus} shape
- represented by the \tgeo{TGeoTorus}{\tt TGeoTorus} class. To create a new torus
- object call one of the following constructors:
-\begin{code}
-/// Constructor to create a new anonymous object with attribute initialization
-Torus(double r, double rmin, double rmax, double phi=M_PI, double delta_phi=2.*M_PI);
-\end{code}
-\item \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_paraboloid.html}{Paraboloid} shape
- represented by the \tgeo{TGeoParaboloid}{\tt TGeoParaboloid} class. To create a new paraboloid
- object call one of the following constructors:
-\begin{code}
-/// Constructor to create a new anonymous object with attribute initialization
-Paraboloid(double r_low, double r_high, double delta_z);
-\end{code}
-\item \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_polyhedra_regular.html}{Regular Polyhedron} shape
- represented by the \tgeo{TGeoPgon}{\tt TGeoPgon} class. To create a new polyhedron
- object call one of the following constructors:
-\begin{code}
-/// Constructor to create a new object. Phi(start)=0, deltaPhi=2PI, Z-planes at +-zlen/2
-PolyhedraRegular(int nsides, double rmin, double rmax, double zlen);
-/// Constructor to create a new object. Phi(start)=0, deltaPhi=2PI, Z-planes at zplanes[0],[1]
-PolyhedraRegular(int nsides, double rmin, double rmax, double zplanes[2]);
-/// Constructor to create a new object with phi_start, deltaPhi=2PI, Z-planes at +-zlen/2
-PolyhedraRegular(int nsides, double phi_start, double rmin, double rmax, double zlen);
-\end{code}
-\end{itemize}
-
-\noindent
-Besides the primitive shapes three types of boolean shapes (described in TGeo by the
-\tgeo{TGeoCompositeShape}{{\tt{TGeoCompositeShape}}} class)
-are supported:
-
-\begin{itemize}\itemcompact
-\item \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_union_solid.html}{\tt UnionSolid} objects representing the union,
-\item \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_intersection_solid.html}{\tt IntersectionSolid} objects representing the intersection,
-\item \detdesc{html/struct_d_d4hep_1_1_geometry_1_1_subtraction_solid.html}{\tt SubtractionSolid} objects representing the subtraction,
-\end{itemize}
-
-\noindent
-of two other primitive or complex shapes. To build a boolean shape, the
-second shape is transformed in 3-dimensional space before the boolean
-operation is applied. The 3D transformations are described by objects from the
-ROOT::Math library and are supplied at construction time.
-Such a transformation as shown in the code snippet below may be
-
-\begin{itemize}\itemcompact
-\item The identity transformation. Then no transformation object needs to be provided (see line 2).
-
-\item A translation only described by a \tw{Position} object (see line 4)
-
-\item A 3-fold rotation first around the Z-axis, then around the Y-axis and finally around the X-axis.
- For transformation operations of this kind a \tw{RotationZYX} object must be supplied (see line 6).
-
-\item A generic 3D rotation matrix should be applied to the second shape. Then a \tw{Rotation3D}
- object must be supplied (see line 8).
-
-\item Finally a generic 3D transformation (translation+rotation) may be applied using a
- \tw{Transform3D} object (see line 10).
-\end{itemize}
-
-\noindent
-All three boolean shapes
-have constructors as shown here for the UnionSolid:
-\begin{code}
- /// Constructor to create a new object. Position is identity, Rotation is identity-rotation!
- UnionSolid(const Solid& shape1, const Solid& shape2);
- /// Constructor to create a new object. Placement by position, Rotation is identity-rotation!
- UnionSolid(const Solid& shape1, const Solid& shape2, const Position& pos);
- /// Constructor to create a new object. Placement by a RotationZYX within the mother
- UnionSolid(const Solid& shape1, const Solid& shape2, const RotationZYX& rot);
- /// Constructor to create a new object. Placement by a generic rotoation within the mother
- UnionSolid(const Solid& shape1, const Solid& shape2, const Rotation3D& rot);
- /// Constructor to create a new object. Placement by a generic transformation within the mother
- UnionSolid(const Solid& shape1, const Solid& shape2, const Transform3D& pos);
-\end{code}
-
-\paragraph{Shape factories} Sometimes it is useful to create shapes in an "abstract" way
-e.g. to define areas in the detector. To create such shapes a factory method was implemented,
-which allows to create a valid shape handle given a valid XML element providing the
-required attributes. The factory methods are invoked using from XML elements of the following form:
-\begin{unnumberedcode}
- <some_element type="shape-type" .... args ....>
-\end{unnumberedcode}
-The shape is then constructed using the XML component object:
-\begin{unnumberedcode}
-#include "DD4hep/DetFactoryHelper.h"
-
- xml_h e = <shape-element>;
- Box box = xml_comp_t(e).createShape();
- if ( !box.isValid() ) { ...handle error ... }
-\end{unnumberedcode}
-The required arguments for the various shapes are then:
-\begin{itemize}
-\item For a Box:
-\vspace{-0.2cm}
-\begin{unnumberedcode}
- <some_element type="Box" x="x-value" y="y-value" z="z-value"/>
-\end{unnumberedcode}
-fulfiling a constructor of the type: $Box(dim.dx(),~dim.dy(),~dim.dz())$.
-
-\item For a Polycone:
-\vspace{-0.2cm}
-\begin{unnumberedcode}
- <some_element type="Polycone" start="start-phi-value" deltaphi="delta-phi-value">
- <zplane z="z-value" rmin="rmin-value" rmax="rmax-value"/>
- <zplane z="z-value" rmin="rmin-value" rmax="rmax-value"/>
- .... any number of Z-planes ....
- <zplane z="z-value" rmin="rmin-value" rmax="rmax-value"/>
- </some_element>
-\end{unnumberedcode}
-
-\item For a ConeSegment the following constructor must be fulfilled:\\
- $ ConeSegment(e.rmin(0.0),~e.rmax(),~e.z(0.0),~e.startphi(0.0),~e.deltaphi(2*M\_PI))$,\\
-where the above default values for the XML attributes $rmin, z, startphi$ and
-$deltaphi$ are used if not explicitly stated in the XML element $e$.
-
-\item For a Tube the constructor is:\\
- $ Tube(e.rmin(0.0),~e.rmax(),~e.z(0.0),~e.startphi(0.0),~e.deltaphi(2*M\_PI))$.
-
-\item For a Cone the constructor is:\\
- $double rmi1 = e.rmin1(0.0), rma1 = e.rmax1();$\\
- $ Cone(e.z(0.0),~rmi1,rma1,~e.rmin2(rmi1),~e.rmax2(rma1))$.
-
-\item For a Trap the constructor is:\\
- if $dz$ is specified: $ Trap(e.dz(),~e.dy(),~e.dx(),_toDouble(_Unicode(pLTX)))$
- Otherwise: \\
- $ Trap(e.z(0.0),~e.theta(),~e.phi(0),~e.y1(),~e.x1(),~e.x2(),~e.alpha(),
- e.y2(),~e.x3(),~e.x4(),~e.alpha2())$.
-
-\item For a Trapezoid the constructor is:\\
- $ Trapezoid(e.x1(),~e.x2(),~e.y1(),~e.y2(),~e.z(0.0))$.
-
-\item For a Torus the constructor is:\\
- $ Torus(e.r(),~e.rmin(),~e.rmax(),~e.phi(M\_PI),~e.deltaphi(2.*M\_PI))$.
-
-\item For a Sphere the constructor is:\\
- $ Sphere(e.rmin(),~e.rmax(),~e.deltatheta(M\_PI),~e.phi(0e0),e.deltaphi(2.*M\_PI))$.
-
-\item For a Paraboloid the constructor is:\\
- $ Paraboloid(e.rmin(0.0),~e.rmax(),~e.dz())$.
-
-\item For a PolyhedraRegular the constructor is:\\
- $ PolyhedraRegular(e.numsides(),~e.rmin(),~e.rmax(),~e.dz())$.
-
-\end{itemize}
-
-\newpage
-%=============================================================================
-\subsection{Volumes and Placements}
-%=============================================================================
-\noindent
-The detector geometry is described by a hierarchy of volumes and their
-corresponding placements. Both, the TGeo package and Geant4~\cite{bib:geant4}
-are following effectively the same ideas ensuring an easy conversion from
-TGeo to Geant4 objects for the simulation application.
-\noindent
-A volume is an unplaced solid de\-scribed in terms of a primitive
-shape or a boolean operation of solids, a material and a number of
-placed sub-volumes (placed volumes) inside. The class diagram showing the
-relationships between volumes and placements, solids and materials is shown
-in Figure~\ref{fig:dd4hep-detector-model}.
-\noindent
-It is worth noting, that any volume has children, but no parent or "mother"
-volume. This is a direct consequence of the requirement to re-use volumes
-and place the same volume arbitrarily often. Only the act of placing a volume
-defines the relationship to the next level parent volume.
-The resulting geometry tree is very effective, simple and convenient to
-describe the detector geometry hierarchy starting from the top level volume
-representing e.g. the experiment cavern down to the very detail of the detector
-e.g. the small screw in the calorimeter. The top level volume is the very only
-volume without a placement. All geometry calculations, computations are always
-performed within the local coordinate system of the volume.
-The following example code shows how to create
-a volume which consists of a given material and with a shape. The created volume
-is then placed inside the mother-volume using the local coordinate system of the
-mother volume:
-
-\begin{code}
- Volume mother = ....ampercent
-
- Material mat (lcdd.material("Iron"));
- Tube tub (rmin, rmax, zhalf);
- Volume vol (name, tub, mat);
- Transform3D tr (RotationZYX(rotz,roty,rotx),Position(x,y,z));
- PlacedVolume phv = mother.placeVolume(vol,tr);
-\end{code}
-
-\noindent
-The volume has the shape of a tube and consists of iron.
-Before being placed, the daughter volume is transformed within
-the mother coordinate system according to the requested transformation.
-The example also illustrates how to access $Material$ objects from the
-$LCDD$ interface.
-
-\noindent
-The {\tt{Volume}} class provides several possibilities to declare
-the required space transformation necessary to place a daughter volume
-within the mother:
-\begin{itemize}\itemcompact
-\item to place a daughter volume unrotated at the origin of the mother, the
-transformation is the identity. Use the following call to place the daughter:
-\begin{unnumberedcode}
-PlacedVolume placeVolume(const Volume& vol) const;
-\end{unnumberedcode}
-\item If the positioning is described by a simple translation, use:
-\begin{unnumberedcode}
-PlacedVolume placeVolume(const Volume& vol, const Position& pos) coampercentnst;
-\end{unnumberedcode}
-\item In case the daughter should be rotated first around the Z-axis,
- then around the Y-axis and finally around the X-axis place the daughter
- using this call:
-\begin{unnumberedcode}
-PlacedVolume placeVolume(const Volume& vol, const RotationZYX& rot) const;
-\end{unnumberedcode}
-\item If the full 3-dimensional rotation matrix is known use:
-\begin{unnumberedcode}
-PlacedVolume placeVolume(const Volume& vol, const Rotation3D& rot) const;
-\end{unnumberedcode}
-\item for an entirely unconstrained placement place the daughter providing
- a Transform3D object:
-\begin{unnumberedcode}
-PlacedVolume placeVolume(const Volume& volume, const Transform3D& tr) const;
-\end{unnumberedcode}
-\end{itemize}
-
-\noindent
-For more details of the \tw{Volume} and the \tw{PlacedVolume} classes please see the
-\detdesc{html/_volumes_8h.html}{header file}.
-
-\noindent
-One volume like construct is special: the assembly constructs.
-Assemblies are volumes without shapes. The "assembly" shape does not
-own a own surface by itself, but rather defines it's surface and
-bounding box from the contained children.
-In this corner also the implementation concepts between TGeo and Geant4 diverge.
-Whereas TGeo handles assemblies very similar to real volumes, in Geant4
-assemblies are purely artificial and disappear at the very moment volumes
-are placed.
-
-\newpage
-%=============================================================================
-\subsection{Detector Elements}
-\label{sec:dd4hep-user-manual-detector-elements}
-%=============================================================================
-\begin{figure}[b]
- \begin{center}
- \includegraphics[width=160mm] {DD4hep-detelement-drawing}
- \caption{The basic layout of the \tw{DetElement} class aggregating
- all data entities necessary to process data.}
- \label{fig:dd4hep-user-manual-detelement-drawing}
- \end{center}
- \vspace{-0.6cm}
-\end{figure}
-
-\noindent
-Detector elements (class \tw{DetElement}) are entities which represent
-subdetectors or sizable parts of a subdetector.
-As shown in Figure~\ref{fig:dd4hep-user-manual-detelement-drawing},
-a \tw{DetElement} instance has the means to provide to clients information about
-
-\begin{itemize}\itemcompact
-\item generic properties like the detector type or the path within the \tw{DetElement}s
- hierarchy:
-\begin{code}
- /// Access detector type (structure, tracker, calorimeter, etc.).
- std::string type() const;
- /// Path of the detector element (not necessarily identical to placement path!)
- std::string path() const;
-\end{code}
-
-\item the detector hierarchy by exposing its children. The hierarchy may be
- accessed with the following API:
-\begin{code}
- /// Add new child to the detector structure
- DetElement& add(DetElement sub_element);
- /// Access to the list of children
- const Children& children() const;
- /// Access to individual children by name
- DetElement child(const std::string& name) const;
- /// Access to the detector elements's parent
- DetElement parent() const;
-\end{code}
-
-\item its placement within the overall experiment if it represents an
- entire subdetector or its placement with respect to its parent
- if the \tw{DetElement} represents a part of a subdetector.
- The placement path is the fully qualified path of placed volumes
- from the top level volume to the placed detector element and may
- serve as a shortcut for the eqnarrayment implementation:
-\begin{code}
- /// Access to the full path to the placed object
- std::string placementPath() const;
- /// Access to the physical volume of this detector element
- PlacedVolume placement() const;
- /// Access to the logical volume of the daughter placement
- Volume volume() const;
-\end{code}
-
-\item information about the environmental conditions etc. (\tw{conditons}):
-\begin{code}
- /// Access to the conditions information
- Conditions conditions() const;
-\end{code}
-
-\item eqnarrayment information:
-\begin{code}
- /// Access to the eqnarrayment information
- eqnarrayment eqnarrayment() const;
-\end{code}
-
-\item convenience information such as cached transformations
- to/from the top level volume, to/from the parent \tw{DetElement}
- and to/from another \tw{DetElement} in the hierarchy above:
-\begin{code}
- /// Transformation from local coordinates of the placed volume to the world system
- bool localToWorld(const Position& local, Position& global) const;
- /// Transformation from world coordinates of the local placed volume coordinates
- bool worldToLocal(const Position& global, Position& local) const;
-
- /// Transformation from local coordinates of the placed volume to the parent system
- bool localToParent(const Position& local, Position& parent) const;
- /// Transformation from world coordinates of the local placed volume coordinates
- bool parentToLocal(const Position& parent, Position& local) const;
-
- /// Transformation from local coordinates of the placed volume to arbitrary parent system set as reference
- bool localToReference(const Position& local, Position& reference) const;
- /// Transformation from world coordinates of the local placed volume coordinates
- bool referenceToLocal(const Position& reference, Position& local) const;
-
- /// Set detector element for reference transformations.
- /// Will delete existing reference transformation.
- DetElement& setReference(DetElement reference);
-\end{code}
-
-\item User extension information as described in section~\ref{sec:dd4hep-user-manual-data-extensions}:
-\begin{code}
- /// Extend the detector element with an arbitrary structure accessible by the type
- template <typename IFACE, typename CONCRETE> IFACE* addExtension(CONCRETE* c);
- /// Access extension element by the type
- template <class T> T* extension() const;
-\end{code}
-
-\end{itemize}
-
-
-\newpage
-%=============================================================================
-\subsection{Sensitive Detectors}
-\label{sec:dd4hep-user-manual-sensitive-detectors}
-%=============================================================================
-
-\noindent
-Though the concept of sensitive detectors comes from Geant4 and simulation
-activities, in DD4hep the sensitive detectors are the client interface to
-access the readout description (class \tw{Readout}) with its
-segmentation of sensitive elements (class \tw{Segmentation}) and
-the description of hit decoders (class \tw{IDDescriptors}).
-As shown in Figure~\ref{fig:dd4hep-sensitive-detectors}, these object
-instances are required when reconstructing data from particle collisions.
-
-\noindent
-Besides the access to data necessary for reconstruction the sensitive detector
-also hosts Region setting (class \tw{Region} and sets of cut limits
-(class \tw{LimitSets}) used to configure the Geant4 simulation toolkit.
-The following code snippet shows the accessors of the
-\tw{SensitiveDetector} class to obtain the corresponding
-information~\footnote{The methods to set the data are not shown here.}:
-
-
-\vspace{0.3cm}
-\begin{code}
- struct SensitiveDetector: public Ref_t {
- /// Access the hits collection name
- const std::string& hitsCollection() const;
- /// Access readout structure of the sensitive detector
- Readout readout() const;
- /// Access to the region setting of the sensitive detector (not mandatory)
- Region region() const;
- /// Access to the limit set of the sensitive detector (not mandatory).
- LimitSet limits() const;
-
- /// Extend the sensitive detector element with an arbitrary structure accessible by the type
- template <typename IFACE, typename CONCRETE> IFACE* addExtension(CONCRETE* c);
- /// Access extension element by the type
- template <class T> T* extension() const;
- };
-\end{code}
-
-\begin{figure}[h]
- \begin{center}
- \includegraphics[width=140mm] {DD4hep-sensitive-detectors}
- \caption{The structure of DD4hep sensitive detectors.}
- \label{fig:dd4hep-sensitive-detectors}
- \end{center}
- \vspace{-0.6cm}
-\end{figure}
-
-
-\noindent
-Sensitive detector objects are automatically creating using the information
-of the \tw{<readout>} section of the XML file if a subdetector is sensitive
-and references a valid readout entry.
-In the detector constructor (or any time later) clients
-may add additional information to a sensitive detector object using
-an extension mechanism similar to the extension mechanism for
-detector elements mentioned earlier.
-
-
-\noindent
-Volumes may be shared and reused in several placements. In the parallel
-hierarchy of detector elements as shown in Figure~\ref{fig:dd4hep-hierarchies},
-the detector elements may reference unambiguously the volumes of their
-respective placements, but not the reverse.
-However, the sensitive detector setup is a single instance per subdetector.
-Hence it may be referenced by all sensitive Volumes of one subdetector.
-In the following chapters the access to the readout structure is described.
-
-%=============================================================================
-\subsection{Description of the Readout Structure}
-\label{sec:dd4hep-manual-readout-description}
-%=============================================================================
-\noindent
-The \tw{Readout} class describes the detailed structure of a sensitve volume.
-The for example may be the layout of strips or pixels in a silicon detector
-i.e. the description of entities which would not be modeled using individual
-volumes and placements though this would theoretically feasible.
-Each sensitive element is segmented according to the \tw{Segmentation} object
-and hits resulting from energy depositions in the sensitive volume are
-encoded using the \tw{IDDescriptor} object.
-
-\begin{figure}[h]
- \begin{center}
- \includegraphics[width=100mm] {DD4hep-readout}
- \caption{The basic components to describe the \tw{Readout} structure
- of a subdetector. }
- \label{fig:dd4hep-sensitive-detectors}
- \end{center}
- \vspace{-0.6cm}
-\end{figure}
-
-%=============================================================================
-\subsubsection{CellID Descriptors}
-\label{sec:dd4hep-manual-readout-iddescriptors}
-%=============================================================================
-\noindent
-\tw{IDDescriptor}s define the encoding of sensitive volumes to uniquely identify
-the location of the detector response. The encoding defines a bit-field with
-the length of 64 bits. The first field is mandatory called \tw{system} and
-identifies the subdetector. All other fields define the other volumes in the
-hierarchy. The high bits are not necessarily mapped to small daughter volumes,
-but may simply identify a logical segmentation such as the \tw{strip} \tw{number}
-within a wafer of a vertex detector as shown in the following XML snippet:
-\begin{code}
-<readouts>
- <readout name="SiVertexEndcapHits">
- <id>system:8,barrel:3,layer:4,module:14,sensor:2,side:32:-2,strip:24</id>
- </readout>
-<readouts>
-\end{code}
-These identifiers are the data input to
-\tw{segmentation classes}~\ref{sec:dd4hep-manual-readout-segmentations},
-which define a user friendly API to en/decode the detector response.
-
-%=============================================================================
-\subsubsection{Segmentations}
-\label{sec:dd4hep-manual-readout-segmentations}
-%=============================================================================
-\noindent
-Segementations define the user API to the low level interpretation of
-the energy deposits in a subdetector. For technical reasons and partial
-religious reasons are the segmentation implementation not part of the \DDhep
-toolkit, but an independent package call
-\tw{DDSegmentation}~\cite{bib:DDSegmentations}. Though the usage is an
-integral part of DD4hep.
-
-\subsubsection{Volume Manager}
-%=============================================================================
-\noindent
-The \tw{VolumeManager} is a tool to seek a lookup table of placements of
-sensitive volumes and their corresponding unique volume identifier, the
-\tw{cellID}. The volume manager analyzes - once the geometry is closed -
-the hierarchical tree and stores the various placements in the hierarchy
-with respect to their identifiers. In other words the the tree is
-reused volumes shown e.g. in Figure~\ref{fig:dd4hep-hierarchies} is
-degenerated according to the full pathes of the various volumes. This
-use case is very common to reconstruction and analysis applications
-whenever a given raw-data (aka "hit") element must be related to its
-geometrical location.
-
-\noindent
-Figure~\ref{fig:dd4hep-user-manual-volmgr} shows the design diagram of this component:
-\begin{figure}[h]
- \begin{center}
- \includegraphics[width=170mm] {DD4hep-volmgr}
- \caption{Extensions may be attached to common Detector Elements which
- extend the functionality of the common DetElement
- class and support e.g. caching of precomputed values.}
- \label{fig:dd4hep-user-manual-volmgr}
- \end{center}
-\end{figure}
-
-\noindent
-To optimize the access of complex subdetector structures, is the volume-identifier
-map split and the volumes of each each subdetector is stored in a separate map.
-This optimization however is transparent to clients. The following code extract
-from the header files lists the main client routines to extract volume information
-given a known cellID:
-\begin{code}
- /// Lookup the context, which belongs to a registered physical volume.
- Context* lookupContext(VolumeID volume_id) const;
- /// Lookup a physical (placed) volume identified by its 64 bit hit ID
- PlacedVolume lookupPlacement(VolumeID volume_id) const;
- /// Lookup a top level subdetector detector element
- /// according to a contained 64 bit hit ID
- DetElement lookupDetector(VolumeID volume_id) const;
- /// Lookup the closest subdetector detector element in the hierarchy
- /// according to a contained 64 bit hit ID
- DetElement lookupDetElement(VolumeID volume_id) const;
- /// Access the transformation of a physical volume to the world coordinate system
- const TGeoMatrix& worldTransformation(VolumeID volume_id) const;
-\end{code}
-
-%=============================================================================
-\subsubsection{Static Electric and Magnetic Fields}
-\label{sec:dd4hep-manual-static-fields}
-
-\noindent
-The generic field is described by a structure of any field type (electric or magnetic)
-with field components in Cartesian coordinates.
-The overlay field is the sum of several magnetic of electric field components
-and the resulting field vectors are computed by the vector addition
-of the individual components. The available components are described in the following.
-If necessary new field implementations may be added at any time: they are
-instantiated when necessary by the factory mechanism.
-Fields are described in the compact model within the {\tt{<fields>}} tags the
-following examople shows:
-\begin{code}
- <fields>
- <field name="MyMagnet" type="solenoid" .... />
- </fields>
-\end{code}
-The actual components are defined one by one within the {\tt{<field>}} tags.
-
-\paragraph{Constant Electric or Magnetic Fields} are defined as follows:
-\begin{code}
- <field name="MyMagnet" type="ConstantField" field="electric">
- <strength x="x-val" y="y-val" z="z-val"/>
- </field>
-\end{code}
-The {\tw{field}} attribute accepts take the values {\tw{[electric,magnetic]}}
-depending on it's nature.
-
-\paragraph{Magnetic Dipoles} are defined as follows:
-\begin{code}
- <field name="MyMagnet" type="DipoleMagnet"
- rmax="50*cm"
- zmin="0*cm"
- zmax="50*cm">
- <dipole_coeff>1.0*tesla</dipole_coeff>
- <dipole_coeff>0.1*tesla/pow(cm,1)</dipole_coeff>
- <dipole_coeff>0.01*tesla/pow(cm,2)</dipole_coeff>
- </field>
-\end{code}
-
-\paragraph{Magnetic Multipole Fields} are developed according to their
-approximation using the multipole coefficients.
-The dipole is assumed to be horizontal as it is used for bending beams in large colliders
-ie. the dipole field lines are vertical.
-
-The different momenta are given by: $ B_y + i B_x $\footnote{
-See for detailed documentation about multipoles:\\
-http://cas.web.cern.ch/cas/Belgium-2009/Lectures/PDFs/Wolski-1.pdf \\
-http://cas.web.cern.ch/cas/Bulgaria-2010/Talks-web/Brandt-1-web.pdf \\
-https://en.wikipedia.org/wiki/Multipole\_magnet
-}, where:
-\begin{eqnarray*}
- B_y + i B_x &=& C_n (x + iy)^{n-1} \\
-B_{sum} = B_y + i B_x &=& \Sigma_{n=1..m} (b_n + ia_n) (x + iy)^{n-1}
-\end{eqnarray*}
-With $C_n$ being the complex multipole coefficients,
-$b_n$ the "normal multipole coefficients" and $a_n$ the "skew multipole coefficients".
-The maximal momentum used is the octopole momentum. The lower four momenta are used
-to describe the magnetic field:
-\begin{itemize}\itemcompact
-\item Dipole (n=1):
- \begin{eqnarray*}
- B_y &=& b_1 \\
- B_x &=& a_1 \\
- B_z &=& constant \\
- \end{eqnarray*}
-\item Quadrupole (n=2):
- \begin{eqnarray*}
- B_y &=& b_2 x - a_2 y \\
- B_x &=& b_2 y + a_2 x \\
- \end{eqnarray*}
-\item Sextupole (n=3):
- \begin{eqnarray*}
- B_y + i B_x &=& (b_3 +ia_3) (x^2 + 2ixy - y^2) \\
- B_y &=& b_3 x^2 - b_3 y^2 - 2 a_3 xy \\
- B_x &=& a_3 x^2 - a_3 y^2 + 2 b_3 xy \\
- \end{eqnarray*}
-
-\item Octopole (n=4):
- \begin{eqnarray*}
- B_y + i B_x &=& (b_4 +ia_4) (x^3 + 3ix^2y - 3xy^2 -iy^3) \\
- B_y &=& b_4 x^3 - 3 b_4 x y^2 - 3 a_4 x^2 y + a_4 y^3 \\
- B_x &=& 3 b_4 x^2 y + b_4 y^3 + a_4 x^3 - 3 a_4 x y^2 \\
- \end{eqnarray*}
-\end{itemize}
-The defined field components only apply within the shape 'volume'.
-If 'volume' is an invalid shape (ie. not defined), then the field
-components are valied throughout the 'universe'.
-
-\noindent
-The magnetic multipoles are defined as follows:
-\begin{code}
- <field name="MyMagnet" type="MultipoleMagnet">
- <position x="0" y="0" z="0"/>
- <rotation x="pi" y="0" z="0"/>
- <shape type="shape-constructor-type" .... args .... >
- <coeffizient coefficient="coeff(n=1)" skew="skew(n=1)"/>
- .... maximum of 4 coefficients ....
- <coeffizient coefficient="coeff(n=4)" skew="skew(n=4)"/>
- </field>
-\end{code}
-The shape defines the geometrical coverage of the multipole
-field in the origin (See section~\ref{dd4hep-basic-shapes} for details).
-This shape may then be transformed to
-the required location in the detector area using the position
-and the rotation elements, which define this transformation.
-
-\newpage
-%=============================================================================
-\subsection{Detector Constructors}
-\label{sec:dd4hep-manual-detector-constructors}
-%=============================================================================
-\noindent
-The creation of appropriate detector constructors is the main work of a client
-defining his own detector. The detector constructor is a fragment of code in the
-form of a routine, which return a handle to the created subdetector
-\tw{DetElement} object.
-
-\noindent
-Knowing that detector constructors are the main work items of clients significant
-effort was put in place to ease and simplify this procedure as much as possible
-in order to obtain readable, still compact code hopefully easy to maintain.
-The interfaces to all objects, XML accessors, shapes, volumes etc. which were
-discussed above were optimized to support this intention.
-
-\noindent
-To illustrate the anatomy of such a constructor the following code originating
-from an existing SiD detector concept will be analyzed. The example starts
-with the XML input data. Further down this section the code is shown
-with a detailed description of every relevant line. The object to be build is
-a subdetector representing a layered calorimeter,
-where each layer consists of a number of slices as shown in the XML snippet.
-These layers are then repeated a number of times.
-
-\vspace{0.1cm}
-\noindent
-The XML snippet describing the subdetector properties:
-\begin{code}
- <detector id="13" name="LumiCal" reflect="true" type="CylindricalEndcapCalorimeter"
- readout="LumiCalHits" vis="LumiCalVis" calorimeterType="LUMI">
- <comment>Luminosity Calorimeter</comment>
- <dimensions inner_r = "LumiCal_rmin" inner_z = "LumiCal_zmin" outer_r = "LumiCal_rmax" />
- <layer repeat="20" >
- <slice material = "TungstenDens24" thickness = "0.271*cm" />
- <slice material = "Silicon" thickness = "0.032*cm" sensitive = "yes" />
- <slice material = "Copper" thickness = "0.005*cm" />
- <slice material = "Kapton" thickness = "0.030*cm" />
- <slice material = "Air" thickness = "0.033*cm" />
- </layer>
- <layer repeat="15" >
- <slice material = "TungstenDens24" thickness = "0.543*cm" />
- <slice material = "Silicon" thickness = "0.032*cm" sensitive = "yes" />
- <slice material = "Copper" thickness = "0.005*cm" />
- <slice material = "Kapton" thickness = "0.030*cm" />
- <slice material = "Air" thickness = "0.033*cm" />
- </layer>
- </detector>
-\end{code}
-
-\vspace{0.1cm}
-\noindent
-The C++ code snippet interpreting the XML data and expanding the geometry:
-\vspace{0.1cm}
-\begin{code}
-#include "DD4hep/DetFactoryHelper.h"
-#include "XML/Layering.h"
-
-using namespace std;
-using namespace DD4hep;
-using namespace DD4hep::Geometry;
-
-static Ref_t create_detector(LCDD& lcdd, xml_h e, SensitiveDetector sens) {
- xml_det_t x_det = e;
- string det_name = x_det.nameStr();
- bool reflect = x_det.reflect();
- xml_dim_t dim = x_det.dimensions();
- double zmin = dim.inner_z();
- double rmin = dim.inner_r();
- double rmax = dim.outer_r();
- double totWidth = Layering(x_det).totalThickness();
- double z = zmin;
- Material air = lcdd.air();
- Tube envelope (rmin,rmax,totWidth,0,2*M_PI);
- Volume envelopeVol(det_name+"_envelope",envelope,air);
- int layer_num = 1;
- PlacedVolume pv;
-
- // Set attributes of slice
- for(xml_coll_t c(x_det,_U(layer)); c; ++c) {
- xml_comp_t x_layer = c;
- double layerWidth = 0;
- for(xml_coll_t l(x_layer,_U(slice)); l; ++l)
- layerWidth += xml_comp_t(l).thickness();
-
- for(int i=0, m=0, repeat=x_layer.repeat(); i<repeat; ++i, m=0) {
- double zlayer = z;
- string layer_name = det_name + _toString(layer_num,"_layer%d");
- Volume layer_vol(layer_name,Tube(rmin,rmax,layerWidth),air);
-
- for(xml_coll_t l(x_layer,_U(slice)); l; ++l, ++m) {
- xml_comp_t x_slice = l;
- double w = x_slice.thickness();
- string slice_name = layer_name + _toString(m+1,"slice%d");
- Material slice_mat = lcdd.material(x_slice.materialStr());
- Volume slice_vol (slice_name,Tube(rmin,rmax,w),slice_mat);
-
- if ( x_slice.isSensitive() ) {
- sens.setType("calorimeter");
- slice_vol.setSensitiveDetector(sens);
- }
- slice_vol.setAttributes(lcdd,x_slice.regionStr(),x_slice.limitsStr(),x_slice.visStr());
- pv = layer_vol.placeVolume(slice_vol,Position(0,0,z-zlayer-layerWidth/2+w/2));
- pv.addPhysVolID("slice",m+1);
- z += w;
- }
- layer_vol.setVisAttributes(lcdd,x_layer.visStr());
- Position layer_pos(0,0,zlayer-zmin-totWidth/2+layerWidth/2);
- pv = envelopeVol.placeVolume(layer_vol,layer_pos);
- pv.addPhysVolID("layer",layer_num);
- ++layer_num;
- }
- }
- // Set attributes of slice
- envelopeVol.setAttributes(lcdd,x_det.regionStr(),x_det.limitsStr(),x_det.visStr());
-
- DetElement sdet(det_name,x_det.id());
- Volume motherVol = lcdd.pickMotherVolume(sdet);
- PlacedVolume phv = motherVol.placeVolume(envelopeVol,Position(0,0,zmin+totWidth/2));
- phv.addPhysVolID("system",sdet.id())
- .addPhysVolID("barrel",1);
- sdet.setPlacement(phv);
- if ( reflect ) {
- phv=motherVol.placeVolume(envelopeVol,Transform3D(RotationZ(M_PI),Position(0,0,-zmin-totWidth/2)));
- phv.addPhysVolID("system",sdet.id())
- .addPhysVolID("barrel",2);
- }
- return sdet;
+\newcommand{\tgeo}[2]
+{
+ \href{http://root.cern.ch/root/html/#1.html}{#2}
+}
+\newcommand{\tgeoO}[3]
+{
+ \href{http://root.cern.ch/root/html/#1:#2}{#3}
}
-DECLARE_DETELEMENT(CylindricalEndcapCalorimeter,create_detector);
-\end{code}
-
-\newpage
-\noindent
-\begin{tabular} {l||p{0cm}}
-\docline{Line}{}
-\docline{1}{The include file DetFactoryHelper.h includes all
- utilities to extract XML information together with the appropriate type
- definition.}
-\docline{4-6}{Convenience shortcut to save ourself a lot of typing.}
-\docline{8}{The entry point to the detector constructor. This routine shall
- be called by the plugin mechanism.}
-\docline{9}{The functionality of the raw XML handle \tw{xml\_h} is rather
- limited. A simple assignment to a XML detector object gives us all the
- functionality we need.}
-\docline{10,11}{Extracting the sub-detector name and properties from the xml handle.}
-\docline{12-17}{Access the $dimension$ child-element from the XML subtree, access the element's
- attributes and precompute values used later.}
-\docline{18}{Retrieve a reference to the "air" material from LCDD.}
-\docline{19-20}{Construct the envelope volume shaped as a tube made out of air.}
-\docline{25}{Now the detector can be built: We loop over all layers types and over
- each layer type as often as necessary (attribute: repeat).
- The XML collection object will return all child elements of \tw{x\_det}
- with a tag-name "layer". }
-\docline{25}{Note the macro $\tt{\_U(layer)}$: When using Xerces-C as an XML parser,
- it will expand to the reference to an object containing the unicode value
- of the string "layer". The full list of predefined tag names can be found in the
- include file \detdesc{html/_unicode_values_8h.html}{DD4hep/UnicodeValues.h}.
- If a user tag is not part in the precompiled tag list, the corresponding Unicode
- string may be created with the macro \tw{\_Unicode(layer)} or \tw{Unicode("layer")}.
- }
-\docline{26}{Convenience assignment to extract attributes of the layer element.}
-\docline{27-29}{Compute total layer width.}
-\docline{31}{Create \tw{repeat} number of layers of the same type.}
-\docline{32-34}{Create the named envelope volume with a tube shape
- containing all slices of this layer.}
-\docline{36-51}{Create the different layer-slices with a tube shape and the
- corresponding material as indicated in the XML data.}
-\docline{43-46}{If the slice is sensitive i.e. is instrumented and supposed to
- deliver signals from particle passing, the sensitive detector component of this
- detector needs to be attached to the slice.}
-\docline{47}{Set visualization and geant4 attributes to the slice volume.
- If the attributes are not present, they will be ignored.}
-\docline{48}{Now the created slice volume will be placed inside the mother,
- the layer envelope at the correct position. This operation results
- in the creation of a \tw{PlacedVolume}.}
-\docline{49}{It identify uniquely every slice within the layer an identifier
- (here the number of the created slice) is attached. This identifier
- must be present in the
- bitmap defined by the \tw{IDDescriptor} of this subdetector.}
-\docline{52-55}{Same as 47-49, but now the created layer volume is placed
- in the envelope of the entire subdetector.}
-\docline{60}{Set envelope attributes.}
-\docline{62}{Construct the main detector element of this subdetector.
- This will be the unique entry point to access any information of the subdetector.\\
- {\bf{Note:}} the subdetector my consist of a hierarchy of detector elements.
- For example each layer could be described by it's own \tw{DetElement} and all
- layer-\tw{DetElement} instances being children of the subdetector instance.
- }
-\docline{63-64}{Place the subdetector envelope into its mother
- (typically the top level (world) volume).}
-\docline{65-66}{Add the missing \tw{IDDescriptor} identifiers to complete the bitmap.}
-\docline{67}{Store the placement in the subdetector detector
- element in order to make it availible to later clients of this \tw{DetElement}.}
-\end{tabular}
-\newpage
-\begin{tabular} {l||p{0cm}}
-\docline{Line}{}
-\docline{68-72}{Endcap calorimeters typically are symmetric i.e. an
- endcap is located on each side of the barrel. To easy such
- reflections the entire endcap structure
- can be copied and placed again. }
-\docline{73}{All done. Return the created subdetector element to the caller for registration.}
-\docline{76}{{\bf Very important:}Without the registration of the construction
- function to the framework, the corresponding plugin will not be found.
- The macro has two arguments: firstly the plugin name which is identical to the
- detector type in the XML snippet and secondly the function to be called
- at construction time.}
-\end{tabular}
-
-\newpage
-%=============================================================================
-\subsection{Tools and Utilities}
-
-%=============================================================================
-\subsubsection{Geometry Visualization}
-\label{sec:dd4hep-manual-geometry-visualization}
-%=============================================================================
-\noindent
-Visualizing the geometry is an important tool to debug and validate
-the constructed detector.
-Since \DDhep uses the \tw{ROOT} geometry package, all visualization tools
-from ROOT are automatically supported. This is in the first place the
-OpenGL canvas of \tw{ROOT} and all elaborated derivatives thereof such as
-event displays etc. Figure~\ref{fig:dd4hep-user-manual-visualization-subdetector}
-shows as an example the subdetector example from the \tw{SiD} detector design
-discussed in section~\ref{sec:dd4hep-manual-detector-constructors}.
-\begin{figure}[h]
- \begin{center}
- \begin{tabular}{l r}
- \includegraphics[width=80mm] {DD4hep-Lumical} &
- \includegraphics[width=80mm] {DD4hep-Lumical-detailed} \\
- \end{tabular}
- \caption{Geometry visualization using the ROOT OpenGL plugin.
- To the left the entire luminosity calorimeter is shown,
- at the right the detailed zoomed view with clipping to
- access the internal layer and slice structure.}
- \label{fig:dd4hep-user-manual-visualization-subdetector}
- \end{center}
-\end{figure}
-
-\noindent
-The command to create the display is part of the DD4hep release:
-\begin{code}
-$> geoDisplay -compact <path to the XML file containing the detector description>
+\setlength{\emergencystretch}{3em}
+\providecommand{\tightlist}{%
+ \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
- DD4hepGeometryDisplay -opt [-opt]
- -compact <file> Specify the compact geometry file
- [REQUIRED] At least one compact geo file is required!
- -build_type <number/string> Specify the build type
- [OPTIONAL] MUST come immediately after the -compact input.
- Default for each file is: BUILD_DEFAULT [=1]
- Allowed values: BUILD_SIMU [=1], BUILD_RECO [=2] or BUILD_DISPLAY [=3]
- -destroy [OPTIONAL] Force destruction of the LCDD instance
- before exiting the application
- -volmgr [OPTIONAL] Load and populate phys.volume manager to
- check the volume ids for duplicates etc.
- -print <number/string> Specify output level. Default: INFO(=3)
- [OPTIONAL] Allowed values: VERBOSE(=1), DEBUG(=2),
- INFO(=3), WARNING(=4), ERROR(=5), FATAL(=6)
- The lower the level, the more printout...
- -load_only [OPTIONAL] Dry-run to only load geometry without
- starting the dispay.
-\end{code}
+\ifx\paragraph\undefined\else
+\let\oldparagraph\paragraph
+\renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}}
+\fi
+\ifx\subparagraph\undefined\else
+\let\oldsubparagraph\subparagraph
+\renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}}
+\fi
-%=============================================================================
-\subsubsection{Geometry Conversion}
-\label{sec:dd4hep-manual-geometry-conversion}
-%=============================================================================
-\noindent
-\tw{ROOT} \tw{TGeo} is only one representation of a detector geometry.
-Other applications may require other representation. In particular two other
-are worth mentioning:
-\begin{itemize}\itemcompact
-\item \tw{LCDD}~\cite{bib:LCDD} the geometry representation used to
- simulate the ILC detector design with the \tw{slic} application.
-\item \tw{GDML}~\cite{bib:GDML} a geometry markup language understood
- by Geant4 and \tw{ROOT}.
-\end{itemize}
-Both conversions are supported in \DDhep with the geoConverter application:
-\begin{code}
- geoConverter -opt [-opt]
- Action flags: Usage is exclusive, 1 required!
- -compact2lcdd Convert compact xml geometry to lcdd.
- -compact2gdml Convert compact xml geometry to gdml.
- -compact2vis Convert compact xml to visualisation attrs
+\providecommand{\subtitle}[1]{}
- -input <file> [REQUIRED] Specify input file.
- -output <file> [OPTIONAL] Specify output file.
- if no output file is specified, the output
- device is stdout.
- -ascii [OPTIONAL] Dump visualisation attrs in csv format.
- [Only valid for -compact2vis]
-\end{code}
+% Set paths
+%\makeatletter
+%\def\input@path{{usermanual/}}
+%\makeatother
-%=============================================================================
-\subsubsection{Overlap checking}
-\label{sec:dd4hep-manual-overlap-checking}
-%=============================================================================
-\noindent
-Overlap checks are an important tool to verify the consistency of the
-implemented geometrical design. As in the real world, where overlaps are
-impossible, also simulated geometries may not have overlaps. In simulation
-overlaps tend to create particle reflections possibly leading to infinite
-loops.
-\begin{code}
- python <install>/DD4hep/bin/checkOverlaps.py --help
- Usage: checkOverlaps.py [options]
+% Load configuration
+\input{config}
+\graphicspath{{figures/}}
+%----------------------------------------------------------------------------------------
+% DOCUMENT INFORMATION
+%----------------------------------------------------------------------------------------
+\titlehead{\centering\includegraphics[width=7cm]{logo.eps}}
+\title{DD4hep User Manual} % Title
- Check TGeo geometries for overlaps.
+\author{DD4hep authors (\href{mailto:dd4hep@cern.ch}{dd4hep@cern.ch})
+} % Author names
- Options:
- -h, --help show this help message and exit
- -c <FILE>, --compact=<FILE> Define LCCDD style compact xml input
- -p <boolean>, --print=<boolean> Print overlap information to standard output
- (default:True)
- -q, --quiet Do not print (disable --print)
- -t <double number>, --tolerance=<double number>
- Overlap checking tolerance. Unit is in [mm].
- (default:0.1 mm)
- -o <string>, --option=<string> Overlap checking option ('' or 's')
-\end{code}
+\date{\today\\ \vspace{10pt} Version \version} % Date for the report
-%=============================================================================
-\subsubsection{Geometry checking}
-\label{sec:dd4hep-manual-geometry-checking}
-%=============================================================================
-\noindent
-Perform extensive geometry checks. For details and up to date information
-please refer to the ROOT documentation of the class {\tt{TGeoManager}}:
-\begin{itemize}\itemcompact
-\item Member function {\tgeoO{TGeoManager.html}{TGeoManager:CheckGeometry}{TGeoManager::CheckGeometry}} and
-\item Member function {\tgeoO{TGeoManager.html}{TGeoManager:CheckGeometryFull}{TGeoManager::CheckGeometryFull}}
-\end{itemize}
-\begin{code}
- python <install>DD4hep/bin/checkGeometry.py --help
- Usage: checkGeometry.py [options]
- TGeo Geometry checking.
+\begin{document}
+\frontmatter
+\pagenumbering{Roman}
- Options:
- -h, --help show this help message and exit
- -c <FILE>, --compact=<FILE> Define LCCDD style compact xml input
- -f <boolean>, --full=<boolean> Full geometry checking
- -n <integer>, --ntracks=<integer> Number of tracks [requires 'full']
- -x <double>, --vx=<double> X-position of track origine vertex [requires 'full']
- -y <double>, --vy=<double> Y-position of track origine vertex [requires 'full']
- -z <double>, --vz=<double> Z-position of track origine vertex [requires 'full']
- -o <string>, --option=<string> Geometry checking option default:ob
-\end{code}
+\thispagestyle{empty}
+\maketitle % Insert the title, author and date
+\cleardoublepage
+\thispagestyle{empty}
+\addlicense
+{\vspace{20pt} \centering\includegraphics[width=\linewidth]{AIDA-2020}}
+\cleardoublepage
-The full geometry check performs the \tgeoO{TGeoManager.html}{TGeoManager:CheckGeometryFull}
-{following actions}:
-\begin{itemize}\itemcompact
-\item if option contains 'o': Optional overlap checkings (by sampling and by mesh).
-\item if option contains 'b': Optional boundary crossing check + timing per volume.
-\item{\bf{STAGE 1:}} extensive overlap checking by sampling per volume. Stdout need to be
- checked by user to get report, then TGeoVolume::CheckOverlaps(0.01, "s") can
- be called for the suspicious volumes.
-\item{\bf{STAGE 2:}} normal overlap checking using the shapes mesh - fills the list of
- overlaps.
-\item{\bf{STAGE 3:}} shooting NTRACKS rays from vertex (vx,vy,vz)
- and counting the total number of
- crossings per volume (rays propagated from boundary to boundary until
- geometry exit). Timing computed and results stored in a histogram.
-\item{\bf{STAGE 4:}} shooting 1 mil. random rays inside EACH volume and calling
- FindNextBoundary() + Safety() for each call. The timing is normalized by the
- number of crossings computed at stage 2 and presented as percentage.
- One can get a picture on which are the most "burned" volumes during
- transportation from geometry point of view. Another plot of the timing per
- volume vs. number of daughters is produced.
-\end{itemize}
-%=============================================================================
-\subsubsection{Directional Material Scans}
-\label{sec:dd4hep-manual-directional-material-scans}
-%=============================================================================
-\noindent
-Print the materials on a straight line between the two given points:
-\begin{code}
-materialScan
- usage: print_materials compact.xml x0 y0 z0 x1 y1 z1
- -> prints the materials on a straight line between the two given points ( unit is cm)
-\end{code}
-$materialScan$ uses the python bindings provided by Geant4 and may be not
-always availible. Alternatively the command $print\_materials$ may be used,
-which does not use the python binding, but produces less pretty output.
+% Table Of Contents
+\tableofcontents
-%=============================================================================
-\subsubsection{Plugin Test Program}
-\label{sec:dd4hep-manual-plugin-test}
-%=============================================================================
-\noindent
-The plugin tester loads a given geometry and the executes a plugin
-defined at the command line. The main purpose of this program is to quickly
-invoke new detector plugins while developing. The arguments for this
-program are:
-\begin{code}
- geoPluginRun -opt [-opt]
-
- -plugin <name> [REQUIRED] Plugin to be executed and applied.
- -input <file> [OPTIONAL] Specify geometry input file.
- -build_type <number/string> Specify the build type
- [OPTIONAL] MUST come immediately after the -compact input.
- Default for each file is: BUILD_DEFAULT [=1]
- Allowed values: BUILD_SIMU [=1], BUILD_RECO [=2] or BUILD_DISPLAY [=3]
- -destroy [OPTIONAL] Force destruction of the LCDD instance
- before exiting the application
- -volmgr [OPTIONAL] Load and populate phys.volume manager to
- check the volume ids for duplicates etc.
- -print <number/string> Specify output level. Default: INFO(=3)
- [OPTIONAL] Allowed values: VERBOSE(=1), DEBUG(=2),
- INFO(=3), WARNING(=4), ERROR(=5), FATAL(=6)
- The lower the level, the more printout...
+\mainmatter
+\pagenumbering{arabic}
+% intro
+\input{chapters/overview}
+\input{chapters/basics}
-\end{code}
+\cleardoublepage
+\phantomsection
+\addreferencesline
+\printbibliography
-%=============================================================================
-\newpage
-\begin{thebibliography}{9}
-\input{Bibliography.tex}
-\bibitem{bib:DDeqnarray} M.Frank,
- "DDeqnarray User Manual:
- eqnarrayment Support for the DD4hep Geometry Description Toolkit".
-\bibitem{bib:DDSegmentations} C.Grefe et al.,
- "The DDSegmentation package",
- Non existing documentation to be written.
-\end{thebibliography}
-%=============================================================================
\end{document}
diff --git a/doc/usermanuals/DD4hep/chapters/basics.tex b/doc/usermanuals/DD4hep/chapters/basics.tex
new file mode 100644
index 000000000..db188543f
--- /dev/null
+++ b/doc/usermanuals/DD4hep/chapters/basics.tex
@@ -0,0 +1,1419 @@
+\chapter{Basics}
+\label{sec:dd4hep-user-manual}
+
+This chapter describes how supply a physics application developed with all the information related to the detector which is necessary to process data from particle collisions and to qualify the detecting apparatus in order to interpret these event data.
+
+The clients of the detector description are the algorithms residing in the event processing framework that need this information in order to perform their job (reconstruction, simulation, etc.). The detector description provided by DD4hep is a framework for developers to provide the specific detector information to software algorithms, which process data from particle collisions.
+
+In the following sections an overview is given over the various independent elements of DD4hep followed by the discussion of an example which leads to the description of a detector when combining these elements. This includes a discussion of the features of the DD4hep detector description and of its structure.
+
+\section{Building DD4hep}
+\label{sec:dd4hep-user-manual-building}
+
+The DD4hep source code is freely available and is distributed under the GPLv3 License. See the \texttt{doc/LICENSE} in the repository~\cite{dd4hep-repo} for more information. Please read the \textit{Release Notes} before downloading or using this release.
+
+The DD4hep project consists of several packages. The idea has been to separate the common parts of the detector description toolkit from concrete detector examples.
+
+The package {\texttt{DDCore}} contains the definition of the basic classes of the toolkit: \texttt{Handle}, \texttt{DetElement}, \texttt{Volume}, \texttt{PlacedVolume}, \texttt{Shapes}, \texttt{Material}, etc. Most of these classes are \texttt{handles} to ROOT's TGeom classes.
+
+\subsection{Supported Platforms}
+\label{sec:dd4hep-user-manual-platforms}
+Actively supported and tested platforms for DD4hep are :
+\begin{itemize}
+\item \texttt{Scientic Linux CERN 6}
+\item \texttt{CERN CentOS 7}
+\item \texttt{Apple macOS}
+\end{itemize}
+Support for any other platform will well be taken into account, but can only be actively supported by users who submit the necessary patches.
+
+\subsection{Prerequisites}
+\label{sec:dd4hep-user-manual-prerequisites}
+
+DD4hep depends on a number of external packages. The user will need to install these in his/her system before building and running the examples
+\begin{itemize}
+\item \texttt{CMake} version 3.4 or higher
+\item \texttt{ROOT 6} installations.
+\item \texttt{Xerces-C} if used to parse compact descriptions an installation of {Xerces-C} will is required.
+\item To build DDG4 it is mandatory to have an installation of the \texttt{Boost} header files.
+\item To build and run the simulation examples \texttt{Geant4} will be required.
+\end{itemize}
+
+\subsection{CMake Build Options for DD4hep}
+\label{sec:dd4hep-user-manual-building}
+
+The package provides the basic mechanisms for constructing the \textit{Generic Detector Description Model} in memory from \texttt{XML} compact detector definition files. Two methods are currently supported: one based
+on the \texttt{C++} \texttt{Xerces-C} parser.
+
+The \texttt{XML} parsing method is enabled by default using the \texttt{TinyXML} parser. Optionally instead of \texttt{TinyXML} the \texttt{Xerces-C} parser may be chosen by setting the two configuration options appropriately:
+
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos]{shell}
+ -DD4HEP_USE_XERCESC=ON
+ -DXERCESC_ROOT_DIR=<path to Xerces-C-installation-directory>
+\end{minted}
+
+DDG4 is the package that contains the conversion of DD4hep geometry into Geant4 geometry to be used for simulation. The option \texttt{DD4HEP\_WITH\_GEANT4:BOOL} controls the building or not of this package that has the dependency to Geant4. The Geant4 installation needs to be located using the variable:
+
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos]{shell}
+ -DDD4HEP_WITH_GEANT4=ON
+ -DGeant4_DIR=<path to Geant4Config.cmake>
+\end{minted}
+
+To properly handle component properties using \texttt{boost::spirit}, access to the Boost header files must be provided.
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{bash}
+ -DBoost_INCLUDE_DIR=<path to the boost include directory>
+ -DBoost_NO_BOOST_CMAKE=ON (to disable the search of boost-cmake)
+\end{minted}
+
+To build only the doxygen documentation and user manuals without the need for any dependencies one can use the following command
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos]{shell}
+ cmake -DBUILD_DOCS_ONLY=ON ..
+\end{minted}
+After one can execute the following target for building doxygen documentaion
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos]{shell}
+make reference
+\end{minted}
+and for building the user manuals
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos]{shell}
+make pdf
+\end{minted}
+
+\subsection{Build From Source}
+\label{sec:dd4hep-user-manual-building-from-source}
+NEED REWRITE ONCE FINALIZED
+%The following steps are necessary to build DD4hep:
+%\begin{itemize}
+%\item Set the environment, at least ROOT needs to be initialized, e.g.
+% \begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{bash}
+% source /data/ilcsoft/root/5.34.03/bin/thisroot.sh
+% \end{minted}
+% \vspace{-0.6cm}
+% (the bare minimum is: \texttt{export ROOTSYS=<path to root installation>}).
+%
+%\item First checkout code from the repository:
+% \begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{bash}
+% svn co https://svnsrv.desy.de/public/aidasoft/DD4hep/trunk DD4hep
+% \end{minted}
+% \vspace{-0.6cm}
+%
+%\item We refer to the directory DD4hep as the source directory. The
+%next step is to create a directory in which to configure and run the build
+%and store the build products. This directory should not be the same as, or
+%inside, the source directory. In this guide, we create this build directory
+%alongside our source directory:
+%\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos]{cmake}
+% mkdir build
+% cd build
+% cmake -DCMAKE_INSTALL_PREFIX=<dd4hep-install-pasth> <CMake-options> ../DD4hep
+% make -j 4
+% make install
+% \end{minted}
+%\end{itemize}
+%The CMake Variable \texttt{CMAKE\_INSTALL\_PREFIX} is used to set the install directory,
+%the directory under which the DD4hep libraries, headers and support files
+%will be installed.
+
+
+\subsection{Remarks}
+\label{sec:dd4hep-user-manual-remarks}
+The main reference is the doxygen information of DD4hep and the ROOT documentation. Please refer to these sources for a detailed view of the capabilities of each component and/or its handle. For coherence reasons, the description of the interfaces is limited to examples which illustrate the usage of the basic components.
+
+\subsection{Caveat}
+\label{sec:dd4hep-user-manual-caveat}
+NEEDS ADDITIONAL CLARIFICATION
+%The atomic units in of Geant4 are (millimeter, nanosecond and MeV and radians).
+%The atomic units of ROOT-TGeo are (centimeter, seconds, GeV and degrees).
+%Unfortunately the authors could not agree on a common system of units
+%and mixing the two can easily result in a chaos.
+%Users must be aware of this fact.
+
+\section{DD4hep Handles}
+\label{sec:dd4hep-user-manual-handles}
+
+Handles are the means of clients accessing DD4hep detector description data. The data itself is not held by the handle itself, the handle only allows the access to the data typically held by a pointer. The template handle class (see for details the \href{https://dd4hep.web.cern.ch/dd4hep/reference/classdd4hep_1_1Handle.html}{\texttt{Handle.h}} header file) allows type safe assignment of other unrelated handles and supports standard data conversions to the underlying object in form of the raw pointer, a reference etc. The template handle class:
+
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+template <typename T> class Handle {
+public:
+ // Type definitions and class specific abbreviations and forward declarations
+ typedef T Implementation;
+ typedef Handle<Implementation> handle_t;
+public:
+ // Single and only data member: pointer to the underlying object
+ T* m_element;
+public:
+ Handle() : m_element(0) { }
+ Handle(T* e) : m_element(e) { }
+ Handle(const Handle<T>& e) : m_element(e.m_element) { }
+ template<typename Q> Handle(Q* e) : m_element((T*)e) { verifyObject(); }
+ template<typename Q> Handle(const Handle<Q>& e) : m_element((T*)e.m_element) { verifyObject(); }
+ Handle<T>& operator=(const Handle<T>& e) { m_element=e.m_element; return *this;}
+ bool isValid() const { return 0 != m_element; }
+ bool operator!() const { return 0 == m_element; }
+ void clear() { m_element = 0; }
+ T* operator->() const { return m_element; }
+ operator T& () const { return *m_element; }
+ T& operator*() const { return *m_element; }
+ T* ptr() const { return m_element; }
+ template <typename Q> Q* _ptr() const { return (Q*)m_element; }
+ template <typename Q> Q* data() const { return (Q*)m_element; }
+ template <typename Q> Q& object() const { return *(Q*)m_element; }
+ const char* name() const;
+};
+\end{minted}
+effectively works like a pointer with additional object validation during assignment and construction. Handles support direct access to the held object: either by using the
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,fontsize=\small]{c++}
+ operator->() (See line 19 above)
+\end{minted}
+or the automatic type conversions:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,fontsize=\small]{c++}
+ operator T& () const (See line 20-21 above)
+ T& operator*() const
+\end{minted}
+
+All entities of the DD4hep detector description are exposed as handles - raw pointers should not occur in the code. The handles to these objects serve two purposes:
+\begin{itemize}
+\item Hold a pointer to the object and extend the functionality of a raw pointer.
+\item Enable the creation of new objects using specialized constructors within sub-classes. To ensure memory integrity and avoid resource leaks these created objects should always be stored in the detector description data hub \texttt{Detector} described in section~\ref{sec:dd4hep-user-manual-LCDD-hub}.
+\end{itemize}
+
+
+\section{The Data Extension Mechanism}
+\label{sec:dd4hep-user-manual-data-extensions}
+
+Data extensions are client defined \texttt{C++} objects aggregated to basic DD4hep objects. The need to introduce such data extensions results from the simple fact that no data structure can be defined without the iterative need in the long term to extend it leading to implementations, which can only satisfy a subset of possible clients. To accomplish for this fact a mechanism was put in place which allows any user to attach any supplementary information provided the information is embedded in a polymorph object with an accessible destructor. There is one limitation though: object extension must differ by their interface type. There may not be two objects attached with the identical interface type. The actual implemented sub-type of the extension is not relevant. Separating the interface type from the implementation type keeps client code still functional even if the implementation of the extension changes
+or is a plug-able component.
+
+The following code snippet shows the extension interface:
+
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ /// Extend the object with an arbitrary structure accessible by the type
+ template <typename IFACE, typename CONCRETE> IFACE* addExtension(CONCRETE* c);
+ /// Access extension element by the type
+ template <class T> T* extension() const;
+\end{minted}
+
+Assuming a client class of the following structure:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ class ExtensionInterface {
+ virtual ~ExtensionInterface();
+ virtual void foo() = 0;
+ };
+
+ class ExtensionImplementation : public ExtensionInterface {
+ ExtensionImplementation();
+ virtual ~ExtensionImplementation();
+ virtual void foo();
+ };
+\end{minted}
+is then attached to an extensible object as follows:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ ExtensionImplementation* ptr = new ExtensionImplementation();
+ /// ... fill the ExtensionImplementation instance with data ...
+ module.addExtension<ExtensionInterface>(ptr);
+\end{minted}
+The data extension may then be retrieved whenever the instance of the extensible object ``module'' is accessible:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ ExtensionInterface* ptr = module.extension<ExtensionInterface>();
+\end{minted}
+The lookup mechanism is rather efficient. Though it is advisable to cache the pointer within the client code if the usage is very frequent.
+
+There are currently three object types present which support this mechanism:
+\begin{itemize}
+\item the central object of DD4hep, the \texttt{Detector} class discussed in section~\ref{sec:dd4hep-user-manual-LCDD-hub}.
+\item the object describing subdetectors or parts thereof, the \texttt{DetElement} class discussed in section~\ref{sec:dd4hep-user-manual-detector-elements}. Detector element extensions in addition require the presence of a copy constructor to support e.g. reflection operations. Without a copy mechanism detector element hierarchies could cloned.
+\item the object describing sensitive detectors, the \texttt{SensitiveDetector} class discussed in section~\ref{sec:dd4hep-user-manual-sensitive-detectors}.
+\end{itemize}
+
+\section{XML Tools and Interfaces}
+\label{sec:dd4hep-user-manual-xml-tools}
+
+Using native tools to interpret \texttt{XML} structures is rather tedious and lengthy. To easy the access to \texttt{XML} data considerable effort was put in place to easy the life of clients as much as possible using predefined instructs to access \texttt{XML} attributes, elements or element collections.
+
+The functionality of the \texttt{XML} tools is perhaps best shown with a small example. Imagine to extract the data from an \texttt{XML} snippet like the following:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+ <detector name="Sometthing">
+ <tubs rmin="BP_radius - BP_thickness" rmax="BP_radius" zhalf="Endcap_zmax/2.0"/>
+ <position x="0" y="0" z="Endcap_zmax/2.0" />
+ <rotation x="0.0" y="CrossingAngle/2.0" z="0.0" />
+ <layer id="1" inner_r="Barrel_r1" outer_r="Barrel_r1 + 0.02*cm" inner_z="Barrel_zmax + 0.1*cm">
+ <slice material = "G10" thickness ="0.5*cm"/>
+ </layer>
+ <layer id="2" inner_r="Barrel_r2" outer_r="Barrel_r2 + 0.02*cm" inner_z="Barrel_zmax + 0.1*cm">
+ <slice material = "G10" thickness ="0.5*cm"/>
+ </layer>
+ ....
+ </detector>
+\end{minted}
+
+The variable names used in the \texttt{XML} snippet are evaluated when interpreted. Unless the attributes are accessed as strings, the client never sees the strings, but only the evaluated numbers. The anatomy of the \texttt{C++} code snippets to interpret such a data section looks very similar:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ static void some_xml_handler(xml_h e) {
+ xml_det_t x_det (e);
+ xml_comp_t x_tube = x_det.tubs();
+ xml_dim_t pos = x_det.position();
+ xml_dim_t rot = x_det.rotation();
+ string name = x_det.nameStr();
+
+ for(xml_coll_t i(x_det,_U(layer)); i; ++i) {
+ xml_comp_t x_layer = i;
+ double zmin = x_layer.inner_z();
+ double rmin = x_layer.inner_r();
+ double rmax = x_layer.outer_r();
+ double layerWidh = 0;
+
+ for(xml_coll_t j(x_layer,_U(slice)); j; ++j) {
+ double thickness = xml_comp_t(j).thickness();
+ layerWidth += thickness;
+ }
+ }
+ }
+\end{minted}
+In the above code snippet an \texttt{XML} (sub-)tree is passed to the executing function as a handle to an \texttt{XML} element ({\texttt{xml\_h}}). Such handles may seamlessly be assigned to any supporting helper class inheriting from the class {\texttt{XML::Element}}, which encapsulates the functionality required to interpret the \texttt{XML} structures. Effectively the various \texttt{XML} attributes and child nodes are accessed using functions with the same name from a convenience handle. In lines 3-5 child nodes are extracted, lines 10-12,16 access element attributes.Element collections with the same tag names \texttt{layer} and \texttt{slice} are exposed to the client code using an iteration mechanism.
+
+Note the macros $\texttt{\_U(layer)}$ and $\texttt{\_U(slice)}$: When using \texttt{Xerces-C} as an \texttt{XML} parser, it will expand to the reference to an object containing the unicode value of the string ``layer''. The full list of predefined tag names can be found in the include file \texttt{XML/UnicodeValues.h}. If a user tag is not part in the precompiled tag list, the corresponding Unicode string may be created with the macro \texttt{\_Unicode(layer)} or the function \texttt{Unicode(``layer'')}.
+
+The convenience handles actually implement these functions to ease life. There is no magic - newly created attributes with new names obviously cannot be accessed with convenience mechanism. Hence, either you know what you are doing and you create your own convenience handlers or you restrict yourself a bit in the creativity of defining new attribute names.
+
+There exist several utility classes to extract data from predefined \texttt{XML} tags:
+\begin{itemize}
+\item Any \texttt{XML} element is described by an \texttt{XML} handle \texttt{\texttt{XML::Handle\_t}} ({\texttt{xml\_t}}). Handles are the basic structure for the support of higher level interfaces described above. The assignment of a handle to any of the interfaces below is possible.
+\item The class \texttt{\texttt{XML::Element}} ({\texttt{xml\_elt\_t}}) supports in a simple way the navigation through the hierarchy of the \texttt{XML} tree accessing child nodes and attributes. Attributes at this level are named entities and the tag name must be supplied.
+\item The class \texttt{\texttt{XML::Dimension}} with the type definition {\texttt{xml\_dim\_t}}, supports numerous access functions named identical to the
+\texttt{XML} attribute names. Such helper classes simplify the tedious string handling required by the
+\item The class \texttt{\texttt{XML::Component}} ({\texttt{xml\_comp\_t}}) and the class \texttt{\texttt{XML::Detector}} ({\texttt{xml\_det\_t}}) resolving other issues useful to construct detectors.
+\item Sequences of \texttt{XML} elements with an identical tag name may be handled as iterations as shown in the Figure above using the class \texttt{\texttt{XML::Collection\_t}}.
+\item Convenience classes, which allow easy access to element attributes may easily be constructed using the methods of the {\texttt{XML::Element}} class. This allows to construct very flexible thou non-intrusive extensions to DD4hep. Hence there is a priori no need to modify these helpers for the benefit of only one single client. In the presence of multiple requests such extensions may though be adopted.
+\end{itemize}
+It is clearly the responsibility of the client to only request attributes from an \texttt{XML} element, which exist. If an attribute, a child node etc. is not found within the element an exception is thrown.
+
+The basic interface of the \texttt{XML::Element} class allows to access tags and child nodes not exposed by the convenience wrappers:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ /// Access the tag name of this DOM element
+ std::string tag() const;
+ /// Access the tag name of this DOM element
+ const XmlChar* tagName() const;
+
+ /// Check for the existence of a named attribute
+ bool hasAttr(const XmlChar* name) const;
+ /// Retrieve a collection of all attributes of this DOM element
+ std::vector<Attribute> attributes() const;
+ /// Access single attribute by it's name
+ Attribute getAttr(const XmlChar* name) const;
+ /// Access attribute with implicit return type conversion
+ template <class T> T attr(const XmlChar* tag) const;
+ /// Access attribute name (throws exception if not present)
+ const XmlChar* attr_name(const Attribute attr) const;
+ /// Access attribute value by the attribute (throws exception if not present)
+ const XmlChar* attr_value(const Attribute attr) const;
+
+ /// Check the existence of a child with a given tag name
+ bool hasChild(const XmlChar* tag) const;
+ /// Access child by tag name. Thow an exception if required in case the child is not present
+ Handle_t child(const Strng_t& tag, bool except = true) const;
+ /// Add a new child to the DOM node
+ Handle_t addChild(const XmlChar* tag) const;
+ /// Check if a child with the required tag exists - if not create it and add it to the current node
+ Handle_t setChild(const XmlChar* tag) const;
+\end{minted}
+
+\section{The Detector Description Data Hub: \texttt{Detector}}
+\label{sec:dd4hep-user-manual-LCDD-hub}
+As shown in Figure~\ref{fig:dd4hep-detector-model}, any access to the detector description data is done using a standardized interface called \texttt{Detector}. During the configuration phase of the detector the interface is used to populate the internal data structures. Data structures present in the memory layout of the detector description may be retrieved by clients at any time using the \href{https://dd4hep.web.cern.ch/dd4hep/reference/classdd4hep_1_1Detector.html}{\texttt{Detector} interface class}. This includes of course, the access during the actual detector construction. The following code listing shows the accessor method to retrieve detector description entities from the interface. Not shown are access methods for groups of these entities and the methods to add objects:
+
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+class Detector {
+ ///+++ Shortcuts to access often used quantities
+
+ /// Return handle to material describing air
+ virtual Material air() const = 0;
+ /// Return handle to material describing vacuum
+ virtual Material vacuum() const = 0;
+ /// Return handle to "invisible" visualization attributes
+ virtual VisAttr invisible() const = 0;
+
+ ///+++ Access to the top level detector elements and the corresponding volumes
+
+ /// Return reference to the top-most (world) detector element
+ virtual DetElement world() const = 0;
+ /// Return reference to detector element with all tracker devices.
+ virtual DetElement trackers() const = 0;
+
+ /// Return handle to the world volume containing everything
+ virtual Volume worldVolume() const = 0;
+ /// Return handle to the volume containing the tracking devices
+ virtual Volume trackingVolume() const = 0;
+
+ ///+++ Access to geometry and detector description objects
+
+ /// Retrieve a constant by it's name from the detector description
+ virtual Constant constant(const std::string& name) const = 0;
+ /// Retrieve a matrial by it's name from the detector description
+ virtual Material material(const std::string& name) const = 0;
+ /// Retrieve a field component by it's name from the detector description
+ virtual DetElement detector(const std::string& name) const = 0;
+ /// Retrieve a sensitive detector by it's name from the detector description
+ virtual SensitiveDetector sensitiveDetector(const std::string& name) const = 0;
+ /// Retrieve a readout object by it's name from the detector description
+ virtual Readout readout(const std::string& name) const = 0;
+ /// Retrieve a id descriptor by it's name from the detector description
+ virtual IDDescriptor idSpecification(const std::string& name) const = 0;
+ /// Retrieve a subdetector element by it's name from the detector description
+ virtual CartesianFieldfield(const std::string& name) const = 0;
+
+ ///+++ Access to visualisation attributes and Geant4 processing hints
+
+ /// Retrieve a visualization attribute by it's name from the detector description
+ virtual VisAttr visAttributes(const std::string& name) const = 0;
+
+ /// Retrieve a region object by it's name from the detector description
+ virtual Region region(const std::string& name) const = 0;
+ /// Retrieve a limitset by it's name from the detector description
+ virtual LimitSet limitSet(const std::string& name) const = 0;
+ //...
+
+ ///+++ Extension mechanism:
+ /// Extend the sensitive detector element with an arbitrary structure accessible by the type
+ template <typename IFACE, typename CONCRETE> IFACE* addExtension(CONCRETE* c)
+};
+\end{minted}
+
+As shown in the above listing, the \texttt{Detector} interface is the main access point to access a whole set
+\begin{itemize}
+\item often used predefined values such as the material ``air'' or ``vacuum'' (line 5--10).
+\item the top level objects ``world'', ``trackers'' and the corresponding volumes (line 14--21).
+\item items in the constants table containing named definitions also used during the interpretation of the \texttt{XML} content after parsing (line 26)
+\item named items in the the material table (line 28)
+\item named subdetectors after construction and the corresponding (line 30)
+\item named sensitive detectors with their (line 32)
+\item named readout structure definition using a (line 34)
+\item named readout identifier descriptions (line 36)
+\item named descriptors of electric and/or magnetic fields (line 39).
+\end{itemize}
+Additional support for specialized applications is provided by the interface:
+\begin{itemize}
+\item Geant4: named region settings (line 46)
+\item Geant4: named limits settings (line 48)
+\item Visualization: named visualization attributes (line 43)
+\item User defined extensions (line 53) are supported with the extension mechanism described in section~\ref{sec:dd4hep-user-manual-data-extensions}.
+\end{itemize}
+
+All the values are populated either directly from \texttt{XML} or from \textit{detector constructors} (see section~\ref{sec:detector-constructors}). The interface also allows to load \texttt{XML} configuration files of any kind provided an appropriate interpretation plugin is present. In the next section we describe the functionality of the ``lccd'' plugin used to interpret the compact detector description. This mechanism can easily be extended using ROOT plugins, where the plugin name must corrspond to the \texttt{XML} root element of the document to be interpreted.
+
+\section{Detector Description Persistency in \texttt{XML}}
+\label{sec:compact-xml-structure}
+As explained in a previous section, the mechanism involved in the data loading allow an application to be fairly independent of the technology used to populate the transient detector representation. However, if one wants to use a given technology, she/he has to get/provide the corresponding conversion mechanism. The choice of \texttt{XML} was driven mainly by its easiness of use and the number of tools provided for its manipulation and parsing. Moreover, \texttt{XML} data can be easily translated into many other format using tools like \texttt{XSLT} processors. The grammar used for the \texttt{XML} data is pretty simple and straight forward, actually very similar to other geometry description languages based on \texttt{XML}. For example the material description is nearly identical to the material description in \texttt{GDML}~\cite{Chytracek:2006be}. The syntactic structure of the compact \texttt{XML} description was taken from the SiD detector description~\cite{Gaede:81331}. The following listing shows the basic layout of any the compact detector description file with its different sections:
+
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+<lccdd>
+ <info> ... </info> Auxiliary detector model information
+ <includes> ... </includes> Section defining GDML files to be included
+ <define> ... </define> Dictionary of constant expressions and varables
+ <materials> ... </materials> Additional material definitions
+ <display> ... </display> Definition of visualization attributes
+ <detectors> ... </detectors> Section with sub-detector definitions
+ <readouts> ... </readouts> Section with readout structure definitions
+ <limits> ... </limits> Definition of limit sets for Geant4
+ <fields> ... </fields> Field definitions
+</lccdd>
+\end{minted}
+
+The root tag of the \texttt{XML} tree is {\texttt{lccdd}}. This name is fixed. In the following the content of the various sections is discussed. The \texttt{XML} sections are filled with the following information:
+\begin{itemize}
+\item {\textbf{The \texttt{<info>} sub-tree}} contains auxiliary information about the detector model:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+<info name="clic_sid_cdr"
+ title="CLIC Silicon Detector CDR"
+ author="Christian Grefe"
+ url="https://twiki.cern.ch/twiki/bin/view/CLIC/ClicSidCdr"
+ status="development"
+ version="$Id: compact.xml 665 2013-07-02 18:49:26Z markus.frank $">
+ <comment>The compact format for the CLIC Silicon Detector used
+ for the conceptual design report</comment>
+</info>
+\end{minted}
+
+\item {\textbf{The \texttt{<includes>} section}} allows to include GDML sub-trees containing material descriptions. These files are processed {\textit{before}} the detector constructors are called:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+<includes>
+ <gdmlFile ref="elements.xml"/>
+ <gdmlFile ref="materials.xml"/>
+ ...
+</includes>
+\end{minted}
+
+\item {\textbf{The \texttt{<define>} section}} contains all variable definitions defined by the client to simplify the definition of subdetectors. These name-value pairs are fed to the expression evaluator and must evaluate to a number. String constants are not allowed. These variables can be combined to formulas e.g. to automatically re-dimension subdetectors if boundaries are changed:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+<define>
+ <constant name="world_side" value="30000"/>
+ <constant name="world_x" value="world_side"/>
+ <constant name="world_y" value="world_side"/>
+ <constant name="world_z" value="world_side"/>
+ ....
+</define>
+\end{minted}
+
+\item {\textbf{The \texttt{<materials>} sub-tree}} contains additional materials, which are not contained in the default materials tables. The snippet below shows an example to extend the table of known materials. For more details please see section~\ref{sec:compact-material-description}.
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+<materials>
+ <!-- The description of an atomic element or isotope -->
+ <element Z="30" formula="Zn" name="Zn" >
+ <atom type="A" unit="g/mol" value="65.3955" />
+ </element>
+ ...
+ <!-- The description of a new material -->
+ <material name="CarbonFiber_15percent">
+ ...
+ </material>
+ ...
+</materials>
+\end{minted}
+
+\item {\textbf{The visualization attributes}} are defined in the \texttt{<display>} section. Clients access visualization settings by name. The possible attributes are shown below and essentially contain the RGB color values, the visibility and the drawing style:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+<display>
+ <vis name="InvisibleNoDaughters"
+ showDaughters="false"
+ visible="false"/>
+ <vis name="SiVertexBarrelModuleVis"
+ alpha="1.0" r="1" g="1" b="0.6"
+ drawingStyle="solid"
+ showDaughters="true"
+ visible="true"/>
+ ....
+</display>
+\end{minted}
+
+\item {\textbf{<Limisets>}} contain parameters passed to Geant4:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+<limits>
+ <limitset name="cal_limits">
+ <limit name="step_length_max" particles="*" value="5.0" unit="mm" />
+ </limitset>
+</limits>
+\end{minted}
+
+\item {\textbf{The \texttt{detectors}}} section contains subtrees of the type \texttt{<detector>} which contain all parameters used by the \textit{detector constructors} to actually expand the geometrical structure. Each subdetector has a name and a type, where the type is used to call the proper constructor plugin. If the subdetector element is sensitive, a forward reference to the corresponding readout structure is mandatory. The remaining parameters are user defined:
+
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+<detectors>
+ <detector id="4" name="SiTrackerEndcap" type="SiTrackerEndcap" readout="SiTrackerEndcapHits">
+ <comment>Outer Tracker Endcaps</comment>
+ <module name="Module1" vis="SiTrackerEndcapModuleVis">
+ <trd x1="36.112" x2="46.635" z="100.114/2" />
+ <module_component thickness="0.00052*cm" material="Copper" />
+ <module_component thickness="0.03*cm" material="Silicon" sensitive="true" />
+ ...
+ </module>
+ ...
+ <layer id="1">
+ <ring r="256.716" zstart="787.105+1.75" nmodules="24" dz="1.75" module="Module1"/>
+ <ring r="353.991" zstart="778.776+1.75" nmodules="32" dz="1.75" module="Module1"/>
+ <ring r="449.180" zstart="770.544+1.75" nmodules="40" dz="1.75" module="Module1"/>
+ </layer>
+ ...
+ </detector>
+</detectors>
+\end{minted}
+
+\item {\textbf{The \texttt{<readouts>} section}} defined the encoding of sensitive volumes to so-called cell-ids, which are in DD4hep 64-bit integer numbers. The encoding is subdetector dependent with one exception: to uniquely identity each subdetector, the width of the system field must be the same.
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+<readouts>
+ <readout name="SiTrackerEndcapHits">
+ <id>system:8,barrel:3,layer:4,module:14,sensor:2,side:32:-2,strip:20</id>
+ </readout>
+ ...
+</readouts>
+\end{minted}
+
+\item {\textbf{Electromagnetic fields}} are described in the \texttt{<fields>} section. There may be several fields present. In DD4hep the resulting field vectors
+may be both electric and magnetic. The strength of the overall field is calculated as the superposition of the individual components:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+<fields>
+ <field name="GlobalSolenoid" type="solenoid"
+ inner_field="5.0*tesla"
+ outer_field="-1.5*tesla"
+ zmax="SolenoidCoilOuterZ"
+ outer_radius="SolenoidalFieldRadius">
+ </field>
+ ...
+</fields>
+\end{minted}
+\end{itemize}
+
+\section{Material Description}
+\label{sec:compact-material-description}
+
+Materials are needed by logical volumes. They are defined as isotopes, elements or mixtures. Elements can optionally be composed of isotopes. Composition is always done by specifying the fraction of the mass. Mixtures can be composed of elements or other mixtures. For a mixture the user can specify composition either by number of atoms or by fraction of mass. The materials sub-tree in section~\ref{sec:compact-xml-structure} shows the representation of an element, a simple material and a composite material in the \texttt{XML} format identical to GDML~\cite{Chytracek:2006be}. The snippet below shows how to define new material instances:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+<materials>
+ ...
+ <!-- (1) The description of an atomic element or isotope -->
+ <element Z="30" formula="Zn" name="Zn" >
+ <atom type="A" unit="g/mol" value="65.3955" />
+ </element>
+ <!-- (2) A composite material -->
+ <material name="Kapton">
+ <D value="1.43" unit="g/cm3" />
+ <composite n="22" ref="C"/>
+ <composite n="10" ref="H" />
+ <composite n="2" ref="N" />
+ <composite n="5" ref="O" />
+ </material>
+ <!-- (3) A material mixture -->
+ <material name="PyrexGlass">
+ <D type="density" value="2.23" unit="g/cm3"/>
+ <fraction n="0.806" ref="SiliconOxide"/>
+ <fraction n="0.130" ref="BoronOxide"/>
+ <fraction n="0.040" ref="SodiumOxide"/>
+ <fraction n="0.023" ref="AluminumOxide"/>
+ </material>
+ ...
+</materials>
+\end{minted}
+
+The \texttt{<materials>} sub-tree contains additional materials, which are not contained in the default materials tables. The snippet above shows different kinds of materials:
+\begin{itemize}
+\item[1.] Atomic elements as they are in the periodic table. The number of elements is finite. It is unlikely any client will have to extend the known elements.
+\item[2.] Composite materials, which consists of one or several elements forming a molecule. These materials have a certain density under normal conditions described in the child element \texttt{D}.
+For each \texttt{composite} the attribute \texttt{ref} denotes the element type by name, the attribute \texttt{n} denotes the atomic multiplicity. Typically each of the elements in (1) also forms such a material representing objects which consist of pure material like e.g. iron magnet yokes or copper wires.
+\item[3.] Last there are mixtures of composite materials to describe for example alloys, solutions or other mixtures of solid materials. This is the type of material used to actually create mechanical structures forming the assembly of an experiment. Depending on the manufacturing these materials have a certain density (\texttt{D}) and are composed of numerous molecules contributing to the resulting material with a given \texttt{fraction}. The sum of all fractions (attribute \texttt{n}) is 1.0.
+\end{itemize}
+``Real'' materials i.e. those you can actually touch are described in TGeo by the class \texttt{TGeoMedium}.
+\footnote{Typical beginner's mistake: Do not mix up the two classes \texttt{TGeoMaterial} and \texttt{TGeoMedium}! The material to define volumes is of type \texttt{TGeoMedium}, which also includes the
+description of the material's finish.}. Materials are not constructed by any client. Materials and elements are either already present in the the corresponding tables of the ROOT geometry package or they are added during the interpretation of the \texttt{XML} input. Clients access the description of material using the \texttt{Detector} interface.
+
+\begin{figure}[t]
+ \begin{center}
+ \includegraphics[width=160mm] {DD4hep-solids}
+ \caption{Extensions may be attached to common Detector Elements which
+ extend the functionality of the common DetElement
+ class and support e.g. caching of precomputed values.}
+ \label{fig:dd4hep-solids}
+ \end{center}
+ \vspace{-0.6cm}
+\end{figure}
+
+\section{Shapes}
+\label{dd4hep-basic-shapes}
+
+Shapes are abstract objects with a bounding surface and fixed dimensions. There are primitive, atomic shapes and complex boolean shapes as shown in Figure~\ref{fig:dd4hep-solids}. TGeo and similarly Geant4 offer a whole palette of primitive shapes, which can be used to construct more complex shapes:
+\begin{itemize}
+\item \texttt{Box} shape represented by the \texttt{TGeoBBox} class. To create a new box object call one of the following constructors:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+/// Constructor to be used when creating an anonymous new box object
+Box(double x, double y, double z);
+/// Constructor to be used when creating an anonymous new box object
+template<typename X, typename Y, typename Z> Box(const X& x, const Y& y, const Z& z);
+\end{minted}
+\item \texttt{Sphere} shape represented by the \texttt{TGeoSphere} class. To create a new sphere object call one of the following constructors:
+\item \texttt{Cone} shape represented by the \texttt{TGeoCone} class. To create a new cone object call one of the following constructors:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+/// Constructor to create a new anonymous object with attribute initialization
+Cone(double z,double rmin1,double rmax1,double rmin2,double rmax2);
+template<typename Z, typename RMIN1, typename RMAX1, typename RMIN2, typename RMAX2>
+Cone(const Z& z, const RMIN1& rmin1, const RMAX1& rmax1, const RMIN2& rmin2, const RMAX2& rmax2);
+\end{minted}
+\item \texttt{ConeSegment} shape represented by the \texttt{TGeoConeSeg} class. To create a new cone segment object call one of the following constructors:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+/// Constructor to create a new ConeSegment
+ConeSegment(double dz, double rmin1, double rmax1, double rmin2, double rmax2, double phi1=0.0, double phi2=2.0*M_PI);
+\end{minted}
+\item \texttt{Polycone} shape represented by the \texttt{TGeoPcon} class. To create a new polycone object call one of the following constructors:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+/// Constructor to create a new polycone object
+Polycone(double start, double delta);
+followed by a call to:
+void addZPlanes(const std::vector<double>& rmin,
+ const std::vector<double>& rmax,
+ const std::vector<double>& z);
+/// Constructor to create a new polycone object. Add at the same time all Z planes
+Polycone(double start, double delta,
+ const std::vector<double>& rmin,
+ const std::vector<double>& rmax,
+ const std::vector<double>& z);
+\end{minted}
+\item \texttt{TubeSegment} shape represented by the \tgeo{TGeoTubeSeg}{\texttt TGeoTubeSeg} class. To create a new tube segment object call one of the following constructors:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+Tube(double rmin, double rmax, double z, double deltaPhi=2*M_PI)
+Tube(double rmin, double rmax, double z, double startPhi, double deltaPhi)
+
+template<typename RMIN, typename RMAX, typename Z, typename DELTAPHI>
+Tube(const RMIN& rmin, const RMAX& rmax, const Z& z, const DELTAPHI& deltaPhi)
+
+template<typename RMIN, typename RMAX, typename Z, typename STARTPHI, typename DELTAPHI>
+Tube(const std::string& name, const RMIN& rmin, const RMAX& rmax, const Z& z,
+ const STARTPHI& startPhi, const DELTAPHI& deltaPhi)
+\end{minted}
+\item \texttt{Trapezoid} shape represented by the \texttt{TGeoTrd} class. To create a new trapezoid object call one of the following constructors:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+/// Constructor to create a new anonymous object with attribute initialization
+Trapezoid(double x1, double x2, double y1, double y2, double z);
+\end{minted}
+\item \texttt{Trap} shape represented by the \tgeo{TGeoTrap}{\texttt TGeoTrap} class. To create a new trap object call one of the following constructors:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+/// Constructor to create a new anonymous object with attribute initialization
+Trap(double z,double theta,double phi,
+ double y1,double x1,double x2,double alpha1,
+ double y2,double x3,double x4,double alpha2);
+/// Constructor to create a new anonymous object for right angular wedge from STEP (Se G4 manual for details)
+Trap( double pz, double py, double px, double pLTX);
+\end{minted}
+\item \texttt{Torus} shape represented by the \tgeo{TGeoTorus}{\texttt TGeoTorus} class. To create a new torus object call one of the following constructors:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+/// Constructor to create a new anonymous object with attribute initialization
+Torus(double r, double rmin, double rmax, double phi=M_PI, double delta_phi=2.*M_PI);
+\end{minted}
+\item \texttt{Paraboloid} shape represented by the \tgeo{TGeoParaboloid}{\texttt TGeoParaboloid} class. To create a new paraboloid object call one of the following constructors:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+/// Constructor to create a new anonymous object with attribute initialization
+Paraboloid(double r_low, double r_high, double delta_z);
+\end{minted}
+\item \texttt{PolyhedraRegular} shape represented by the \texttt{TGeoPgon} class. To create a new polyhedron object call one of the following constructors:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+/// Constructor to create a new object. Phi(start)=0, deltaPhi=2PI, Z-planes at +-zlen/2
+PolyhedraRegular(int nsides, double rmin, double rmax, double zlen);
+/// Constructor to create a new object. Phi(start)=0, deltaPhi=2PI, Z-planes at zplanes[0],[1]
+PolyhedraRegular(int nsides, double rmin, double rmax, double zplanes[2]);
+/// Constructor to create a new object with phi_start, deltaPhi=2PI, Z-planes at +-zlen/2
+PolyhedraRegular(int nsides, double phi_start, double rmin, double rmax, double zlen);
+\end{minted}
+\end{itemize}
+
+Besides the primitive shapes three types of boolean shapes (described in TGeo by the \texttt{TGeoCompositeShape} class) are supported:
+
+\begin{itemize}
+\item \texttt{UnionSolid} objects representing the union,
+\item \texttt{IntersectionSolid} objects representing the intersection,
+\item \texttt{SubtractionSolid} objects representing the subtraction,
+\end{itemize}
+
+of two other primitive or complex shapes. To build a boolean shape, the second shape is transformed in 3-dimensional space before the boolean operation is applied. The 3D transformations are described by objects from the \texttt{ROOT::Math} library and are supplied at construction time. Such a transformation as shown in the code snippet below may be
+
+\begin{itemize}
+\item The identity transformation. Then no transformation object needs to be provided (see line 2).
+\item A translation only described by a \texttt{Position} object (see line 4)
+\item A 3-fold rotation first around the Z-axis, then around the Y-axis and finally around the X-axis. For transformation operations of this kind a \texttt{RotationZYX} object must be supplied (see line 6).
+\item A generic 3D rotation matrix should be applied to the second shape. Then a \texttt{Rotation3D} object must be supplied (see line 8).
+\item Finally a generic 3D transformation (translation+rotation) may be applied using a \texttt{Transform3D} object (see line 10).
+\end{itemize}
+
+All three boolean shapes have constructors as shown here for the \texttt{UnionSolid}:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ /// Constructor to create a new object. Position is identity, Rotation is identity-rotation!
+ UnionSolid(const Solid& shape1, const Solid& shape2);
+ /// Constructor to create a new object. Placement by position, Rotation is identity-rotation!
+ UnionSolid(const Solid& shape1, const Solid& shape2, const Position& pos);
+ /// Constructor to create a new object. Placement by a RotationZYX within the mother
+ UnionSolid(const Solid& shape1, const Solid& shape2, const RotationZYX& rot);
+ /// Constructor to create a new object. Placement by a generic rotoation within the mother
+ UnionSolid(const Solid& shape1, const Solid& shape2, const Rotation3D& rot);
+ /// Constructor to create a new object. Placement by a generic transformation within the mother
+ UnionSolid(const Solid& shape1, const Solid& shape2, const Transform3D& pos);
+\end{minted}
+
+\subsection{Shape factories}
+Sometimes it is useful to create shapes in an ``abstract'' way e.g. to define areas in the detector. To create such shapes a factory method was implemented, which allows to create a valid shape handle given a valid \texttt{XML} element providing the required attributes. The factory methods are invoked using from \texttt{XML} elements of the following form:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+ <some_element type="shape-type" .... args ....>
+\end{minted}
+
+The shape is then constructed using the \texttt{XML} component object:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+#include "XML/Helper.h"
+
+xml_h e = <shape-element>;
+Box box = xml_comp_t(e).createShape();
+if ( !box.isValid() ) { /* ...handle error ... */ }
+\end{minted}
+The required arguments for the various shapes are then:
+\begin{itemize}
+\item For a Box:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+ <some_element type="Box" x="x-value" y="y-value" z="z-value"/>
+\end{minted}
+fulfilling a constructor of the type: \texttt{Box(dim.dx(), dim.dy(), dim.dz())}.
+
+\item For a Polycone:
+\vspace{-0.2cm}
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+ <some_element type="Polycone" start="start-phi-value" deltaphi="delta-phi-value">
+ <zplane z="z-value" rmin="rmin-value" rmax="rmax-value"/>
+ <zplane z="z-value" rmin="rmin-value" rmax="rmax-value"/>
+ .... any number of Z-planes ....
+ <zplane z="z-value" rmin="rmin-value" rmax="rmax-value"/>
+ </some_element>
+\end{minted}
+
+\item For a ConeSegment the following constructor must be fulfilled:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ConeSegment(e.rmin(0.0), e.rmax(), e.z(0.0), e.startphi(0.0), e.deltaphi(2*M_PI))}
+\end{minted}
+where the above default values for the \texttt{XML} attributes \texttt{rmin}, \texttt{z}, \texttt{startphi} and \texttt{deltaphi} are used if not explicitly stated in the \texttt{XML} element \texttt{e}.
+
+\item For a Tube the constructor is:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+Tube(e.rmin(0.0), e.rmax(), e.z(0.0), e.startphi(0.0), e.deltaphi(2*M_PI))
+\end{minted}
+
+\item For a Cone the constructor is:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+double rmi1 = e.rmin1(0.0), rma1 = e.rmax1();
+Cone(e.z(0.0), rmi1, rma1, e.rmin2(rmi1), e.rmax2(rma1))
+\end{minted}
+
+\item For a Trap the constructor is: if \texttt{dz} is specified:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+Trap(e.dz(), e.dy(), e.dx(),_toDouble(_Unicode(pLTX)))
+\end{minted}
+Otherwise:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+Trap(e.z(0.0), e.theta(), e.phi(0), e.y1(), e.x1(), e.x2(), e.alpha(), e.y2(), e.x3(), e.x4(), e.alpha2())
+\end{minted}
+\item For a Trapezoid the constructor is:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+Trapezoid(e.x1(), e.x2(), e.y1(), e.y2(), e.z(0.0))
+\end{minted}
+\item For a Torus the constructor is:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+Torus(e.r(), e.rmin(), e.rmax(), e.phi(M_PI), e.deltaphi(2.*M_PI))
+\end{minted}
+\item For a Sphere the constructor is:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+Sphere(e.rmin(), e.rmax(), e.deltatheta(M_PI), e.phi(0e0),e.deltaphi(2.*M_PI))
+\end{minted}
+\item For a Paraboloid the constructor is:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+Paraboloid(e.rmin(0.0), e.rmax(), e.dz())
+\end{minted}
+\item For a PolyhedraRegular the constructor is:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+PolyhedraRegular(e.numsides(), e.rmin(), e.rmax(), e.dz())
+\end{minted}
+\end{itemize}
+
+\section{Volumes and Placements}
+
+The detector geometry is described by a hierarchy of volumes and their corresponding placements. Both, the TGeo package and Geant4~\cite{Agostinelli:2002hh} are following effectively the same ideas ensuring an easy conversion from TGeo to Geant4 objects for the simulation application. A volume is an unplaced solid de\-scribed in terms of a primitive shape or a boolean operation of solids, a material and a number of placed sub-volumes (placed volumes) inside. The class diagram showing the relationships between volumes and placements, solids and materials is shown in Figure~\ref{fig:dd4hep-detector-model}.
+It is worth noting, that any volume has children, but no parent or ``mother'' volume. This is a direct consequence of the requirement to re-use volumes and place the same volume arbitrarily often. Only the act of placing a volume defines the relationship to the next level parent volume. The resulting geometry tree is very effective, simple and convenient to describe the detector geometry hierarchy starting from the top level volume representing e.g. the experiment cavern down to the very detail of the detector e.g. the small screw in the calorimeter. The top level volume is the very only volume without a placement. All geometry calculations, computations are always performed within the local coordinate system of the volume. The following example code shows how to create a volume which consists of a given material and with a shape. The created volume is then placed inside the mother-volume using the local coordinate system of the mother volume:
+
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ Volume mother = ....ampercent
+
+ Material mat (lcdd.material("Iron"));
+ Tube tub (rmin, rmax, zhalf);
+ Volume vol (name, tub, mat);
+ Transform3D tr (RotationZYX(rotz,roty,rotx),Position(x,y,z));
+ PlacedVolume phv = mother.placeVolume(vol,tr);
+\end{minted}
+
+The volume has the shape of a tube and consists of iron. Before being placed, the daughter volume is transformed within the mother coordinate system according to the requested transformation. The example also illustrates how to access \texttt{Material} objects from the \texttt{Detector} interface.
+
+The {\texttt{Volume}} class provides several possibilities to declare the required space transformation necessary to place a daughter volume within the mother:
+\begin{itemize}
+\item to place a daughter volume unrotated at the origin of the mother, the
+transformation is the identity. Use the following call to place the daughter:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+PlacedVolume placeVolume(const Volume& vol) const;
+\end{minted}
+\item If the positioning is described by a simple translation, use:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+PlacedVolume placeVolume(const Volume& vol, const Position& pos) coampercentnst;
+\end{minted}
+\item In case the daughter should be rotated first around the Z-axis, then around the Y-axis and finally around the X-axis place the daughter using this call:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+PlacedVolume placeVolume(const Volume& vol, const RotationZYX& rot) const;
+\end{minted}
+\item If the full 3-dimensional rotation matrix is known use:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+PlacedVolume placeVolume(const Volume& vol, const Rotation3D& rot) const;
+\end{minted}
+\item for an entirely unconstrained placement place the daughter providing a \texttt{Transform3D} object:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+PlacedVolume placeVolume(const Volume& volume, const Transform3D& tr) const;
+\end{minted}
+\end{itemize}
+
+For more details of the \texttt{Volume} and the \texttt{PlacedVolume} classes please see the header file \texttt{Volumes.h}.
+
+One volume like construct is special: the assembly constructs. Assemblies are volumes without shapes. The ``assembly'' shape does not own a own surface by itself, but rather defines it's surface and
+bounding box from the contained children. In this corner also the implementation concepts between TGeo and Geant4 diverge. Whereas TGeo handles assemblies very similar to real volumes, in Geant4 assemblies are purely artificial and disappear at the very moment volumes are placed.
+
+\section{Detector Elements}
+\label{sec:dd4hep-user-manual-detector-elements}
+
+\begin{figure}[b]
+ \begin{center}
+ \includegraphics[width=160mm] {DD4hep-detelement-drawing}
+ \caption{The basic layout of the \texttt{DetElement} class aggregating
+ all data entities necessary to process data.}
+ \label{fig:dd4hep-user-manual-detelement-drawing}
+ \end{center}
+ \vspace{-0.6cm}
+\end{figure}
+
+Detector elements (class \texttt{DetElement}) are entities which represent subdetectors or sizable parts of a subdetector. As shown in Figure~\ref{fig:dd4hep-user-manual-detelement-drawing}, a \texttt{DetElement} instance has the means to provide to clients information about
+
+\begin{itemize}
+\item generic properties like the detector type or the path within the \texttt{DetElement}s hierarchy:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ /// Access detector type (structure, tracker, calorimeter, etc.).
+ std::string type() const;
+ /// Path of the detector element (not necessarily identical to placement path!)
+ std::string path() const;
+\end{minted}
+
+\item the detector hierarchy by exposing its children. The hierarchy may be accessed with the following API:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ /// Add new child to the detector structure
+ DetElement& add(DetElement sub_element);
+ /// Access to the list of children
+ const Children& children() const;
+ /// Access to individual children by name
+ DetElement child(const std::string& name) const;
+ /// Access to the detector elements's parent
+ DetElement parent() const;
+\end{minted}
+
+\item its placement within the overall experiment if it represents an entire subdetector or its placement with respect to its parent if the \texttt{DetElement} represents a part of a subdetector. The placement path is the fully qualified path of placed volumes from the top level volume to the placed detector element. % and may serve as a shortcut for the eqnarrayment implementation:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ /// Access to the full path to the placed object
+ std::string placementPath() const;
+ /// Access to the physical volume of this detector element
+ PlacedVolume placement() const;
+ /// Access to the logical volume of the daughter placement
+ Volume volume() const;
+\end{minted}
+
+\item information about the environmental conditions etc. (\texttt{conditons}):
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ /// Access to the conditions information
+ Conditions conditions() const;
+\end{minted}
+
+%\item eqnarrayment information:
+%\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+% /// Access to the eqnarrayment information
+% eqnarrayment eqnarrayment() const;
+%\end{minted}
+
+\item convenience information such as cached transformations to/from the top level volume, to/from the parent \texttt{DetElement} and to/from another \texttt{DetElement} in the hierarchy above:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ /// Transformation from local coordinates of the placed volume to the world system
+ bool localToWorld(const Position& local, Position& global) const;
+ /// Transformation from world coordinates of the local placed volume coordinates
+ bool worldToLocal(const Position& global, Position& local) const;
+
+ /// Transformation from local coordinates of the placed volume to the parent system
+ bool localToParent(const Position& local, Position& parent) const;
+ /// Transformation from world coordinates of the local placed volume coordinates
+ bool parentToLocal(const Position& parent, Position& local) const;
+
+ /// Transformation from local coordinates of the placed volume to arbitrary parent system set as reference
+ bool localToReference(const Position& local, Position& reference) const;
+ /// Transformation from world coordinates of the local placed volume coordinates
+ bool referenceToLocal(const Position& reference, Position& local) const;
+
+ /// Set detector element for reference transformations.
+ /// Will delete existing reference transformation.
+ DetElement& setReference(DetElement reference);
+\end{minted}
+
+\item User extension information as described in section~\ref{sec:dd4hep-user-manual-data-extensions}:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ /// Extend the detector element with an arbitrary structure accessible by the type
+ template <typename IFACE, typename CONCRETE> IFACE* addExtension(CONCRETE* c);
+ /// Access extension element by the type
+ template <class T> T* extension() const;
+\end{minted}
+
+\end{itemize}
+
+\section{Sensitive Detectors}
+\label{sec:dd4hep-user-manual-sensitive-detectors}
+
+Though the concept of sensitive detectors comes from Geant4 and simulation activities, in DD4hep the sensitive detectors are the client interface to access the readout description (class \texttt{Readout}) with its segmentation of sensitive elements (class \texttt{Segmentation}) and the description of hit decoders (class \texttt{IDDescriptors}). As shown in Figure~\ref{fig:dd4hep-sensitive-detectors}, these object instances are required when reconstructing data from particle collisions.
+
+Besides the access to data necessary for reconstruction the sensitive detector also hosts Region setting (class \texttt{Region} and sets of cut limits (class \texttt{LimitSets}) used to configure the Geant4 simulation toolkit. The following code snippet shows the accessors of the \texttt{SensitiveDetector} class to obtain the corresponding information~\footnote{The methods to set the data are not shown here.}:
+
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ struct SensitiveDetector: public Ref_t {
+ /// Access the hits collection name
+ const std::string& hitsCollection() const;
+ /// Access readout structure of the sensitive detector
+ Readout readout() const;
+ /// Access to the region setting of the sensitive detector (not mandatory)
+ Region region() const;
+ /// Access to the limit set of the sensitive detector (not mandatory).
+ LimitSet limits() const;
+
+ /// Extend the sensitive detector element with an arbitrary structure accessible by the type
+ template <typename IFACE, typename CONCRETE> IFACE* addExtension(CONCRETE* c);
+ /// Access extension element by the type
+ template <class T> T* extension() const;
+ };
+\end{minted}
+
+\begin{figure}[h]
+ \begin{center}
+ \includegraphics[width=140mm] {DD4hep-sensitive-detectors}
+ \caption{The structure of DD4hep sensitive detectors.}
+ \label{fig:dd4hep-sensitive-detectors}
+ \end{center}
+ \vspace{-0.6cm}
+\end{figure}
+
+Sensitive detector objects are automatically creating using the information of the \texttt{<readout>} section of the \texttt{XML} file if a subdetector is sensitive and references a valid readout entry. In the detector constructor (or any time later) clients may add additional information to a sensitive detector object using an extension mechanism similar to the extension mechanism for detector elements mentioned earlier.
+
+Volumes may be shared and reused in several placements. In the parallel hierarchy of detector elements as shown in Figure~\ref{fig:dd4hep-hierarchies}, the detector elements may reference unambiguously the volumes of their respective placements, but not the reverse. However, the sensitive detector setup is a single instance per subdetector. Hence it may be referenced by all sensitive Volumes of one subdetector. In the following chapters the access to the readout structure is described.
+
+\section{Description of the Readout Structure}
+\label{sec:dd4hep-manual-readout-description}
+
+The \texttt{Readout} class describes the detailed structure of a sensitve volume. The for example may be the layout of strips or pixels in a silicon detector i.e. the description of entities which would not be modeled using individual volumes and placements though this would theoretically feasible. Each sensitive element is segmented according to the \texttt{Segmentation} object and hits resulting from energy depositions in the sensitive volume are encoded using the \texttt{IDDescriptor} object.
+
+\begin{figure}[h]
+ \begin{center}
+ \includegraphics[width=100mm] {DD4hep-readout}
+ \caption{The basic components to describe the \texttt{Readout} structure
+ of a subdetector. }
+ \label{fig:dd4hep-sensitive-detectors}
+ \end{center}
+ \vspace{-0.6cm}
+\end{figure}
+
+\subsection{CellID Descriptors}
+\label{sec:dd4hep-manual-readout-iddescriptors}
+
+\texttt{IDDescriptor}s define the encoding of sensitive volumes to uniquely identify the location of the detector response. The encoding defines a bit-field with the length of 64 bits. The first field is mandatory called \texttt{system} and identifies the subdetector. All other fields define the other volumes in the hierarchy. The high bits are not necessarily mapped to small daughter volumes, but may simply identify a logical segmentation such as the \texttt{strip} \texttt{number} within a wafer of a vertex detector as shown in the following \texttt{XML} snippet:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+<readouts>
+ <readout name="SiVertexEndcapHits">
+ <id>system:8,barrel:3,layer:4,module:14,sensor:2,side:32:-2,strip:24</id>
+ </readout>
+<readouts>
+\end{minted}
+These identifiers are the data input to \texttt{segmentation classes}~\ref{sec:dd4hep-manual-readout-segmentations}, which define a user friendly API to en/decode the detector response.
+
+\subsection{Segmentations}
+\label{sec:dd4hep-manual-readout-segmentations}
+
+Segementations define the user API to the low level interpretation of the energy deposits in a subdetector. For technical reasons and partial religious reasons are the segmentation implementation not part of the DD4hep toolkit, but an independent package call \texttt{DDSegmentation}. Though the usage is an integral part of DD4hep.
+
+\subsection{Volume Manager}
+The \texttt{VolumeManager} is a tool to seek a lookup table of placements of sensitive volumes and their corresponding unique volume identifier, the \texttt{cellID}. The volume manager analyzes - once the geometry is closed - the hierarchical tree and stores the various placements in the hierarchy with respect to their identifiers. In other words the the tree is reused volumes shown e.g. in Figure~\ref{fig:dd4hep-hierarchies} is degenerated according to the full pathes of the various volumes. This use case is very common to reconstruction and analysis applications whenever a given raw-data (aka ``hit'') element must be related to its geometrical location.
+
+Figure~\ref{fig:dd4hep-user-manual-volmgr} shows the design diagram of this component:
+\begin{figure}[h]
+ \begin{center}
+ \includegraphics[width=170mm] {DD4hep-volmgr}
+ \caption{Extensions may be attached to common Detector Elements which
+ extend the functionality of the common DetElement
+ class and support e.g. caching of precomputed values.}
+ \label{fig:dd4hep-user-manual-volmgr}
+ \end{center}
+\end{figure}
+
+To optimize the access of complex subdetector structures, is the volume-identifier map split and the volumes of each each subdetector is stored in a separate map. This optimization however is transparent to clients. The following code extract from the header files lists the main client routines to extract volume information given a known \texttt{cellID}:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ /// Lookup the context, which belongs to a registered physical volume.
+ Context* lookupContext(VolumeID volume_id) const;
+ /// Lookup a physical (placed) volume identified by its 64 bit hit ID
+ PlacedVolume lookupPlacement(VolumeID volume_id) const;
+ /// Lookup a top level subdetector detector element
+ /// according to a contained 64 bit hit ID
+ DetElement lookupDetector(VolumeID volume_id) const;
+ /// Lookup the closest subdetector detector element in the hierarchy
+ /// according to a contained 64 bit hit ID
+ DetElement lookupDetElement(VolumeID volume_id) const;
+ /// Access the transformation of a physical volume to the world coordinate system
+ const TGeoMatrix& worldTransformation(VolumeID volume_id) const;
+\end{minted}
+
+
+\subsection{Static Electric and Magnetic Fields}
+\label{sec:dd4hep-manual-static-fields}
+
+The generic field is described by a structure of any field type (electric or magnetic) with field components in Cartesian coordinates. The overlay field is the sum of several magnetic of electric field components
+and the resulting field vectors are computed by the vector addition of the individual components. The available components are described in the following. If necessary new field implementations may be added at any time: they are instantiated when necessary by the factory mechanism. Fields are described in the compact model within the {\texttt{<fields>}} tags the following example shows:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+ <fields>
+ <field name="MyMagnet" type="solenoid" .... />
+ </fields>
+\end{minted}
+The actual components are defined one by one within the {\texttt{<field>}} tags.
+
+Constant Electric or Magnetic Fields are defined as follows:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+ <field name="MyMagnet" type="ConstantField" field="electric">
+ <strength x="x-val" y="y-val" z="z-val"/>
+ </field>
+\end{minted}
+The {\texttt{field}} attribute accepts take the values {\texttt{[electric,magnetic]}} depending on it's nature.
+
+Magnetic Dipoles are defined as follows:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+ <field name="MyMagnet" type="DipoleMagnet"
+ rmax="50*cm"
+ zmin="0*cm"
+ zmax="50*cm">
+ <dipole_coeff>1.0*tesla</dipole_coeff>
+ <dipole_coeff>0.1*tesla/pow(cm,1)</dipole_coeff>
+ <dipole_coeff>0.01*tesla/pow(cm,2)</dipole_coeff>
+ </field>
+\end{minted}
+
+Magnetic Multipole Fields are developed according to their approximation using the multipole coefficients. The dipole is assumed to be horizontal as it is used for bending beams in large colliders
+ie. the dipole field lines are vertical.
+
+The different momenta are given by:
+\begin{eqnarray*}
+B_n^{\mathrm{norm}}(x)&=& \frac{cp}{e} \sum_{m=1}^{\frac{n}{2}} \frac{(-1)^{m-1} C_n y^{2 m-1} x^{n-2 m}}{(2 m-1)! (n-2 m)!} \quad, \\
+B_n^{\mathrm{norm}}(y)&=& \frac{cp}{e} \sum_{m=0}^{\frac{n-1}{2}} \frac{(-1)^m y^{2 m} S_n x^{-2 m+n-1}}{(2 m)! (-2 m+n-1)!} \quad, \\
+B_n^{\mathrm{skew}}(x)&=& \frac{cp}{e} \sum_{m=0}^{\frac{n-1}{2}} \frac{(-1)^m y^{2 m} S_n x^{-2 m+n-1}}{(2 m)! (-2 m+n-1)!} \quad, \\
+B_n^{\mathrm{skew}}(y)&=& \frac{cp}{e} \sum_{m=1}^{\frac{n}{2}} \frac{(-1)^m y^{2 m-1} S_n x^{n-2 m}}{(2 m-1)! (n-2 m)!}\quad.
+\end{eqnarray*}
+With $C_n$ being ``normal multipole coefficients'' and $S_n$ the ``skew multipole coefficients''. The maximal momentum used is the octopole momentum. The lower four momenta are used
+to describe the magnetic field:
+\begin{itemize}
+\item Dipole (n=1):
+ \begin{eqnarray*}
+ B_x &=& S_1\quad, \\
+ B_y &=& C_1\quad, \\
+ B_z &=& constant\quad.
+ \end{eqnarray*}
+\item Quadrupole (n=2):
+ \begin{eqnarray*}
+ B_x &=& C_2 y+S_2 x\quad, \\
+ B_y &=& C_2 x-S_2 y\quad.
+ \end{eqnarray*}
+\item Sextupole (n=3):
+ \begin{eqnarray*}
+ B_x &=& C_3 x y+\frac{S_3 x^2}{2}-\frac{S_3 y^2}{2}\quad, \\
+ B_y &=& \frac{C_3 x^2}{2}-\frac{C_3 y^2}{2}-S_3 x y\quad.
+ \end{eqnarray*}
+
+\item Octopole (n=4):
+ \begin{eqnarray*}
+ B_x &=& \frac{1}{2} C_4 x^2 y-\frac{C_4 y^3}{6}+\frac{S_4 x^3}{6}-\frac{1}{2} S_4 x y^2\quad,\\
+ B_y &=& \frac{C_4 x^3}{6}-\frac{1}{2} C_4 x y^2-\frac{1}{2} S_4 x^2 y+\frac{S_4 y^3}{6}\quad.
+ \end{eqnarray*}
+\end{itemize}
+The defined field components only apply within the shape 'volume'. If 'volume' is an invalid shape (ie. not defined), then the field components are valied throughout the 'universe'.
+
+The magnetic multipoles are defined as follows:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+<field name="MyMagnet" type="MultipoleMagnet">
+ <position x="0" y="0" z="0"/>
+ <rotation x="pi" y="0" z="0"/>
+ <shape type="shape-constructor-type" .... args .... >
+ <coeffizient coefficient="coeff(n=1)" skew="skew(n=1)"/>
+ .... maximum of 4 coefficients ....
+ <coeffizient coefficient="coeff(n=4)" skew="skew(n=4)"/>
+</field>
+\end{minted}
+The shape defines the geometrical coverage of the multipole field in the origin (See section~\ref{dd4hep-basic-shapes} for details). This shape may then be transformed to the required location in the detector area using the position and the rotation elements, which define this transformation.
+
+
+\section{Detector Constructors}
+\label{sec:dd4hep-manual-detector-constructors}
+
+The creation of appropriate detector constructors is the main work of a client defining his own detector. The detector constructor is a fragment of code in the form of a routine, which return a handle to the created subdetector \texttt{DetElement} object.
+
+Knowing that detector constructors are the main work items of clients significant effort was put in place to ease and simplify this procedure as much as possible in order to obtain readable, still compact code hopefully easy to maintain. The interfaces to all objects, \texttt{XML} accessors, shapes, volumes etc. which were discussed above were optimized to support this intention.
+
+To illustrate the anatomy of such a constructor the following code originating from an existing SiD detector concept will be analyzed. The example starts with the \texttt{XML} input data. Further down this section the code is shown with a detailed description of every relevant line. The object to be build is a subdetector representing a layered calorimeter, where each layer consists of a number of slices as shown in the \texttt{XML} snippet. These layers are then repeated a number of times.
+
+The \texttt{XML} snippet describing the subdetector properties:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{xml}
+ <detector id="13" name="LumiCal" reflect="true" type="CylindricalEndcapCalorimeter"
+ readout="LumiCalHits" vis="LumiCalVis" calorimeterType="LUMI">
+ <comment>Luminosity Calorimeter</comment>
+ <dimensions inner_r = "LumiCal_rmin" inner_z = "LumiCal_zmin" outer_r = "LumiCal_rmax" />
+ <layer repeat="20" >
+ <slice material = "TungstenDens24" thickness = "0.271*cm" />
+ <slice material = "Silicon" thickness = "0.032*cm" sensitive = "yes" />
+ <slice material = "Copper" thickness = "0.005*cm" />
+ <slice material = "Kapton" thickness = "0.030*cm" />
+ <slice material = "Air" thickness = "0.033*cm" />
+ </layer>
+ <layer repeat="15" >
+ <slice material = "TungstenDens24" thickness = "0.543*cm" />
+ <slice material = "Silicon" thickness = "0.032*cm" sensitive = "yes" />
+ <slice material = "Copper" thickness = "0.005*cm" />
+ <slice material = "Kapton" thickness = "0.030*cm" />
+ <slice material = "Air" thickness = "0.033*cm" />
+ </layer>
+ </detector>
+\end{minted}
+
+The \texttt{C++} code snippet interpreting the \texttt{XML} data and expanding the geometry:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{c++}
+#include "DD4hep/DetFactoryHelper.h"
+#include "XML/Layering.h"
+
+using namespace std;
+using namespace dd4hep;
+
+static Ref_t create_detector(Detector& lcdd, xml_h e, SensitiveDetector sens) {
+ xml_det_t x_det = e;
+ string det_name = x_det.nameStr();
+ bool reflect = x_det.reflect();
+ xml_dim_t dim = x_det.dimensions();
+ double zmin = dim.inner_z();
+ double rmin = dim.inner_r();
+ double rmax = dim.outer_r();
+ double totWidth = Layering(x_det).totalThickness();
+ double z = zmin;
+ Material air = lcdd.air();
+ Tube envelope (rmin,rmax,totWidth,0,2*M_PI);
+ Volume envelopeVol(det_name+"_envelope",envelope,air);
+ int layer_num = 1;
+ PlacedVolume pv;
+
+ // Set attributes of slice
+ for(xml_coll_t c(x_det,_U(layer)); c; ++c) {
+ xml_comp_t x_layer = c;
+ double layerWidth = 0;
+ for(xml_coll_t l(x_layer,_U(slice)); l; ++l)
+ layerWidth += xml_comp_t(l).thickness();
+
+ for(int i=0, m=0, repeat=x_layer.repeat(); i<repeat; ++i, m=0) {
+ double zlayer = z;
+ string layer_name = det_name + _toString(layer_num,"_layer%d");
+ Volume layer_vol(layer_name,Tube(rmin,rmax,layerWidth),air);
+
+ for(xml_coll_t l(x_layer,_U(slice)); l; ++l, ++m) {
+ xml_comp_t x_slice = l;
+ double w = x_slice.thickness();
+ string slice_name = layer_name + _toString(m+1,"slice%d");
+ Material slice_mat = lcdd.material(x_slice.materialStr());
+ Volume slice_vol (slice_name,Tube(rmin,rmax,w),slice_mat);
+
+ if ( x_slice.isSensitive() ) {
+ sens.setType("calorimeter");
+ slice_vol.setSensitiveDetector(sens);
+ }
+ slice_vol.setAttributes(lcdd, x_slice.regionStr(), x_slice.limitsStr(), x_slice.visStr());
+ pv = layer_vol.placeVolume(slice_vol, Position(0,0,z-zlayer-layerWidth/2+w/2));
+ pv.addPhysVolID("slice",m+1);
+ z += w;
+ }
+ layer_vol.setVisAttributes(lcdd,x_layer.visStr());
+ Position layer_pos(0,0,zlayer-zmin-totWidth/2+layerWidth/2);
+ pv = envelopeVol.placeVolume(layer_vol,layer_pos);
+ pv.addPhysVolID("layer",layer_num);
+ ++layer_num;
+ }
+ }
+ // Set attributes of slice
+ envelopeVol.setAttributes(lcdd, x_det.regionStr(), x_det.limitsStr(), x_det.visStr());
+
+ DetElement sdet(det_name,x_det.id());
+ Volume motherVol = lcdd.pickMotherVolume(sdet);
+ PlacedVolume phv = motherVol.placeVolume(envelopeVol,Position(0,0,zmin+totWidth/2));
+ phv.addPhysVolID("system",sdet.id()).addPhysVolID("barrel",1);
+ sdet.setPlacement(phv);
+ if ( reflect ) {
+ phv=motherVol.placeVolume(envelopeVol, Transform3D(RotationZ(M_PI), Position(0,0,-zmin-totWidth/2)));
+ phv.addPhysVolID("system",sdet.id()).addPhysVolID("barrel",2);
+ }
+ return sdet;
+}
+
+DECLARE_DETELEMENT(CylindricalEndcapCalorimeter,create_detector);
+\end{minted}
+{\small
+\begin{tabular} {p{0.1\linewidth}|p{0.9\linewidth}}
+\hline \\
+1 & The include file DetFactoryHelper.h includes allutilities to extract \texttt{XML} information together with the appropriate type definition.\\
+4-5 & Convenience shortcut to save ourself a lot of typing.\\
+7 & The entry point to the detector constructor. This routine shall be called by the plugin mechanism.\\
+8 & The functionality of the raw \texttt{XML} handle \texttt{xml\_h} is rather limited. A simple assignment to a \texttt{XML} detector object gives us all the functionality we need.\\
+9--10 & Extracting the sub-detector name and properties from the xml handle.\\
+11--16 & Access the \texttt{dimension} child-element from the \texttt{XML} subtree, access the element's attributes and precompute values used later.\\
+17 & Retrieve a reference to the ``air'' material from \texttt{Detector}.\\
+18--19 & Construct the envelope volume shaped as a tube made out of air.\\
+24 & Now the detector can be built: We loop over all layers types and overeach layer type as often as necessary (attribute: repeat).The \texttt{XML} collection object will return all child elements of \texttt{x\_det}with a tag-name ``layer''. Note the macro $\texttt{\_U(layer)}$: When using Xerces-C as an \texttt{XML} parser, it will expand to the reference to an object containing the unicode value of the string ``layer''. The full list of predefined tag names can be found in theinclude file \texttt{XML/UnicodeValues.h}.If a user tag is not part in the precompiled tag list, the corresponding Unicodestring may be created with the macro \texttt{\_Unicode(layer)} or \texttt{Unicode("layer")}.\\
+25 & Convenience assignment to extract attributes of the layer element.\\
+26--28 & Compute total layer width.\\
+30 & Create \texttt{repeat} number of layers of the same type.\\
+31-33 & Create the named envelope volume with a tube shape containing all slices of this layer.\\
+35-50 & Create the different layer-slices with a tube shape and the corresponding material as indicated in the \texttt{XML} data.\\
+42-45 & If the slice is sensitive i.e. is instrumented and supposed to deliver signals from particle passing, the sensitive detector component of thisdetector needs to be attached to the slice.\\
+46 & Set visualization and geant4 attributes to the slice volume. If the attributes are not present, they will be ignored.\\
+47 & Now the created slice volume will be placed inside the mother, the layer envelope at the correct position. This operation results in the creation of a \texttt{PlacedVolume}.\\
+48 & It identify uniquely every slice within the layer an identifier (here the number of the created slice) is attached. This identifier must be present in the bitmap defined by the \texttt{IDDescriptor} of this subdetector.\\
+52-55 & Same as 46-48, but now the created layer volume is placed in the envelope of the entire subdetector.\\
+59 & Set envelope attributes.\\
+61 & Construct the main detector element of this subdetector.This will be the unique entry point to access any information of the subdetector. {\textbf{Note:}} the subdetector my consist of a hierarchy of detector elements.For example each layer could be described by it's own \texttt{DetElement} and alllayer-\texttt{DetElement} instances being children of the subdetector instance.\\
+62-62 & Place the subdetector envelope into its mother (typically the top level (world) volume).\\
+64-65 & Add the missing \texttt{IDDescriptor} identifiers to complete the bitmap.\\
+66 & Store the placement in the subdetector detector element in order to make it availible to later clients of this \texttt{DetElement}. \\
+67-69 & Endcap calorimeters typically are symmetric i.e. an endcap is located on each side of the barrel. To easy such reflections the entire endcap structure can be copied and placed again. \\
+70 & All done. Return the created subdetector element to the caller for registration. \\
+73 & \textbf{Very important:} Without the registration of the construction function to the framework, the corresponding plugin will not be found. The macro has two arguments: firstly the plugin name which is identical to the detector type in the \texttt{XML} snippet and secondly the function to be called at construction time.
+\end{tabular}
+}
+\section{Tools and Utilities}
+
+
+\subsection{Geometry Visualization}
+\label{sec:dd4hep-manual-geometry-visualization}
+
+Visualizing the geometry is an important tool to debug and validate the constructed detector. Since DD4hep uses the \texttt{ROOT} geometry package, all visualization tools from ROOT are automatically supported. This is in the first place the OpenGL canvas of \texttt{ROOT} and all elaborated derivatives thereof such as event displays etc. Figure~\ref{fig:dd4hep-user-manual-visualization-subdetector} shows as an example the subdetector example from the \texttt{SiD} detector design discussed in section~\ref{sec:dd4hep-manual-detector-constructors}.
+\begin{figure}[h]
+ \begin{center}
+ \begin{tabular}{l r}
+ \includegraphics[width=80mm] {DD4hep-Lumical} &
+ \includegraphics[width=80mm] {DD4hep-Lumical-detailed} \\
+ \end{tabular}
+ \caption{Geometry visualization using the ROOT OpenGL plugin.
+ To the left the entire luminosity calorimeter is shown,
+ at the right the detailed zoomed view with clipping to
+ access the internal layer and slice structure.}
+ \label{fig:dd4hep-user-manual-visualization-subdetector}
+ \end{center}
+\end{figure}
+
+The command to create the display is part of the DD4hep release:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{bash}
+$> geoDisplay -compact <path to the \texttt{XML} file containing the detector description>
+
+ DD4hepGeometryDisplay -opt [-opt]
+ -compact <file> Specify the compact geometry file
+ [REQUIRED] At least one compact geo file is required!
+ -build_type <number/string> Specify the build type
+ [OPTIONAL] MUST come immediately after the -compact input.
+ Default for each file is: BUILD_DEFAULT [=1]
+ Allowed values: BUILD_SIMU [=1], BUILD_RECO [=2] or BUILD_DISPLAY [=3]
+ -destroy [OPTIONAL] Force destruction of the Detector instance
+ before exiting the application
+ -volmgr [OPTIONAL] Load and populate phys.volume manager to
+ check the volume ids for duplicates etc.
+ -print <number/string> Specify output level. Default: INFO(=3)
+ [OPTIONAL] Allowed values: VERBOSE(=1), DEBUG(=2),
+ INFO(=3), WARNING(=4), ERROR(=5), FATAL(=6)
+ The lower the level, the more printout...
+ -load_only [OPTIONAL] Dry-run to only load geometry without
+ starting the dispay.
+\end{minted}
+
+
+\subsection{Geometry Conversion}
+\label{sec:dd4hep-manual-geometry-conversion}
+
+\texttt{ROOT} \texttt{TGeo} is only one representation of a detector geometry. Other applications may require other representation. In particular two other are worth mentioning:
+\begin{itemize}
+\item \texttt{Detector}~\cite{Gaede:81331} the geometry representation used to simulate the ILC detector design with the \texttt{slic} application.
+\item \texttt{GDML}~\cite{Chytracek:2006be} a geometry markup language understood by Geant4 and \texttt{ROOT}.
+\end{itemize}
+Both conversions are supported in DD4hep with the geoConverter application:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{bash}
+ geoConverter -opt [-opt]
+ Action flags: Usage is exclusive, 1 required!
+ -compact2lcdd Convert compact xml geometry to lcdd.
+ -compact2gdml Convert compact xml geometry to gdml.
+ -compact2vis Convert compact xml to visualisation attrs
+
+ -input <file> [REQUIRED] Specify input file.
+ -output <file> [OPTIONAL] Specify output file.
+ if no output file is specified, the output
+ device is stdout.
+ -ascii [OPTIONAL] Dump visualisation attrs in csv format.
+ [Only valid for -compact2vis]
+\end{minted}
+
+\subsection{Overlap checking}
+\label{sec:dd4hep-manual-overlap-checking}
+
+Overlap checks are an important tool to verify the consistency of the implemented geometrical design. As in the real world, where overlaps are impossible, also simulated geometries may not have overlaps. In simulation overlaps tend to create particle reflections possibly leading to infinite loops.
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{bash}
+ python <install>/DD4hep/bin/checkOverlaps.py --help
+ Usage: checkOverlaps.py [options]
+
+ Check TGeo geometries for overlaps.
+
+ Options:
+ -h, --help show this help message and exit
+ -c <FILE>, --compact=<FILE> Define LCCDD style compact xml input
+ -p <boolean>, --print=<boolean> Print overlap information to standard output
+ (default:True)
+ -q, --quiet Do not print (disable --print)
+ -t <double number>, --tolerance=<double number>
+ Overlap checking tolerance. Unit is in [mm].
+ (default:0.1 mm)
+ -o <string>, --option=<string> Overlap checking option ('' or 's')
+\end{minted}
+
+\subsection{Geometry checking}
+\label{sec:dd4hep-manual-geometry-checking}
+
+Perform extensive geometry checks. For details and up to date information please refer to the ROOT documentation of the class {\texttt{TGeoManager}}:
+\begin{itemize}
+\item Member function \texttt{TGeoManager::CheckGeometry} and
+\item Member function \texttt{TGeoManager::CheckGeometryFull}
+\end{itemize}
+
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{bash}
+ python <install>DD4hep/bin/checkGeometry.py --help
+ Usage: checkGeometry.py [options]
+
+ TGeo Geometry checking.
+
+ Options:
+ -h, --help show this help message and exit
+ -c <FILE>, --compact=<FILE> Define LCCDD style compact xml input
+ -f <boolean>, --full=<boolean> Full geometry checking
+ -n <integer>, --ntracks=<integer> Number of tracks [requires 'full']
+ -x <double>, --vx=<double> X-position of track origine vertex [requires 'full']
+ -y <double>, --vy=<double> Y-position of track origine vertex [requires 'full']
+ -z <double>, --vz=<double> Z-position of track origine vertex [requires 'full']
+ -o <string>, --option=<string> Geometry checking option default:ob
+\end{minted}
+
+The full geometry check performs the \texttt{TGeoManager:CheckGeometryFull} following actions:
+\begin{itemize}
+\item if option contains 'o': Optional overlap checkings (by sampling and by mesh).
+\item if option contains 'b': Optional boundary crossing check + timing per volume.
+\end{itemize}
+\begin{description}
+\item[STAGE 1] extensive overlap checking by sampling per volume. Stdout need to be checked by user to get report, then \texttt{TGeoVolume::CheckOverlaps(0.01, "s")} can be called for the suspicious volumes.
+\item[STAGE 2] normal overlap checking using the shapes mesh - fills the list of overlaps.
+\item[STAGE 3:] shooting NTRACKS rays from vertex \texttt{(vx,vy,vz)} and counting the total number of crossings per volume (rays propagated from boundary to boundary until geometry exit). Timing computed and results stored in a histogram.
+\item[STAGE 4:] shooting 1 mil. random rays inside EACH volume and calling FindNextBoundary() + Safety() for each call. The timing is normalized by the number of crossings computed at stage 2 and presented as percentage. One can get a picture on which are the most ``burned'' volumes during transportation from geometry point of view. Another plot of the timing per volume vs. number of daughters is produced.
+\end{description}
+
+\subsection{Directional Material Scans}
+\label{sec:dd4hep-manual-directional-material-scans}
+
+Print the materials on a straight line between the two given points:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{bash}
+materialScan
+ usage: print_materials compact.xml x0 y0 z0 x1 y1 z1
+ -> prints the materials on a straight line between the two given points ( unit is cm)
+\end{minted}
+\texttt{materialScan} uses the python bindings provided by Geant4 and may be not always availible. Alternatively the command \texttt{print\_materials} may be used, which does not use the python binding, but produces less pretty output.
+
+
+\subsection{Plugin Test Program}
+\label{sec:dd4hep-manual-plugin-test}
+
+The plugin tester loads a given geometry and the executes a plugin defined at the command line. The main purpose of this program is to quickly invoke new detector plugins while developing. The arguments for this program are:
+\begin{minted}[frame=single,framesep=3pt,breaklines=true,tabsize=2,linenos,fontsize=\small]{bash}
+ geoPluginRun -opt [-opt]
+
+ -plugin <name> [REQUIRED] Plugin to be executed and applied.
+ -input <file> [OPTIONAL] Specify geometry input file.
+ -build_type <number/string> Specify the build type
+ [OPTIONAL] MUST come immediately after the -compact input.
+ Default for each file is: BUILD_DEFAULT [=1]
+ Allowed values: BUILD_SIMU [=1], BUILD_RECO [=2] or BUILD_DISPLAY [=3]
+ -destroy [OPTIONAL] Force destruction of the LCDD instance
+ before exiting the application
+ -volmgr [OPTIONAL] Load and populate phys.volume manager to
+ check the volume ids for duplicates etc.
+ -print <number/string> Specify output level. Default: INFO(=3)
+ [OPTIONAL] Allowed values: VERBOSE(=1), DEBUG(=2),
+ INFO(=3), WARNING(=4), ERROR(=5), FATAL(=6)
+ The lower the level, the more printout...
+\end{minted}
diff --git a/doc/usermanuals/DD4hep/chapters/overview.tex b/doc/usermanuals/DD4hep/chapters/overview.tex
new file mode 100644
index 000000000..e2cf490fb
--- /dev/null
+++ b/doc/usermanuals/DD4hep/chapters/overview.tex
@@ -0,0 +1,131 @@
+\chapter{Introduction and General Overview}
+\label{sec:introduction}
+
+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 DD4hep toolkit~\cite{dd4hep-repo} is shaped on the experience of detector description systems, which were implemented for the LHC experiments, in particular the LHCb experiment~\cite{Antunes-Nobrega:630827,Ponce:1496875}, as well as the lessons learnt from other implementations of geometry description tools developed for the Linear Collider community~\cite{Aihara:2009ad,Abe:2010aa}. 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. DD4hep aims to widely reuse used existing software components, in particular the ROOT geometry package~\cite{Brun2003676}, part of the ROOT project~\cite{Brun:1997pa}, 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 ROOT geometry package provides sophisticated 3D visualization functionality, which is ideal for building detector and event displays. The second component is the Geant4 simulation toolkit~\cite{Agostinelli:2002hh}, which is used to simulate the detector response from particle collisions in complex designs. In DD4hep the geometrical representation provided by ROOT is the main source of information. In addition DD4hep 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.
+
+In Section~\ref{sec:architectural-concepts} the scope and the high-level requirements of the DD4hep toolkit are elaborated (in the following also called ``the toolki''). This is basically the high level vision
+of the provided functionality to the experimental communities. In Section~\ref{sec:toolkit-design} the high-level or architectural design of the toolkit is presented, and in subsequent subsections design aspects of the various functional components and their interfaces will be introduced.
+
+\section{Project Scope and Requirements}
+\label{sec:architectural-concepts}
+
+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 LHC 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{description}
+\item[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[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 \textit{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[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[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{description}
+
+\begin{figure}[h]
+ \begin{center}
+ \includegraphics[width=0.8\linewidth] {DD4hep_big_picture}
+ \caption{The components of the DD4hep detector geometry toolkit.}
+ \label{fig:dd4hep-big-picture}
+ \end{center}
+ \vspace{-0.4cm}
+\end{figure}
+
+
+\section{Toolkit Design}
+\label{sec:toolkit-design}
+
+Figure~\ref{fig:dd4hep-big-picture} 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 \texttt{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.
+
+\subsection{The Compact Detector Description}
+\label{sec:problem_analysis}
+
+Inspired from the work of the linear collider detector simulation~\cite{Gaede:81331}, 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 \texttt{XML}. \texttt{XML} is an open format, the DD4hep 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 \textit{Detector Constructors} are needed.
+
+\subsection{Detector Constructors}
+\label{sec:detector-constructors}
+
+Detector Constructors are relatively small code fragments that get as input an \texttt{XML} 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~\ref{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 \texttt{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. DD4hep provides already a palette of basic pre-implemented geometrical detector concepts to design experiments. In view of usage of DD4hep 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.
+
+\begin{figure}[t]
+ \begin{center}
+ \includegraphics[width=0.8\linewidth]{DD4hep_classes}
+ \caption{Class diagram with the main classes and their relations
+ for the Generic Detector Description Model. The implementing
+ ROOT classes are shown in brackets.}
+ \label{fig:dd4hep-detector-model}
+ \end{center}
+\end{figure}
+
+
+\section{Generic Detector Description Model}
+\label{subsec:generic-model}
+
+This is the heart of the DD4hep 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 ROOT geometry package and extends them in case required functionality is not available. Figure~\ref{fig:dd4hep-detector-model} illustrates the main players and their relationships. Any detector is modeled as a tree of \textit{Detector Elements}, the entity central to this design, which is represented in the implementation by the \texttt{DetElement} class~\cite{Antunes-Nobrega:630827}. It offers all applications a natural entry point to any detector part of the experiment and represents a complete sub-detector (e.g. TPC), a part of a sub-detector (e.g. TPC-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 TPC reconstruction code, accessing the TPC detector element from this code will provide access the all TPC geometrical dimensions, the alignment and calibration constants and other slow varying conditions such as the gas pressure, end-plate temperatures etc. The \textit{Detector Element} acts as a data concentrator. Applications may access the full experiment geometry and all connected data through a singleton object called \texttt{Detector}, which provides management, bookkeeping and ownership to the model instances.
+
+The geometry is implemented using the ROOT geometry classes, which are used directly without unnecessary interfaces to isolate the end-user from the actual ROOT based implementation. There is one exception: The constructors are wrapped to facilitate a very compact and readable notation to end-users building custom \textit{Detector Constructors}.
+
+\subsection{Detector Element Tree versus the Geometry Hierarchy}
+\label{subsect:detelement-hierarchy}
+
+The geometry part of the detector description is delegated to the ROOT classes. \textit{Logical Volumes} are the basic objects used in building the geometrical hierarchy. A \textit{Logical Volume} is a shape with its dimensions and consist of a given material.
+They represent unpositioned objects which store all information about the placement of possibly embedded volumes. The same volume can be replicated several times in the geometry. The \textit{Logical Volume} also represents a system of reference with respect to its containing volumes. The reuse of instances of \textit{Logical Volumes} for different placements optimizes the memory consumption and detailed geometries for complex setups consisting of millions of volumes may be realized with reasonable amount of memory. The difficulty is to identify a given positioned volume in space and e.g. applying misalignment to one of these volumes. The relationship between the Detector Element and the placements is not defined by a single reference to the placement, but the full path from the top of the detector geometry model to resolve existing ambiguities due to the reuse of \textit{Logical Volumes}. Hence, individual volumes must be identified by their full path from mother to daughter starting from the top-level volume.
+
+\begin{figure}[t]
+ \begin{center}
+ \includegraphics[width=0.8\linewidth] {DD4hep_detelement_tree}
+ \caption{The object diagram of a hypothetical TPC detector showing in
+ parallel the \textit{Detector Element} and the \textit{Geometry} hierarchy and the
+ relationships between the objects.}
+ \label{fig:dd4hep-hierarchies}
+ \end{center}
+\end{figure}
+
+The tree structure of Detector Elements is a parallel structure to the geometrical hierarchy. This structure will probably not be as deep as the geometrical one since there would not need to associate detector information at very fine-grain
+level - it is unlikely that every little metallic screw needs associated detector information such as alignment, conditions, etc. Though this screw and many other replicas must be described in the geometry description since it may be important e.g. for its material contribution in the simulation application. Thus, the tree of Detector Elements is fully degenerate and each detector element object will be placed only once in the detector element tree as illustrated for a hypothetical TPC detector in Figure~\ref{fig:dd4hep-hierarchies}.
+
+\subsection{Extensions and Views}
+\label{subsect:extesions-and-views}
+
+As depicted in Figure~\ref{fig:dd4hep-big-picture} the reconstruction application will require special functionality extending the basics offered by the common detector element. This functionality may be implemented by a set of specialized classes that will extend the detector element. These extensions will be in charge of providing specific answers to the questions formulated by the reconstruction algorithms such as pattern recognition, tracking, vertexing, particle identification, etc. One example could be to transform a calorimeter cell identifier into a 3D space position in the global coordinate system. A generic detector description toolkit would be unable to answer this concrete question, however it provides a convenient environment for the developer to slot-in code fragments, which implement the additional functionality using parameters stored in the \texttt{XML} compact description.
+
+Depending on the functionality these specialized component must be able to either store additional data, expose additional behavior or both. Additional behavior may easily be added overloading the \texttt{DetElement} class using its internal data. The internal data is public and addressed by reference, hence any number of views extending the \texttt{DetElement} behavior may be constructed with very small overhead. Additional data may be added by any user at any time to any instance of the \texttt{DetElement} class using a simple aggregation mechanism shown in Figure~\ref{fig:dd4hep-extensions}. Data extensions must differ by their type. The freedom to attach virtually any data item allows for optimized attachments depending on the application type, such as special attachments for reconstruction, simulation, tracking, etc.
+
+\begin{figure}[t]
+ \begin{center}
+ \includegraphics[width=0.8\linewidth] {DD4hep-extensions}
+ \caption{Extensions may be attached to common Detector Elements which
+ extend the functionality of the common DetElement
+ class and support e.g. caching of precomputed values.}
+ \label{fig:dd4hep-extensions}
+ \end{center}
+\end{figure}
+
+This design allows to build views addressing the following use-cases:
+\begin{description}
+\item[Convenience Views] provide higher level abstractions and internally group complex calculations. Such views simplify the life of the end-users.
+\item[Optimization Views] allows end-users extend the data of the common detector detector element and store precomputed results, which would be expensive to obtain repeatedly.
+\item[Compatibility Views] help to ensure smooth periods of software redesign. During the life-time of the experiment often various software constructs are for functional reasons re-designed and re-engineered. Compatibility Views either adapt new data designs to existing application code or expose new behavior based on existing data.
+\end{description}
+
+\section{Simulation Support}
+\label{subsect:simulation-support}
+
+Detector-simulation depends strongly on the use of an underlying simulation toolkit, the most prominent candidate nowadays being Geant4~\cite{Agostinelli:2002hh}. DD4hep supports simulation activities with Geant4 providing an automatic translation mechanism between geometry representations. The simulation response in the active elements of the detector is not implemented by the toolkit, since it is strongly influenced by the technical choices and precise simulations depends on the very specific detection techniques. In Geant4 this response is computed in software constructs called \textit{Sensitive Detectors}.
+
+Ideally DD4hep aims to provide a generic simulation application. Similar to the palette of pre-implemented geometrical detector concepts to design experiments, it provides a palette of \textit{Sensitive Detectors} to simulate the detector response in form of a component library. Detector designers may base the simulation of a planned experiment on these predefined components for initial design and optimization studies. In a similar way easy access and configuration of other user actions of Geant4 is provided.
+
+\section{Detector Alignment Support}
+\label{subsect:alignment-support}
+
+The support for alignment operations is crucial to the usefulness of the toolkit. In the linear collider community this support is basically missing in all the currently used geometry description systems. The possibility to apply into the detector description alignment \textit{deltas} (differences with respect the ideal or measured position) and read them from an external source is mandatory to exploit the toolkit. A typical alignment application would consist of calculating a new set of \textit{deltas} from a given starting point, which could then be loaded and applied again in order to validate the alignment by recalculating some alignment residuals. The ROOT geometry package supports to apply an [mis]-alignment to \textit{touchable} objects in the geometry. \textit{Touchable} objects are identified by the path of positioned volumes starting with the top node (e.g. path=\texttt{$/TOP/A_1/B_4/C_3$}). Contrary to ordinary multiple placements of \textit{Logical Volumes}, \textit{touchable} objects are degenerate and only valid for one single volume~\cite{Brun2003676}. To simplify the usage for the end user, the identification of a positioned volume will be connected to the Detector Element, where only the relative path with respect to the Detector Element will have to be specified rather the full path from the top volume. The \textit{delta}-values will have to be read from various data sources. The initial implementation will be based on simple \texttt{XML} files, later a connection to other sources such as the detector conditions database is envisaged.
+
diff --git a/doc/usermanuals/DD4hep/config.tex b/doc/usermanuals/DD4hep/config.tex
new file mode 100755
index 000000000..28db9173b
--- /dev/null
+++ b/doc/usermanuals/DD4hep/config.tex
@@ -0,0 +1,88 @@
+% Temporary TODO commands
+% \newcommand{\comment}[1]{#1} % DRAFT
+\newcommand{\comment}[1]{} % FINAL
+
+\newcommand{\needcite}{\comment{[CITE?] }}
+\newcommand{\needref}{\comment{[REF?] }}
+\newcommand{\todo}[1]{\comment{[TODO: #1] }}
+
+\newcommand{\wip}{\textit{This section is not written yet.}}
+
+% Paragraph with new line
+\newcommand{\nlparagraph}[1]{\paragraph{#1}\mbox{}\\}
+
+% Typeset framework parameter and escape underscores:
+\DeclareUrlCommand\parameter{\bfseries\urlstyle{tt}}
+\newcommand{\command}[1]{\parameter{#1}}
+
+% Typeset directory and file names
+\DeclareUrlCommand\dir{\urlstyle{tt}}
+\newcommand{\file}[1]{\dir{#1}}
+
+% Define ini format used in the converted Markdown files
+\lstdefinelanguage{Ini}
+{
+ basicstyle=\ttfamily\small,
+ columns=fullflexible,
+ morecomment=[s][\color{blue}\bfseries]{[}{]},
+ morecomment=[l]{\#},
+ morecomment=[l]{;},
+ commentstyle=\color{gray}\ttfamily,
+ alsoletter={=},
+ morekeywords={=},
+ otherkeywords={},
+ keywordstyle={\color{green}\bfseries}
+}
+
+% Warning box
+\newsavebox{\warningbox}
+\newenvironment{warning}
+ {\newcommand\colboxcolor{pink}%
+ \begin{lrbox}{\warningbox}%
+ \begin{minipage}{\dimexpr\linewidth-2em\relax}}
+ {\end{minipage}\end{lrbox}%
+ \begin{center}
+ \setlength\fboxsep{0pt}
+ \colorbox{\colboxcolor}{\setlength\fboxsep{1em}\fbox{\usebox{\warningbox}}}
+ \end{center}}
+
+% Command to add all modules
+\newcommand{\includemodulesmd}{\def\temp{@DD4HEP_MODULE_FILES@}\ifx\temp\empty
+ \textit{Module documentation not added because Markdown to \LaTeX~conversion was not possible}
+\else
+ \foreach \n in @DD4HEP_MODULE_FILES@ {\input{\n}}
+\fi}
+
+% Command to add all examples
+\newcommand{\includeexamplesmd}{\def\temp{@DD4HEP_EXAMPLE_FILES@}\ifx\temp\empty
+ \textit{Example documentation not added because Markdown to \LaTeX~conversion was not possible}
+\else
+ \foreach \n in @DD4HEP_EXAMPLE_FILES@ {\input{\n}}
+\fi}
+
+% Command to add a single converted markdown file
+\newcommand{\inputmd}[1]{\input{md/#1}}
+
+% Set bibliography
+\addbibresource{references.bib}
+
+% Set DD4hep version
+\newcommand{\version}{\lstinline|@DD4HEP_VERSION@|}
+\newcommand{\project}{@CMAKE_PROJECT_NAME@}
+
+% Create addreferences command (overwritten for HTML in config)
+\newcommand{\addreferencesline}{\addcontentsline{toc}{chapter}{References}}
+
+% Command to add the license (overwritten for HTML in config)
+\newcommand{\addlicense}{
+\begin{table}[h]
+\centering
+\renewcommand{\arraystretch}{1.5}% Spread rows out...
+\begin{tabular}{>{\centering\arraybackslash}m{.10\textwidth}>{\raggedright\arraybackslash}m{.90\textwidth}}
+ \Large{\ccLogo \ccAttribution} & \footnotesize{This manual is licensed under the Creative Commons Attribution 4.0 International License.\newline To view a copy of this license, visit \url{http://creativecommons.org/licenses/by/4.0/}.} \\
+\end{tabular}
+\end{table}
+}
+
+% Use new lines in FAQ (fixed for HTML in config)
+\setlist[description]{style=nextline}
diff --git a/doc/usermanuals/DD4hep/figures/AIDA-2020.png b/doc/usermanuals/DD4hep/figures/AIDA-2020.png
new file mode 100644
index 0000000000000000000000000000000000000000..fe4df1612ec05e0fc48469519596497cf50d6d85
GIT binary patch
literal 22883
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
K^3}4I;r|1A?5_I&
literal 0
HcmV?d00001
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep-AIDA-logo.png b/doc/usermanuals/DD4hep/figures/DD4hep-AIDA-logo.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep-AIDA-logo.png
rename to doc/usermanuals/DD4hep/figures/DD4hep-AIDA-logo.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep-Lumical-detailed.png b/doc/usermanuals/DD4hep/figures/DD4hep-Lumical-detailed.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep-Lumical-detailed.png
rename to doc/usermanuals/DD4hep/figures/DD4hep-Lumical-detailed.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep-Lumical.png b/doc/usermanuals/DD4hep/figures/DD4hep-Lumical.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep-Lumical.png
rename to doc/usermanuals/DD4hep/figures/DD4hep-Lumical.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep-detelement-drawing.png b/doc/usermanuals/DD4hep/figures/DD4hep-detelement-drawing.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep-detelement-drawing.png
rename to doc/usermanuals/DD4hep/figures/DD4hep-detelement-drawing.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep-extensions.png b/doc/usermanuals/DD4hep/figures/DD4hep-extensions.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep-extensions.png
rename to doc/usermanuals/DD4hep/figures/DD4hep-extensions.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep-materials.png b/doc/usermanuals/DD4hep/figures/DD4hep-materials.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep-materials.png
rename to doc/usermanuals/DD4hep/figures/DD4hep-materials.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep-readout.png b/doc/usermanuals/DD4hep/figures/DD4hep-readout.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep-readout.png
rename to doc/usermanuals/DD4hep/figures/DD4hep-readout.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep-sensitive-detectors.png b/doc/usermanuals/DD4hep/figures/DD4hep-sensitive-detectors.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep-sensitive-detectors.png
rename to doc/usermanuals/DD4hep/figures/DD4hep-sensitive-detectors.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep-solids.png b/doc/usermanuals/DD4hep/figures/DD4hep-solids.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep-solids.png
rename to doc/usermanuals/DD4hep/figures/DD4hep-solids.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep-volmgr.png b/doc/usermanuals/DD4hep/figures/DD4hep-volmgr.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep-volmgr.png
rename to doc/usermanuals/DD4hep/figures/DD4hep-volmgr.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep-volume-code.png b/doc/usermanuals/DD4hep/figures/DD4hep-volume-code.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep-volume-code.png
rename to doc/usermanuals/DD4hep/figures/DD4hep-volume-code.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep-xml-code-snippet.png b/doc/usermanuals/DD4hep/figures/DD4hep-xml-code-snippet.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep-xml-code-snippet.png
rename to doc/usermanuals/DD4hep/figures/DD4hep-xml-code-snippet.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep-xml-data-snippet.png b/doc/usermanuals/DD4hep/figures/DD4hep-xml-data-snippet.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep-xml-data-snippet.png
rename to doc/usermanuals/DD4hep/figures/DD4hep-xml-data-snippet.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep-xml-data-structure.png b/doc/usermanuals/DD4hep/figures/DD4hep-xml-data-structure.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep-xml-data-structure.png
rename to doc/usermanuals/DD4hep/figures/DD4hep-xml-data-structure.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep_big_picture.png b/doc/usermanuals/DD4hep/figures/DD4hep_big_picture.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep_big_picture.png
rename to doc/usermanuals/DD4hep/figures/DD4hep_big_picture.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep_classes.png b/doc/usermanuals/DD4hep/figures/DD4hep_classes.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep_classes.png
rename to doc/usermanuals/DD4hep/figures/DD4hep_classes.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep_compact_xml.png b/doc/usermanuals/DD4hep/figures/DD4hep_compact_xml.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep_compact_xml.png
rename to doc/usermanuals/DD4hep/figures/DD4hep_compact_xml.png
diff --git a/doc/usermanuals/DD4hep/figs/DD4hep_detelement_tree.png b/doc/usermanuals/DD4hep/figures/DD4hep_detelement_tree.png
similarity index 100%
rename from doc/usermanuals/DD4hep/figs/DD4hep_detelement_tree.png
rename to doc/usermanuals/DD4hep/figures/DD4hep_detelement_tree.png
diff --git a/doc/usermanuals/DD4hep/figures/cc-by.png b/doc/usermanuals/DD4hep/figures/cc-by.png
new file mode 100755
index 0000000000000000000000000000000000000000..c8473a24786ab016d9c3e717a380910f7cbb0fff
GIT binary patch
literal 12588
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
XN9~BE9V~(W*#J?HQI)QMng;zJcO`H8
literal 0
HcmV?d00001
diff --git a/doc/usermanuals/DD4hep/figures/logo.eps b/doc/usermanuals/DD4hep/figures/logo.eps
new file mode 100644
index 000000000..3e3cc468f
--- /dev/null
+++ b/doc/usermanuals/DD4hep/figures/logo.eps
@@ -0,0 +1,142 @@
+%!PS-Adobe-3.0 EPSF-3.0
+%%Creator: cairo 1.14.0 (http://cairographics.org)
+%%CreationDate: Thu Apr 12 20:12:58 2018
+%%Pages: 1
+%%DocumentData: Clean7Bit
+%%LanguageLevel: 2
+%%BoundingBox: 0 -1 205 205
+%%EndComments
+%%BeginProlog
+save
+50 dict begin
+/q { gsave } bind def
+/Q { grestore } bind def
+/cm { 6 array astore concat } bind def
+/w { setlinewidth } bind def
+/J { setlinecap } bind def
+/j { setlinejoin } bind def
+/M { setmiterlimit } bind def
+/d { setdash } bind def
+/m { moveto } bind def
+/l { lineto } bind def
+/c { curveto } bind def
+/h { closepath } bind def
+/re { exch dup neg 3 1 roll 5 3 roll moveto 0 rlineto
+ 0 exch rlineto 0 rlineto closepath } bind def
+/S { stroke } bind def
+/f { fill } bind def
+/f* { eofill } bind def
+/n { newpath } bind def
+/W { clip } bind def
+/W* { eoclip } bind def
+/BT { } bind def
+/ET { } bind def
+/pdfmark where { pop globaldict /?pdfmark /exec load put }
+ { globaldict begin /?pdfmark /pop load def /pdfmark
+ /cleartomark load def end } ifelse
+/BDC { mark 3 1 roll /BDC pdfmark } bind def
+/EMC { mark /EMC pdfmark } bind def
+/cairo_store_point { /cairo_point_y exch def /cairo_point_x exch def } def
+/Tj { show currentpoint cairo_store_point } bind def
+/TJ {
+ {
+ dup
+ type /stringtype eq
+ { show } { -0.001 mul 0 cairo_font_matrix dtransform rmoveto } ifelse
+ } forall
+ currentpoint cairo_store_point
+} bind def
+/cairo_selectfont { cairo_font_matrix aload pop pop pop 0 0 6 array astore
+ cairo_font exch selectfont cairo_point_x cairo_point_y moveto } bind def
+/Tf { pop /cairo_font exch def /cairo_font_matrix where
+ { pop cairo_selectfont } if } bind def
+/Td { matrix translate cairo_font_matrix matrix concatmatrix dup
+ /cairo_font_matrix exch def dup 4 get exch 5 get cairo_store_point
+ /cairo_font where { pop cairo_selectfont } if } bind def
+/Tm { 2 copy 8 2 roll 6 array astore /cairo_font_matrix exch def
+ cairo_store_point /cairo_font where { pop cairo_selectfont } if } bind def
+/g { setgray } bind def
+/rg { setrgbcolor } bind def
+/d1 { setcachedevice } bind def
+%%EndProlog
+%%BeginSetup
+%%BeginResource: font f-0-0
+%!FontType1-1.1 f-0-0 1.0
+11 dict begin
+/FontName /f-0-0 def
+/PaintType 0 def
+/FontType 1 def
+/FontMatrix [0.001 0 0 0.001 0 0] readonly def
+/FontBBox {24 -194 743 742 } readonly def
+/Encoding 256 array
+0 1 255 {1 index exch /.notdef put} for
+dup 52 /four put
+dup 68 /D put
+dup 101 /e put
+dup 104 /h put
+dup 112 /p put
+readonly def
+currentdict end
+currentfile eexec
+f983ef0097ece636fb4a96c74d26ab84185f6dfa4a16a7a1c27bbe3f1156aea698df336d20b467
+b10e7f33846656653c5ac6962759d3056cbdb3190bac614b984bf5a132dc418192443014ba63de
+800d392b6fea026574bb2535fd7bb5338f35bf15a88ea328fdaa49670c7852e3d060f3c5d6b07f
+2ef6d0f22646c5d18e19a2ae3ee120390f6dd96f76dcf1e127de5e9299077a00c17c0d71e36e5b
+9d5ec58fceda57739a6a4214d4b79d6c48d2784b60c320323c7acddddf34db833cac0cf109f799
+69d114a330d372e5c978a66acc84e3fe5557f6240856a013ffaa0199444e5c5036f775eba4a5c5
+8cde66cf604b9aca2178431127b8a1ff7ed633a65c04600af5f573483112251caad907dcd8c61e
+23500065b1568be79a17d2379b63d656e8f7715cd87e85d67cb62f2fc770f40cd0e229cc3339a4
+1843a5f462de40ad82a61de3dfd785537834c460c20ae89b3ac2effacb2cc757acb0f2eee4d0c7
+8db786169a9cbfdbea48c5cd6253b4b70cebc8c1400908718ac0ed955b4bfa0184d85c5dc0da11
+cbde56d1e23fab50ea8ebcdd26b5aae30642606f218d7287171d50f89a850fc0ea5185f5d7b7c2
+8819476935e1ceb42ede3e3ce23eff213fb047f9d24dc1858e864df3a33c1d0d683a8bd2360b37
+7afc4bde118f4638c682bbfb40663ccd2f6103c99a0a89e02afbdb442f80260afb2d8810e04d55
+10dbd7f611d3fe2b6c1ac9759cc14345e80e00379e7030e49d68ff36b46ed9d29c6235cb4317d6
+0b7bd74d16d5d2d9547c6984b9ae5c7bb6b7841a2c2321808c6289c99a848aaaf1bdd0e8c6410f
+a9793595799f2ac1d93505c5a6213283c93763cd92d77798e45f2110f2505b4c20b045e8c0156d
+dfae1f34ec775a3b6bdba661d0ede5cbe23b18ca2b905fb0482904e8d3ade8563eed3bce1580e0
+4e88f4a2b28edf868db35afc72248520c2d0698c337b594b132776ba7bbfc32904e215f243cbfc
+95624673bb3edbc546901f25bb4f6ce1431b35b197fe1c4623a1d1e51484ff950f2a02abd6c485
+70664e78d3686a8787d3e9257f2615740769c844eff0b7528b5187b39a96d7fde78f3a998358fb
+259714eb3dadbb7a635de56fad77967a9440519e9a6ba1f468e02694bcf5288b8e5489a361f1de
+0717161f5c14b534828f35f760bcdc4b4dd400eea1c2a4c4689b696744e0af410c4cae44e91c79
+3d4eacb23582e1edaeb91baf1279e73b538f137c915a14bc93b80339cac82fa5cda5818a4a3327
+335f29999fd1d57b2bd1285773d248de00878a47b13de57ca958b0d921362fd361b90a3fc415e5
+9789d47ee27cdcf0cd9dc13dca1c13d80a0d327965906dab9bc495f1df6157f9b2223560a138e8
+8a7fc7df28c2c7a7603a6b64afe3fc5a4e931bbbcfa46940fe76b6dd74024e2114309b7dad4ebc
+aca1621d4c54874939cfe6d218ea4c0e03da612baf3a1941b513e0377a4b69dedb52f2d439b8b4
+66b3bdad0c46ac828af4888b3b74d1bc406c2b2d0a60feaa3c442d1517051e8c23e12fc381a4d2
+1dd11715096745abf5d1bff2de5d9a759e295d08916cf712459978a9a22c2799e9ebc8d577f06a
+aba5bc3e616fb498dbd170333013a4008635b23f7ccdcd8a087934d2ff449d6f2b90c31aad0ef5
+f5afb312e0fd496fbf5177999eba15a448e6bba45f5460fa0e0000000000000000000000000000000000000000000000000000000000000000
+0000000000000000000000000000000000000000000000000000000000000000
+0000000000000000000000000000000000000000000000000000000000000000
+0000000000000000000000000000000000000000000000000000000000000000
+0000000000000000000000000000000000000000000000000000000000000000
+0000000000000000000000000000000000000000000000000000000000000000
+0000000000000000000000000000000000000000000000000000000000000000
+0000000000000000000000000000000000000000000000000000000000000000
+cleartomark
+%%EndResource
+%%EndSetup
+%%Page: 1 1
+%%BeginPageSetup
+%%PageBoundingBox: 0 -1 205 205
+%%EndPageSetup
+q 0 -1 205 206 rectclip q
+0.0117647 0.329412 0.631373 rg
+204.801 102.402 m 204.801 45.847 158.953 -0.001 102.398 -0.001 c 45.848
+ -0.001 0 45.847 0 102.402 c 0 158.952 45.848 204.8 102.398 204.8 c 158.953
+ 204.8 204.801 158.952 204.801 102.402 c h
+204.801 102.402 m f
+1 g
+BT
+49.207898 0 0 51.662998 0.6539 88.308303 Tm
+/f-0-0 1 Tf
+[(DD)-3(4hep)]TJ
+ET
+Q Q
+showpage
+%%Trailer
+end restore
+%%EOF
diff --git a/doc/usermanuals/DD4hep/html/css/custom.css b/doc/usermanuals/DD4hep/html/css/custom.css
index a5d583ef5..7b152bac9 100755
--- a/doc/usermanuals/DD4hep/html/css/custom.css
+++ b/doc/usermanuals/DD4hep/html/css/custom.css
@@ -18,6 +18,14 @@ h2 a, h3 a, h4 a, h5 a {
.ec-lmr-6 {
margin-right: 8px;
}
+.ec-lmr-5:before {
+ content: '';
+ clear: right;
+ display: block;
+}
+.ec-lmr-5 {
+ margin-right: 8px;
+}
.fancyvrb {
font-size: 80%;
}
diff --git a/doc/usermanuals/DD4hep/html/dd4hep.cfg b/doc/usermanuals/DD4hep/html/dd4hep.cfg
index c1ad61c9c..d677e4403 100755
--- a/doc/usermanuals/DD4hep/html/dd4hep.cfg
+++ b/doc/usermanuals/DD4hep/html/dd4hep.cfg
@@ -29,11 +29,11 @@
% Fix to use ol tags for enumerate
\ConfigureList{enumerate}
{\ifvmode\IgnorePar\fi\EndP\HCode{<ol class="enumerate">\Hnewline}\ShowPar%
-\bgroup
-\def\EndDefItem{}}
+ \bgroup
+ \def\EndDefItem{}}
{\EndDefItem\egroup%
-\ifvmode\IgnorePar\fi\EndP\HCode{</ol>\Hnewline}\ShowPar%
-\par}
+ \ifvmode\IgnorePar\fi\EndP\HCode{</ol>\Hnewline}\ShowPar%
+ \par}
{\EndDefItem\HCode{<li class="enumerate-item" >}\DeleteMark\def\EndDefItem{\HCode{</li>\Hnewline}}}
{}
@@ -45,12 +45,13 @@
\makeatletter
\renewcommand\tableofcontents{\@ifstar{}{}}
\makeatother
-%\renewcommand{\addreferencesline}{}
+\renewcommand{\addreferencesline}{}
% Delete license because it is included in html
-% \renewcommand{\addlicense}{}
+\renewcommand{\addlicense}{}
% Use standard for description because nextline does not work
-%\setlist[description]{style=standard}
+\setlist[description]{style=standard}
\EndPreamble
+
diff --git a/doc/usermanuals/DD4hep/references.bib b/doc/usermanuals/DD4hep/references.bib
new file mode 100755
index 000000000..bc1b7c4a3
--- /dev/null
+++ b/doc/usermanuals/DD4hep/references.bib
@@ -0,0 +1,135 @@
+@book{Antunes-Nobrega:630827,
+ author = "Antunes-Nobrega, R and others",
+ title = "{LHCb reoptimized detector design and performance:
+ Technical Design Report}",
+ publisher = "CERN",
+ collaboration = "LHCb Collaboration",
+ address = "Geneva",
+ series = "Technical Design Report LHCb",
+ year = "2003",
+ url = "https://cds.cern.ch/record/630827",
+}
+
+@techreport{Ponce:1496875,
+ author = "Ponce, S\'ebastien",
+ title = "{Detector Description Framework in LHCb}",
+ institution = "CERN",
+ address = "Geneva",
+ number = "LHCb-PROC-2003-004. CERN-LHCb-PROC-2003-004",
+ month = "Mar",
+ year = "2003",
+ reportNumber = "LHCb-PROC-2003-004",
+ url = "https://cds.cern.ch/record/1496875",
+}
+
+@article{Aihara:2009ad,
+ author = "Aihara, H. and Burrows, P. and Oreglia, M. and Berger, E.
+ L. and Guarino, V. and Repond, J. and Weerts, H. and Xia,
+ L. and Zhang, J. and Zhang, Q. and others ",
+ title = "{SiD Letter of Intent}",
+ year = "2009",
+ eprint = "0911.0006",
+ archivePrefix = "arXiv",
+ primaryClass = "physics.ins-det",
+ reportNumber = "SLAC-R-989, FERMILAB-LOI-2009-01, FERMILAB-PUB-09-681-E",
+ SLACcitation = "%%CITATION = ARXIV:0911.0006;%%"
+}
+
+@article{Abe:2010aa,
+ author = "Abe, Toshinori and others",
+ title = "{The International Large Detector: Letter of Intent}",
+ collaboration = "Linear Collider ILD Concept Group -",
+ doi = "10.2172/975166",
+ year = "2010",
+ eprint = "1006.3396",
+ archivePrefix = "arXiv",
+ primaryClass = "hep-ex",
+ reportNumber = "FERMILAB-LOI-2010-03, FERMILAB-PUB-09-682-E, DESY-09-87,
+ KEK-REPORT-2009-6",
+ SLACcitation = "%%CITATION = ARXIV:1006.3396;%%"
+}
+
+@article{Brun2003676,
+ author = "Brun, R. and Gheata, A. and Gheata, M.",
+ title = "{The ROOT geometry package}",
+ booktitle = "{Advanced computing and analysis techniques in physics
+ research. Proceedings, 8th International Workshop, ACAT
+ 2002, Moscow, Russia, June 24-28, 2002}",
+ journal = "Nucl. Instrum. Meth.",
+ volume = "A502",
+ year = "2003",
+ pages = "676-680",
+ doi = "10.1016/S0168-9002(03)00541-2",
+ SLACcitation = "%%CITATION = NUIMA,A502,676;%%"
+}
+
+@article{Agostinelli:2002hh,
+ author = "Agostinelli, S. and others",
+ title = "{GEANT4: A Simulation toolkit}",
+ collaboration = "GEANT4",
+ journal = "Nucl. Instrum. Meth.",
+ volume = "A506",
+ year = "2003",
+ pages = "250-303",
+ doi = "10.1016/S0168-9002(03)01368-8",
+ reportNumber = "SLAC-PUB-9350, FERMILAB-PUB-03-339",
+ SLACcitation = "%%CITATION = NUIMA,A506,250;%%"
+}
+
+@article{Brun:1997pa,
+ author = "Brun, R. and Rademakers, F.",
+ title = "{ROOT: An object oriented data analysis framework}",
+ booktitle = "{New computing techniques in physics research V.
+ Proceedings, 5th International Workshop, AIHENP '96,
+ Lausanne, Switzerland, September 2-6, 1996}",
+ journal = "Nucl. Instrum. Meth.",
+ volume = "A389",
+ year = "1997",
+ pages = "81-86",
+ doi = "10.1016/S0168-9002(97)00048-X",
+ SLACcitation = "%%CITATION = NUIMA,A389,81;%%"
+}
+
+@INPROCEEDINGS{Gaede:81331,
+ author = {Gaede, F. and Graf, N. and Johnson, T.},
+ title = {{LCGO} - geometry description for {ILC} detectors},
+ reportid = {PHPPUBDB-6036},
+ year = {2007},
+ month = {Sep},
+ date = {2007-09-02},
+ organization = {International Conference on Computing
+ in High Energy and Nuclear Physics,
+ Victoria (Canada), 2 Sep 2007 - 7 Sep
+ 2007},
+ cin = {IT},
+ cid = {$I:(DE-H253)IT_-2012_-20120307$},
+ pnm = {Facility (machine) ILC $R\&D$ (POF1-510)},
+ pid = {G:(DE-H253)POF1-ILC-20130405},
+ experiment = {EXP:(DE-H253)ILC(machine)-20150101},
+ typ = {PUB:(DE-HGF)6},
+ url = {http://bib-pubdb1.desy.de/record/81331},
+}
+
+@online{dd4hep-repo,
+ title = {The DD4hep Project Repository},
+ author = {},
+ url = {https://github.com/AIDASoft/DD4hep},
+ year = {2016},
+ month = Oct,
+ day = {16}
+}
+
+@article{Chytracek:2006be,
+ author = "Chytracek, R. and McCormick, J. and Pokorski, W. and
+ Santin, G.",
+ title = "{Geometry description markup language for physics
+ simulation and analysis applications.}",
+ journal = "IEEE Trans. Nucl. Sci.",
+ volume = "53",
+ year = "2006",
+ pages = "2892",
+ doi = "10.1109/TNS.2006.881062",
+ reportNumber = "SLAC-PUB-12301",
+ SLACcitation = "%%CITATION = IETNA,53,2892;%%"
+}
+
diff --git a/doc/usermanuals/DD4hep/sections/Abstract.tex b/doc/usermanuals/DD4hep/sections/Abstract.tex
deleted file mode 100644
index d737ff65c..000000000
--- a/doc/usermanuals/DD4hep/sections/Abstract.tex
+++ /dev/null
@@ -1,17 +0,0 @@
-%=============================================================================
-\noindent
-The detector description is an essential component that is used to analyze data
-resulting from particle collisions in high energy physics experiments.
-We will present a generic detector description toolkit
-and describe the guiding requirements and the architectural design for
-such a toolkit, as well as the main implementation choices.
-The design is strongly driven by easy of use;
-developers of detector descriptions and applications using
-them should provide minimal information and minimal specific
-code to achieve the desired result.
-The toolkit will be built reusing already existing components
-from the ROOT geometry package and provides missing functional
-elements and interfaces to offer a complete and coherent
-detector description solution. A natural integration to
-Geant4, the detector simulation program used in high energy physics,
-is provided.
diff --git a/doc/usermanuals/DD4hep/sections/Overview.tex b/doc/usermanuals/DD4hep/sections/Overview.tex
deleted file mode 100644
index 8212f1b4d..000000000
--- a/doc/usermanuals/DD4hep/sections/Overview.tex
+++ /dev/null
@@ -1,418 +0,0 @@
-%=============================================================================
-\section{Introduction and General Overview}
-%=============================================================================
-\label{sec:introduction}
-\noindent
-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.
-
-\noindent
-The design of the DD4hep toolkit\cite{bib:DD4hep}
-is shaped on the experience of detector description
-systems, which were implemented for the LHC experiments, in particular
-the LHCb experiment~\cite{bib:LHCb,bib:LHCb-geometry},
-as well as the lessons learnt from other
-implementations of geometry description tools developed for
-the Linear Collider community~\cite{bib:ILD,bib:SiD}.
-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.
-DD4hep aims to widely reuse used existing software components, in particular
-the ROOT geometry package~\cite{bib:ROOT-tgeo}, part of the
-ROOT project\cite{bib:ROOT}, 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 ROOT geometry package provides
-sophisticated 3D visualization functionality, which is ideal for building
-detector and event displays. The second component is
-the Geant4 simulation toolkit~\cite{bib:geant4}, which is used to
-simulate the detector response from particle collisions in complex designs.
-In DD4hep the geometrical
-representation provided by ROOT is the main source of information.
-In addition DD4hep 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.
-
-\noindent
-In Section~\ref{sec:architectural-concepts} the scope and the high-level
-requirements of the DD4hep toolkit are elaborated (in the following
-also called "the toolkit"). This is basically the high level vision
-of the provided functionality to the experimental communities.
-In Section~\ref{sec:toolkit-design} the high-level or architectural design
-of the toolkit is presented, and in subsequent subsections design
-aspects of the various functional components and their interfaces will be
-introduced.
-
-%=============================================================================
-\subsection{Project Scope and Requirements}
-%=============================================================================
-\label{sec:architectural-concepts}
-\noindent
-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 LHC 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.
-
-\noindent
-The following main requirements influenced the design of the toolkit:
-\begin{itemize}
-\item {\bf{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 {\bf{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 {\bf{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 {\bf{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{itemize}
-
-%=============================================================================
-\begin{figure}[h]
- \begin{center}
- \includegraphics[height=80mm] {DD4hep_big_picture}
- \caption{The components of the DD4hep detector geometry toolkit.}
- \label{fig:dd4hep-big-picture}
- \end{center}
- \vspace{-0.4cm}
-\end{figure}
-
-%=============================================================================
-\subsection{Toolkit Design}
-\label{sec:toolkit-design}
-%=============================================================================
-\noindent
-Figure~\ref{fig:dd4hep-big-picture} 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.
-
-%=============================================================================
-\subsubsection{The Compact Detector Description}
-\label{sec:problem_analysis}
-%=============================================================================
-\noindent
-Inspired from the work of the linear collider detector
-simulation~\cite{bib:LCDD,bib:lcsim}, 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.
-
-\noindent
-In the compact description the detector is parametrized in minimalistic terms
-with user provided parameters in XML.
-XML is an open format, the DD4hep 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.
-%Figure~\ref{fig:fig-vxd-xml} shows a partial example of how to describe an ideal
-%silicon-based vertex detector with regular disposition of ladders
-%in 2 layers in total.
-Such a compact detector descriptions cannot be interpreted in a
-general manner, therefore so called $Detector$ $Constructors$ are needed.
-
-%=============================================================================
-%\begin{figure}[h]
-% \begin{center}
-% \includegraphics[width=16cm] {DD4hep_compact_xml}
-% \caption{An example sniplett of the compact detector description. The
-% example shows the description of a 2 layered silicon vertex
-% detector.}
-% \label{fig:fig-vxd-xml}
-% \end{center}
-% \vspace{-0.6cm}
-%\end{figure}
-%=============================================================================
-
-%=============================================================================
-\subsubsection{Detector Constructors}
-\label{sec:detector-constructors}
-%=============================================================================
-\noindent
-Detector Constructors are relatively small code fragments that get
-as input an XML 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~\ref{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.
-
-\noindent
-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.
-DD4hep provides already a palette of basic pre-implemented geometrical detector
-concepts to design experiments. In view of usage of DD4hep 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.
-%=============================================================================
-\begin{figure}[t]
- \begin{center}
- \includegraphics[height=110mm] {DD4hep_classes}
- \caption{Class diagram with the main classes and their relations
- for the Generic Detector Description Model. The implementing
- ROOT classes are shown in brackets.}
- \label{fig:dd4hep-detector-model}
- \end{center}
-\end{figure}
-%=============================================================================
-\subsection{Generic Detector Description Model}
-\label{subsec:generic-model}
-%=============================================================================
-
-\noindent
-This is the heart of the DD4hep 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 ROOT geometry package and extends them in case required functionality
-is not available. Figure~\ref{fig:dd4hep-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 $DetElement$ class~\cite{bib:LHCb-geometry}. It offers all
-applications a natural entry point to any detector part of the experiment
-and represents a complete sub-detector (e.g. TPC), a part of a
-sub-detector (e.g. TPC-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 TPC reconstruction
-code, accessing the TPC detector element from this code will provide access
-the all TPC 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 $LCDD$, which provides
-management, bookkeeping and ownership to the model instances.
-
-\noindent
-The geometry is implemented using the ROOT geometry classes, which are used
-directly without unnecessary interfaces to isolate the end-user from the
-actual ROOT 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$.
-
-%=============================================================================
-\subsubsection{Detector Element Tree versus the Geometry Hierarchy}
-\label{subsect:detelement-hierarchy}
-%=============================================================================
-\noindent
-The geometry part of the detector description is delegated to the ROOT classes.
-$Logical$ $Volumes$ are the basic objects used in building the geometrical hierarchy.
-A $Logical$ $Volume$ is a shape with its dimensions and consist of a given material.
-They represent unpositioned objects which store all information about
-the placement of possibly embedded volumes. The same
-volume can be replicated several times in the geometry. The $Logical$ $Volume$ also
-represents a system of reference with respect to its containing volumes.
-The reuse of instances of $Logical$ $Volumes$ for different placements
-optimizes the memory consumption and detailed geometries for complex setups
-consisting of millions of volumes may be realized with reasonable amount of memory.
-The difficulty is to identify a given positioned volume
-in space and e.g. applying misalignment to one of these volumes.
-The relationship between the Detector Element and the placements
-is not defined by a single reference to the placement, but the full path
-from the top of the detector geometry model to resolve existing
-ambiguities due to the reuse of $Logical$ $Volumes$.
-Hence, individual volumes must be identified by their full path from mother
-to daughter starting from the top-level volume.
-
-%=============================================================================
-\begin{figure}[t]
- \begin{center}
- \includegraphics[height=85mm] {DD4hep_detelement_tree}
- \caption{The object diagram of a hypothetical TPC detector showing in
- parallel the $Detector$ $Element$ and the $Geometry$ hierarchy and the
- relationships between the objects.}
- \label{fig:dd4hep-hierarchies}
- \end{center}
-\end{figure}
-%=============================================================================
-
-\noindent
-The tree structure of
-Detector Elements is a parallel structure to the geometrical hierarchy.
-This structure will probably not be as deep as the geometrical one since
-there would not need to associate detector information at very fine-grain
-level - it is unlikely that every little metallic screw
-needs associated detector information such as alignment, conditions, etc.
-Though this screw and many other replicas must be described in the geometry
-description since it may be important e.g. for its material contribution
-in the simulation application. Thus, the tree of Detector Elements is
-fully degenerate and each detector element object will be placed only
-once in the detector element tree as illustrated for a hypothetical
-TPC detector in Figure~\ref{fig:dd4hep-hierarchies}.
-
-%=============================================================================
-\subsubsection{Extensions and Views}
-\label{subsect:extesions-and-views}
-%=============================================================================
-
-\noindent
-As depicted in Figure~\ref{fig:dd4hep-big-picture} the reconstruction
-application will require special functionality extending the basics
-offered by the common detector element. This functionality may be
-implemented by a set of specialized classes that will extend the
-detector element. These extensions will be in charge
-of providing specific answers to the questions formulated by the
-reconstruction algorithms such as pattern recognition, tracking, vertexing,
-particle identification, etc. One example could be to transform a calorimeter
-cell identifier into a 3D space position in the global coordinate system.
-A generic detector description toolkit would be unable
-to answer this concrete question, however it provides a convenient
-environment for the developer to slot-in code fragments, which implement the
-additional functionality using parameters stored
-in the XML compact description.
-
-\noindent
-Depending on the functionality these specialized component must be able to
-either store additional data, expose additional behavior or both. Additional
-behavior may easily be added overloading the $DetElement$ class using its
-internal data. The internal data is public and addressed by reference, hence
-any number of views extending the $DetElement$ behavior may be constructed
-with very small overhead. Additional data may be added by any user at any time
-to any instance of the $DetElement$ class using a simple aggregation
-mechanism shown in Figure~\ref{fig:dd4hep-extensions}. Data extensions must
-differ by their type. The freedom to attach virtually
-any data item allows for optimized attachments depending on the
-application type, such as special attachments for reconstruction,
-simulation, tracking, etc.
-%=============================================================================
-\begin{figure}[t]
- \begin{center}
- \includegraphics[width=115mm] {DD4hep-extensions}
- \caption{Extensions may be attached to common Detector Elements which
- extend the functionality of the common DetElement
- class and support e.g. caching of precomputed values.}
- \label{fig:dd4hep-extensions}
- \end{center}
-\end{figure}
-%=============================================================================
-This design allows to build views addressing the following use-cases:
-\begin{itemize}
-\item{{\bf{Convenience Views}}} provide higher level abstractions
- and internally group complex calculations. Such views simplify
- the life of the end-users.
-\item{{\bf{Optimization Views}}} allows end-users extend the data of
- the common detector detector element and store precomputed
- results, which would be expensive to obtain repeatedly.
-\item{{\bf{Compatibility Views}}} help to ensure smooth periods of
- software redesign. During the life-time of the experiment
- often various software constructs are for functional reasons
- re-designed and re-engineered.
- Compatibility Views either adapt new data designs to existing application
- code or expose new behavior based on existing data.
-\end{itemize}
-
-%=============================================================================
-\subsection{Simulation Support}
-\label{subsect:simulation-support}
-%=============================================================================
-\noindent
-Detector-simulation depends strongly on the use of an underlying simulation toolkit,
-the most prominent candidate nowadays being Geant4~\cite{bib:geant4}.
-DD4hep supports simulation activities with Geant4 providing
-an automatic translation mechanism between geometry representations.
-The simulation response in the active elements of the detector
-is not implemented by the toolkit, since it is strongly influenced by the technical
-choices and precise simulations depends on the very specific detection techniques.
-In Geant4 this response is computed in software constructs called $Sensitive$
-$Detectors$.
-
-\noindent
-Ideally DD4hep aims to provide a generic simulation application.
-Similar to the palette of pre-implemented geometrical detector
-concepts to design experiments, it provides a palette of $Sensitive$
-$Detectors$ to simulate the detector response in form of a component library.
-Detector designers may base the simulation of a planned experiment
-on these predefined components for initial design and optimization
-studies. In a similar way easy access
-and configuration of other user actions of Geant4 is provided.
-
-%=============================================================================
-\subsection{Detector Alignment Support}
-\label{subsect:alignment-support}
-%=============================================================================
-\noindent
-The support for alignment operations is crucial to the usefulness of the
-toolkit. In the linear collider community this support is basically missing
-in all the currently used geometry description systems.
-The possibility to apply into the detector description alignment $deltas$
-(differences with respect the ideal or measured position) and read them
-from an external source is mandatory to exploit the toolkit. A typical
-alignment application would consist of calculating a new set of $deltas$
-from a given starting point, which could then be loaded and applied again
-in order to validate the alignment by recalculating some alignment residuals.
-The ROOT geometry package supports to apply an [mis]-alignment to
-$touchable$ objects in the geometry. $Touchable$ objects are identified
-by the path of positioned volumes starting with the top node
-(e.g. path=$/TOP/A_1/B_4/C_3$). Contrary to ordinary multiple placements
-of $Logical$ $Volumes$, $touchable$ objects are degenerate and only
-valid for one single volume~\cite{bib:ROOT-tgeo}.
-To simplify the usage for the end user,
-the identification of a positioned volume will be connected
-to the Detector Element, where only the relative path with respect
-to the Detector Element will have to be specified
-rather the full path from the top volume.
-The $delta$-values will have to be read from various data sources.
-The initial implementation will be based on simple XML files, later
-a connection to other sources such as the detector conditions database
-is envisaged.
-
diff --git a/doc/usermanuals/DD4hep/setup/AIDA2020-logo.png b/doc/usermanuals/DD4hep/setup/AIDA2020-logo.png
deleted file mode 100644
index 4e8bfcc859665acd61421b3fda2d7a6a40e586dd..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 121803
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
H2>ky5A2*Yg
diff --git a/doc/usermanuals/DD4hep/setup/AIDA2020-setup.tex b/doc/usermanuals/DD4hep/setup/AIDA2020-setup.tex
deleted file mode 100644
index e9174da4d..000000000
--- a/doc/usermanuals/DD4hep/setup/AIDA2020-setup.tex
+++ /dev/null
@@ -1,98 +0,0 @@
-%
-%
-\usepackage{graphicx}
-\usepackage{hyperref}
-\usepackage{verbatim}
-\usepackage{fix-cm}
-\usepackage{lineno}
-\usepackage{fancyhdr}
-%\usepackage{amsmath}
-%
-\oddsidemargin 0.1 in
-\evensidemargin 0.1 in
-%
-%
-\newlength{\backindent}\setlength{\backindent}{2cm}
-\textwidth 5.375 in % Width of text line.
-\advance\textheight by1.4cm
-\advance\voffset by-1.4cm
-\advance\textwidth by\backindent
-%
-%
-% === Fancy headers setup ===============================
-%
-\setlength{\headheight}{15.2pt}
-\pagestyle{fancyplain} {
-\fancyhead[L]{\includegraphics[height=10mm]{./setup/AIDA2020-logo}\vspace{-0.3cm}}
-\fancyhead[C]{}
-\fancyhead[R]{\sffamily{\underline{\hspace{6cm}Advanced European Infrastructures for Detectors at Accelerators}}}
-\fancyfoot[L]{}
-\fancyfoot[C]{\sffamily{User Manual}}
-\fancyfoot[R]{\sffamily{\thepage}}
-}
-%
-%
-\newcommand{\tw}[1]{${\tt{#1}}$}
-\newcommand{\tts}[1]{{\tt\small{#1}}}
-\newcommand{\bold}[1]{{\bf{#1}}}
-%
-%
-\newcommand{\docline}[2]{\vspace{0.1cm}{\bf{#1}} & \parbox{14.5cm}{#2}\\}
-%
-% === Specialization of the lineno package
-%
-\renewcommand{\linenumberfont} {\normalfont\small\sffamily}
-\renewcommand{\makeLineNumber} {\makeLineNumberLeft}
-\renewcommand{\linenumbersep} {2pt}
-%
-% === Set font to code section with line numbers
-%
-\newenvironment{code}{\par\vspace{0.01cm}\small\linenumbers\verbatim\setcounter{linenumber}{1}}{\endverbatim\nolinenumbers\vspace{-0.02cm}}%
-%
-% === Set font to code section with line numbers
-%
-\newenvironment{unnumberedcode}{\par\vspace{-0.1cm}\small\verbatim\setcounter{linenumber}{1}}%
-{\endverbatim\vspace{-0.2cm}}
-%
-%
-% === Compactify the item list =========================
-%
-\newcommand{\itemcompact}{\setlength{\itemsep}{1pt}\setlength{\parskip}{0pt}\setlength{\parsep}{0pt}}
-%
-%
-% === Title page command ===============================
-%
-%
-\newcommand{\basictitle}[2]{
-%
-\pagestyle{empty}
-%
-\includegraphics[height=25mm] {./setup/AIDA2020-logo}
-
-\vspace{0.02cm}
-
-{\sffamily{\underline{\hspace{6cm}Advanced European Infrastructures for Detectors at Accelerators}}}
-
-\vspace{2cm}
-
-\begin{center}
-{\fontsize{72}{32}\selectfont{\bfseries{#1}}}
-
-\vspace{3cm}
-{\Huge\bf{#2}}
-\vspace{3cm}
-\begin{figure}[b]
- \begin{center}
- \includegraphics[height=15mm] {./setup/Horizon2020-grant-logo}
- \end{center}
-\end{figure}
-\end{center}
-}
-\newcommand{\AIDAtitle}[3]{
-\begin{titlepage}
-\basictitle{#1}{#2}
-\begin{center}
-{#3}
-\end{center}
-\end{titlepage}
-}
diff --git a/doc/usermanuals/DD4hep/setup/DD4hep-setup.tex b/doc/usermanuals/DD4hep/setup/DD4hep-setup.tex
deleted file mode 100644
index ce0c21c7f..000000000
--- a/doc/usermanuals/DD4hep/setup/DD4hep-setup.tex
+++ /dev/null
@@ -1,36 +0,0 @@
-%
-% === Command to insert http links to the DD4hep geomtery package
-%
-\newcommand{\detdesc}[2]
-{
- \href{http://www.cern.ch/frankm/DD4hep/#1}{#2}
-}
-%
-% === Command to insert http links to the ROOT geomtery package
-%
-\newcommand{\tgeo}[2]
-{
- \href{http://root.cern.ch/root/html/#1.html}{#2}
-}
-\newcommand{\tgeoO}[3]
-{
- \href{http://root.cern.ch/root/html/#1:#2}{#3}
-}
-\newcommand{\DDE}{{$\tt{DDEve}$\space}}
-\newcommand{\DDhep}{{$\tt{DD4hep}$\space}}
-\newcommand{\DDH}{{$\tt{DD4hep}$\space}}
-\newcommand{\DDG}{{\tt{DDG4}\space}}
-\newcommand{\DDA}{{\tt{DDAlign}\space}}
-\newcommand{\DDC}{{\tt{DDCond}\space}}
-\newcommand{\DDR}{{\tt{DDRec}\space}}
-%
-% === Custom title page ================================
-%
-\newcommand{\mytitle}[3]{
-\begin{titlepage}
-\basictitle{#1}{#2}
-\begin{center}
-{#3}
-\end{center}
-\end{titlepage}
-}
diff --git a/doc/usermanuals/DD4hep/setup/Horizon2020-grant-logo.png b/doc/usermanuals/DD4hep/setup/Horizon2020-grant-logo.png
deleted file mode 100644
index 6e0a8d729be9db6a2174060cd019050c01cc597f..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 10152
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
B6x#p*
diff --git a/doc/usermanuals/DDAlign/html/css/custom.css b/doc/usermanuals/DDAlign/html/css/custom.css
index a5d583ef5..7b152bac9 100755
--- a/doc/usermanuals/DDAlign/html/css/custom.css
+++ b/doc/usermanuals/DDAlign/html/css/custom.css
@@ -18,6 +18,14 @@ h2 a, h3 a, h4 a, h5 a {
.ec-lmr-6 {
margin-right: 8px;
}
+.ec-lmr-5:before {
+ content: '';
+ clear: right;
+ display: block;
+}
+.ec-lmr-5 {
+ margin-right: 8px;
+}
.fancyvrb {
font-size: 80%;
}
diff --git a/doc/usermanuals/DDCond/html/css/custom.css b/doc/usermanuals/DDCond/html/css/custom.css
index a5d583ef5..7b152bac9 100755
--- a/doc/usermanuals/DDCond/html/css/custom.css
+++ b/doc/usermanuals/DDCond/html/css/custom.css
@@ -18,6 +18,14 @@ h2 a, h3 a, h4 a, h5 a {
.ec-lmr-6 {
margin-right: 8px;
}
+.ec-lmr-5:before {
+ content: '';
+ clear: right;
+ display: block;
+}
+.ec-lmr-5 {
+ margin-right: 8px;
+}
.fancyvrb {
font-size: 80%;
}
diff --git a/doc/usermanuals/DDEve/html/css/custom.css b/doc/usermanuals/DDEve/html/css/custom.css
index a5d583ef5..7b152bac9 100755
--- a/doc/usermanuals/DDEve/html/css/custom.css
+++ b/doc/usermanuals/DDEve/html/css/custom.css
@@ -18,6 +18,14 @@ h2 a, h3 a, h4 a, h5 a {
.ec-lmr-6 {
margin-right: 8px;
}
+.ec-lmr-5:before {
+ content: '';
+ clear: right;
+ display: block;
+}
+.ec-lmr-5 {
+ margin-right: 8px;
+}
.fancyvrb {
font-size: 80%;
}
diff --git a/doc/usermanuals/DDG4/html/css/custom.css b/doc/usermanuals/DDG4/html/css/custom.css
index a5d583ef5..7b152bac9 100755
--- a/doc/usermanuals/DDG4/html/css/custom.css
+++ b/doc/usermanuals/DDG4/html/css/custom.css
@@ -18,6 +18,14 @@ h2 a, h3 a, h4 a, h5 a {
.ec-lmr-6 {
margin-right: 8px;
}
+.ec-lmr-5:before {
+ content: '';
+ clear: right;
+ display: block;
+}
+.ec-lmr-5 {
+ margin-right: 8px;
+}
.fancyvrb {
font-size: 80%;
}
diff --git a/doc/usermanuals/DDRec/html/css/custom.css b/doc/usermanuals/DDRec/html/css/custom.css
index a5d583ef5..7b152bac9 100755
--- a/doc/usermanuals/DDRec/html/css/custom.css
+++ b/doc/usermanuals/DDRec/html/css/custom.css
@@ -18,6 +18,14 @@ h2 a, h3 a, h4 a, h5 a {
.ec-lmr-6 {
margin-right: 8px;
}
+.ec-lmr-5:before {
+ content: '';
+ clear: right;
+ display: block;
+}
+.ec-lmr-5 {
+ margin-right: 8px;
+}
.fancyvrb {
font-size: 80%;
}
--
GitLab