From dd12a59a88c85ee13a38f131d52369d58bce30e4 Mon Sep 17 00:00:00 2001
From: Markus Frank <markus.frank@cern.ch>
Date: Wed, 7 Oct 2015 09:56:28 +0000
Subject: [PATCH] These files should have never been there....(temporary
backups)
---
doc/LaTex/DD4hepManual.0.tex | 1831 ---------------------------------
doc/LaTex/DDAlignManual.0.tex | 743 -------------
doc/LaTex/DDG4Manual.0.tex | 1419 -------------------------
3 files changed, 3993 deletions(-)
delete mode 100644 doc/LaTex/DD4hepManual.0.tex
delete mode 100644 doc/LaTex/DDAlignManual.0.tex
delete mode 100644 doc/LaTex/DDG4Manual.0.tex
diff --git a/doc/LaTex/DD4hepManual.0.tex b/doc/LaTex/DD4hepManual.0.tex
deleted file mode 100644
index 8b2f98a0e..000000000
--- a/doc/LaTex/DD4hepManual.0.tex
+++ /dev/null
@@ -1,1831 +0,0 @@
-%=============================================================================
-\documentclass[10pt,a4paper]{article}
-%
-\input{DD4hep-setup.tex}
-%
-\pagestyle{fancyplain}{\fancyfoot[C]{\sffamily{DD4hep User Manual}}}
-%
-%
-\begin{document}
-%
-\mytitle{
-DD4hep
-}{
-A Detector Description Toolkit\\
-for High Energy Physics\\
-\vspace{0.3cm}
-Experiments
-}
-%
-%
-%== Abstract ===============================================================
-\pagestyle{plain}
-\pagenumbering{Roman}
-\setcounter{page}{1}
-
-\begin{abstract}
-\normalsize
-\input{DD4hep-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{DD4hep-Overview.tex}
-%
-\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 algorithms.
-
-\noindent
-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 \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.
-\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 useful 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> struct Handle {
- typedef T Implementation;
- typedef Handle<Implementation> handle_t;
- T* m_element;
- 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 alignment entry by it's name from the detector description
- virtual AlignmentEntryalignment(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 Alignment: named alignment 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.png}
- \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}
-
-
-\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.png}
- \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 alignment 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 alignment information:
-\begin{code}
- /// Access to the alignment information
- Alignment alignment() 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.png}
- \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.png}
- \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.
-
-\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;
-}
-
-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}
-
-%=============================================================================
-\subsection{Tools}
-\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.png}
- \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{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.png} &
- \includegraphics[width=80mm] {DD4hep-Lumical-detailed.png} \\
- \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>
-
-
-geoDisplay -opt [-opt]
- -compact <file> Specify the compact geometry file
- [REQUIRED] At least one compact geo file is required!
- -load_only [OPTIONAL] Dry-run to only load geometry without
- starting the dispay.
-\end{code}
-
-%=============================================================================
-\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
-
- -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}
-
-%=============================================================================
-\newpage
-\begin{thebibliography}{9}
-\input{DD4hep-bibliography.tex}
-\bibitem{bib:DDSegmentations} C.Grefe et al.,
- "The DDSegmentation package",
- Non existing documentation to be written.
-\end{thebibliography}
-%=============================================================================
-\end{document}
diff --git a/doc/LaTex/DDAlignManual.0.tex b/doc/LaTex/DDAlignManual.0.tex
deleted file mode 100644
index fd9cf5635..000000000
--- a/doc/LaTex/DDAlignManual.0.tex
+++ /dev/null
@@ -1,743 +0,0 @@
-%=============================================================================
-\documentclass[10pt,a4paper]{article}
-%
-\input{DD4hep-setup.tex}
-%
-\pagestyle{fancyplain}{\fancyfoot[C]{\sffamily{DDAlign User Manual}}}
-%
-\begin{document}
-%
-\mytitle{
-DDAlign
-}{
-Alignment Support for the \\
-\vspace{0.5cm}
-DD4hep Geometry Description \\
-\vspace{0.5cm}
-Toolkit
-\vspace{2cm}
-}{DDAlign User Manual}
-%
-%
-%== Abstract ===============================================================
-\pagestyle{plain}
-\pagenumbering{Roman}
-\setcounter{page}{1}
-\begin{abstract}
-%=============================================================================
-
-\noindent
-\normalsize
-Experimental setups in High Energy Physics are highly complex assemblies
-consisting of various detector devices typically called {\it{subdetectors}}.
-Contrary to the ideal world, where all these components are of perfect shape
-and at exact positions, existing devices have imperfections both in their
-shape and their relative and absolute positions.\\
-To still measure the detector response from particle collisions with the highest
-possible precision, these imperfections are taken into account when converting
-measured signals to space-points in the measurement devices. This procedure
-is called {\it{detector alignment}}. \DDhep does not want to solve the exact
-problem of the detector alignment itself, but rather support firstly algorithms
-determining the imperfections and secondly support the application of the
-measured imperfection to the ideal geometry for further event data processing.\\
-We will present the tools to support the detector alignment procedures using
-the \DDhep detector description toolkit.
-The \DDA toolkit implements a modular and flexible approach to introduce and
-access the imperfections.\\
-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.
-
-\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 & 1/4/2014 & Markus Frank CERN/LHCb \\
- & & \\ \hline
-\end{tabular}
-}}}
-\end{center}
-
-\clearpage
-%
-%
-%== TOC ====================================================================
-\tableofcontents
-\clearpage
-%
-%
-%=============================================================================
-% Manual
-%=============================================================================
-\pagenumbering{arabic}
-\setcounter{page}{1}
-
-%=============================================================================
-\section{Introduction}
-\label{sec:ddalign-user-manual-introduction}
-%=============================================================================
-\noindent
-This manual should introduce to the \DDA framework.
-One goal of \DDA is to easily model geometrical imperfections applied to
-the ideal geometry of detection devices as they are typically used in
-high energy physics experiments.
-
-\noindent
-\DDA formalizes both the access and the application of geometrical imperfection
-to the ideal geometry. In this manual we will shortly describe the model used
-to describe an experiments detector description and then in more detail
-document the support for alignment with its programming interfaces.
-
-%=============================================================================
-\begin{figure}[h]
- \begin{center}
- \includegraphics[height=90mm] {DD4hep_classes.png}
- \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}
-\vspace{-0.5cm}
-%=============================================================================
-\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.
-\DDA allows client to access and manage imperfections or smallish changes
-to this geometry. The mechanism to achieve this is described in the following.
-
-%=============================================================================
-\begin{figure}[t]
- \begin{center}
- \includegraphics[height=75mm] {DD4hep_detelement_tree.png}
- \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}
- \vspace{-0.5cm}
-\end{figure}
-%=============================================================================
-\subsection{Detector Element Tree and 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.
-
-\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
-Time Projection Chamber (TPC) detector in
-Figure~\ref{fig:dd4hep-hierarchies} with an ideal geometry,
-where no positioning corrections are applied to neither child. It is essential to
-realize that the geometry tree in an ideal geometry is degenerate contrary
-to the tree of detector elements.
-
-%=============================================================================
-\begin{figure}[h]
- \begin{center}
- \includegraphics[width=160mm] {DDAlign_detelement_aligned_tree.png}
- \caption{The object diagram of a hypothetical TPC detector showing in
- parallel the $Detector$ $Element$ and the $Geometry$ hierarchy and examples
- of mispositioned detector parts: (a) mispositioned entire subdetector
- (translation), (b) mispositioned end-cap (tilt) and (c) mispositioned
- individual sectors within one endcap.}
- \label{fig:dd4hep-aligned-hierarchies}
- \end{center}
-\end{figure}
-%=============================================================================
-\subsection{Geometrical Imperfection of Detector Components}
-\label{subsect:ddalign-intro-aligments}
-%=============================================================================
-\noindent
-Imperfections never apply in the same way to {\it{all}} placements of the
-same volume in this hierarchy. Hence, to (re-)align a volume in the hierarchy
-means to lift a full branch of placements from the top volume down to
-the element to be (re-)aligned out of this shared hierarchy and apply
-a correction matrix to the last node. This procedure is illustrated in
-Figure~\ref{fig:dd4hep-aligned-hierarchies}. Re-alignment of volumes may occur
-at any level. In the above example of a TPC this results in the following effects:
-
-\noindent
-\begin{itemize}\itemcompact
-\item A realignment of the entire subdetector, i.e. the TPC as a whole,
- would affect consequently move all contained children with respect to the
- top level coordinate system. An example is shown in
- Figure~\ref{fig:dd4hep-aligned-hierarchies} (a). A movement of the subdetector
- would affect all transformation between local coordinates of any part of the
- subdetector to the top level coordinate system. Such effects would be visible
- at all stages of the data processing e.g. when translating signals from
- particles into global coordinates.
-\item A realignment of parts of a subdetector affects only the partial subdetector
- itself and child volumes at lower levels. As in the example, where the entire
- subdetector is moved, here only the sectors on one side of the TPC would be affected
- as shown in Figure~\ref{fig:dd4hep-aligned-hierarchies} (b).
-\item In Figure~\ref{fig:dd4hep-aligned-hierarchies} (c) within one end-cap of the TPC
- individual sectors may not be positioned at the ideal location
- (Figure~\ref{fig:dd4hep-aligned-hierarchies} (c) exaggerates:
- ''flying sectors'' are a rather rare case in reality).
- Finally also the sectors itself could be fragmented and be assemblies of other
- shapes, which are not ideally placed and may need correction.
-\end{itemize}
-The origin of the volume misplacements may be many-fold:
-\begin{itemize}\itemcompact
-\item Elements may be weak and assembled parts move due to weak support structures.
- This is a common problem e.g. for tracking detectors, where heavy and solid
- structures dramatically influence the measurement result.
- Misplaced sectors could e.g. be the consequence of a deforming end-cap frame due
- to the weight of the sectors.
-\item Environmental conditions such as the temperature may influence the
- position or the shape of a volume.
-\item Some of the measurement equipment may be moved from a parking position into
- a data taking position such as the two halves of the LHCb vertex detector.
- Whereas the position of the sensors on each half are known to a very high
- precision, the position of the absolute position of the two halves with respect
- to the full experiment may change after each movement.
-\end{itemize}
-All effects resulting from such causes obviously need to be corrected in order to
-fully explore the capabilities of the detection devices and to minimize
-measurement errors. In general any deviation from the ideal position of a volume
-can be described by two elementary transformations:
-\begin{itemize}\itemcompact
-\item a translation
-\item a rotation around a pivot point.
-\end{itemize}
-giving a full transformation matrix of the form:
-\begin{equation}
-T = L * P * R * P^{-1}
-\end{equation}
-where
-\begin{itemize}\itemcompact
-\item $T$ is the full transformation in 3D space containing the change to the
-exiting placement transformation. The existing placement is the placement
-transformation of the volume with respect to the mother volume.
-\item $L$ is a translation specifying the position change with respect to the
- mother volume.
-\item $P * R * P^{-1}$ describes a rotation around a pivot point specified
- int he mother volume's coordinate system.
-\item $P$ is the translation vector from the mother volumes origin to the
- pivot point.
-\end{itemize}
-Most of the changes do not require the full set of parameters. Very often
-the changes only require the application of only a translation, only a rotation
-or both with a pivot point in the origin. These simplifications are supported
-in the user interface described in
-Section~\ref{sec:ddalign-user-manual-ddalign-interface}.
-
-%=============================================================================
-\begin{figure}[t]
- \begin{center}
- \includegraphics[width=160mm] {DDAlign-iterative-misalignment.png}
- \caption{The iterative application of geometry imperfections as described
- in Section~\ref{subsect:ddalign-intro-iterative-alignments}.
- For each interval of validity ($[T_0,T_1]$, $[T_2,T_3]$, $[T_4,T_5]$, ...)
- a seperate set of alignment constants is applied to the ideal geometry.
- The two steps to reset the misaligned geometry back to the ideal geometry and
- to re-apply a new set of alignment constants may be executed as
- often as necessary when processing data from particle collisions.}
- \label{fig:ddalign-aligned-iterative}
- \end{center}
-\end{figure}
-
-\newpage
-%=============================================================================
-\subsection{Iterative Application of Alignments}
-\label{subsect:ddalign-intro-iterative-alignments}
-%=============================================================================
-\noindent
-In the general case geometrical imperfections are not static and may very
-well change with time. For this reason it is highly important to support
-not only one single realignment step.
-Hence, the following scenario is an important use case:
-\begin{enumerate}\itemcompact
-\item Create the ideal detector using an ideal geometry.
-\item Apply the misalignment for a given time interval corresponding to the
- time a set of particle collisions were collected in the experiment.
-\item Process the set of collected particle collisions.
-\item Reset the misaligned detector to the ideal.
-\item Choose new event data input corresponding to another time interval
- and restart at item 2.
-\end{enumerate}
-Graphically this use case is illustrated in
-Figure~\ref{fig:ddalign-aligned-iterative}. In
-Section~\ref{sec:ddalign-user-manual-ddalign-interface} the implementation
-to realize this use case is described.
-
-\newpage
-%=============================================================================
-\section{The DDAlign User Interface}
-\label{sec:ddalign-user-manual-ddalign-interface}
-%=============================================================================
-
-\noindent
-\DDA implements a machinery to apply and access geometrical imperfections
-describing the difference between an ideal detector given by an ideal geometry
-and the geometry of the actually built assembly in real life.
-To ease its usage for the clients and to shield clients from the
-internals when actually dealing with realigned geometries, a set of
-helper classes was designed. The access to the imperfections
-in read-only mode was separated from the import or export thereof.
-
-\noindent
-As a basic concept within \DDhep any {\it{sizable}} detector component
-can be realigned. {\it{Sizable}} as a rule of thumb is anything, which
-is manufactured as an individual piece and which you may ''hold in your hands''.
-Such objects are also described by a $detector$ $element$ of type {\tt DetElement}.
-An example is e.g. a single silicon wafer of a tracking device or the entire
-tracking detector itself.
-The access to the geometry imperfections is possible from each {\tt DetElement}
-instance as described in Section~\ref{sec:ddalign-user-manual-misalignment-access}
-
-\noindent
-Please be aware that the extensive use of misalignments is highly memory
-consuming.
-
-\noindent
-%=============================================================================
-\subsection{Access to Geometrical Imperfections from the Detector Element}
-\label{sec:ddalign-user-manual-misalignment-access}
-%=============================================================================
-
-\noindent
-The $DetElement$ class as shown in Figure~\ref{fig:dd4hep-detector-model}
-gives the user access to the alignment structure of type $Alignment$ as
-illustrated in the following example:
-\begin{code}
- DetElement wafer = ... // Valid handle to a detector element
- Alignment wafer_alignment = wafer.alignment();
- if ( wafer_alignment.isValid() ) {
- // This wafer's placement differs from the ideal geometry and
- // imperfections are present.
-
- // Access the misalignment transformation with respect to the parent volume:
- Transform3D tr = wafer_alignment.toMotherDelta();
- }
-\end{code}
-The access to details of an invalid alignment object results in a runtime
-exception. The full interface of the $Alignment$ structure to access detector imperfections
-is as follows:
-\begin{code}
- /// Number of nodes in this branch (=depth of the placement hierarchy from the top level volume)
- int numNodes() const;
- /// Access the placement of this node
- PlacedVolume placement() const;
- /// Access the placement of the mother of this node
- PlacedVolume motherPlacement(int level_up = 1) const;
- /// Access the placement of a node in the chain of placements for this branch
- PlacedVolume nodePlacement(int level=-1) const;
- /// Access the currently applied alignment/placement matrix with respect to the world
- Transform3D toGlobal(int level=-1) const;
- /// Transform a point from local coordinates of a given level to global coordinates
- Position toGlobal(const Position& localPoint, int level=-1) const;
- /// Transform a point from global coordinates to local coordinates of a given level
- Position globalToLocal(const Position& globalPoint, int level=-1) const;
- /// Access the currently applied alignment/placement matrix with respect to mother volume
- Transform3D toMother(int level=-1) const;
- /// Access the currently applied alignment/placement matrix (mother to daughter)
- Transform3D nominal() const;
- /// Access the currently applied correction matrix (delta) (mother to daughter)
- Transform3D delta() const;
-\end{code}
-\begin{itemize}\itemcompact
-\item The calls in line 3-8 allow access to the relative position of the $nth.$ element
- in the alignment stack with respect to its next level parent.
- Element $numNodes()-1$ denotes the lowest level and element $0$ is the world
- volume. The default argument $(-1)$ addresses the lowest placement in the hierarchy.
-\item Calls in line 9-12 allow to access/execute transformations from a given level
- in the placement hierarchy to coordinates in the top level volume (world).
-\item The call in line 14 allows to transform a global coordinate to the local coordinate
- system in a given level of the hierarchy.
-\item The call $toMother$ in line 16 returns the local transformation of the node at
- a given level to the mother's coordinate system.
-\item The calls in line 17-20 give access to the nominal placement matrix of the realigned
- node with respect to the parent volume and the changes thereof.
-\end{itemize}
-Besides these convenience calls the full interface to the class {\tt TGeoPhysicalNode},
-which implements in the ROOT geometry package alignment changes, is accessible
-from the $Alignment$ handle using the overloaded $operator->()$.
-Further documentation is available directly from the \tgeo{TGeoPhysicalNode}{ROOT site}.
-
-\noindent
-%=============================================================================
-\subsection{Manipulation of Geometrical Imperfections}
-\label{sec:ddalign-user-manual-misalignment-manip}
-%=============================================================================
-There are multiple possibilities to apply geometry imperfections:
-\begin{itemize}\itemcompact
-\item The pedestrian way ''by hand'' using C++ as described in
- Subsection~\ref{sec:ddalign-user-manual-misalignment-manip-cxx}
-\item Loading a whole set of misalignment constants from XML, the ''poor man's'' database.
- This mechanism is described in
- Subsection~\ref{sec:ddalign-user-manual-misalignment-manip-xml}
-\item Loading a whole set of misalignment constants from a database.
- This possibility depends heavily on the database and its schema used.
- A typical use case is to load misalignment constants depending on the
- experiment conditions at the time the event data were collected.
- \DDA does not provide an implementation.
- This possibility here is only mentioned for completeness and will be subject
- to further developments to support conditions in \DDhep.
-\end{itemize}
-
-\noindent
-%=============================================================================
-\subsubsection{Manipulation of Geometrical Imperfections for Pedestrians using C++}
-\label{sec:ddalign-user-manual-misalignment-manip-cxx}
-%=============================================================================
-\noindent
-In this section we describe how to apply geometry imperfections to an existing
-detector geometry in memory using {\tt C++}. To apply misalignment to an existing
-geometry two classes are collaborating, the {\tt AlignmentCache} attached to
-the geometry container {\tt LCDD} and a temporary structure the {\tt AlignmentStack}.
-The {\tt AlignmentCache} allows to access all existing alignment entries
-based on their subdetector.
-The {\tt AlignmentStack} may exist in exactly one instance and is used to
-insert a consistent set of alignment entries. Consistency is important because
-changes may occur at any hierarchical level and internal transformation caches
-of the ROOT geometry package must be revalidated for all branches containing
-a higher level node.
-{\bf For this reason it is highly advisable to apply realignment constants
-for a complete subdetector.}
-Note that this restriction is not imposed, in principle a consistent set
-of misalignments may be applied at any level of the geometry hierarchy.
-
-\noindent
-Though the application of alignment is much simpler using XML files, the following
-description should give an insight on the mechanisms used behind the scene and
-to understand the concept.
-
-\noindent
-Any manipulations are transaction based must be embraced by the following two calls
-opening and closing a transaction:
-\begin{code}
-// Required include file(s)
-#include "DDAlign/AlignmentCache.h"
-
- LCDD& lcdd = ....;
- AlignmentCache* cache = lcdd.extension<Geometry::AlignmentCache>();
-
- // First things first: open the transaction.
- cache->openTransaction();
-
- // Prepare the entry containing the alignment data
- AlignmentStack::StackEntry* entry = .....;
- //.... and add the element to the AlignmentStack .....
- AlignmentStack::insert(entry);
-
- // Finally close the transaction. At this moment the changes are applied.
- cache->closeTransaction();
-\end{code}
-In the following we describe the mechanism to create and prepare the
-{\tt StackEntry} instances of the above code snippet. The calls to open and close
-the alignment transaction do not have to be in the same code fragment where also
-the alignment entries are prepared. However, all changes are only applied when
-the transaction is closed. The alignment entries do not necessarily have to
-be prepared in the sequence of the hierarchy they should be applied, internally
-the entries are re-ordered and follow the geometry hierarchy top to bottom
-i.e. mother volumes are always re-aligned {\it\bf before} the daughters
-are re-aligned.
-
-\noindent
-The {\tt StackEntry} instances carry all information to apply the re-alignment
-of a given volume. This information contains:
-\begin{itemize}\itemcompact
-\item The transformation matrix describing the positional change of the volume
- with respect to its mother volume.
-\item The placement path of the volume to be realigned.
-\item A flag to reset the volume to its ideal position {\it\bf before} the
- change is applied.
-\item A flag to also reset all daughter volumes to their
- ideal position {\it\bf before} the change is applied.
-\item A flag to check for overlaps after the application of the change and
-\item the actual precision used to perform this check.
-\end{itemize}
-
-\noindent
-The {\tt ROOT::Math} library provides several ways to construct the required
-3D transformation as described in Section~\ref{subsect:ddalign-intro-aligments}:
-\begin{code}
-// Required include file(s)
-#include "DD4hep/Objects.h"
-
- Position trans(x_translation, y_translation, z_translation);
- RotationZYX rot (z_angle, y_angle, x_angle);
- Translation3D pivot(x_pivot, y_pivot, z_pivot);
-
- Transform3D trafo;
- /// Construct a 3D transformation for a translation and a rotation around a pivot point:
- trafo = Transform3D(Translation3D(trans)*pivot*rot*(pivot.Inverse()));
-
- /// Construct a 3D transformation for a translation and a rotation around the origin
- trafo = Transform3D(rot,pos);
-
- /// Construct a 3D transformation for a rotation around a pivot point
- trafo = Transform3D(piv*rot*(piv.Inverse()));
-
- /// Construct a 3D transformation for a rotation around the origin
- trafo = Transform3D(rot);
-
- /// Construct a 3D transformation for simple translation
- trafo = Transform3D(pos);
-
-\end{code}
-
-\noindent
-The following code snippet shows how to extract this information from the
-{\tt DetElement} and prepare such a {\tt StackEntry} instance:
-\begin{code}
-// Required include file(s)
-#include "DDAlign/AlignmentStack.h"
-
- // Prepare the entry containing the alignment data
- typedef AlignmentStack::StackEntry Entry;
- /// Detector element to be realigned
- DetElement element = ...;
- /// The transformation describing the relative change with respect to the mother volume
- Transform3D trafo = ...;
- /// Instantiate a new alignment entry
- Entry* entry = new Entry(element);
- entry->setTransformation(trafo) // Apply the transformation matrix
- .applyReset(/* argument default: true */) // Set the reset flag
- .applyResetChildren(/* argument default: true */) // Set the daughter reset flag
- .checkOverlaps(/* argument default: true */) // Set flag to check overlaps
- .overlapPrecision(0.001/mm); // With this precision in mm
-
- /// Now add the entry to the alignment stack:
- AlignmentStack::insert(entry);
-\end{code}
-The constructor will automatically determine the volumes placement path
-from the {\tt DetElement}. Then the transformation is applied and the flags
-to reset the volume, its children and to trigger the overlap checks with
-the given precision.
-
-\noindent
-When passing the entry to the {\tt AlignmentStack} the {\tt AlignmentStack}
-takes ownership and subsequently the entry is deleted after being applied to
-the geometry. For further shortcuts in the calling sequence please consult the
-{\tt AlignmentStack} header file.
-
-
-\noindent
-%=============================================================================
-\subsubsection{Loading Geometrical Imperfections from XML}
-\label{sec:ddalign-user-manual-misalignment-manip-xml}
-%=============================================================================
-\noindent
-In this section we describe how to load geometry imperfections and to apply them
-to an existing geometry. Loading the XML file is done automatically using the
-standard XML loader plugin provided by \DDhep. This plugin is interfaced to
-the {\tt LCDD} instance and invoked from code as follows:
-\begin{code}
- LCDD& lcdd = ....;
- lcdd.fromXML("file:AlepTPC_alignment.xml");
-\end{code}
-To fully exploit the capabilities it is important to understand the interpreted
-structure of the XML file being processed. At the top level of the primary
-input file (i.e. the file given to the XML processor) the following structure
-is expected:
-\begin{code}
-<alignment>
- <!-- Open the alignment transaction -->
- <open_transaction/>
- <subdetectors> <!-- Container with the list of subdetectors to be processed. -->
- <detelement path="TPC" reset="true" reset_children="true">
- <!-- Move the entire TPC in the world volume -->
- <position="" x="30" y="30" z="80"/>
-
- <!-- Now add daughter detector elements -->
-
- <!-- Twist a bit the entire endcap by rotating it around the x and the y axis -->
- <detelement path="/world/TPC/TPC_SideA" check_overlaps="false">
- <position x="0" y="0" z="0"/>
- <rotation x="-0.2" y="-0.2" z="0"/>
- <!-- Apply corrections of type Translation*Rotation to a single sector
- <detelement path="TPC_SideA_sector02" check_overlaps="true">
- <position x="0" y="0" z="0"/>
- <rotation x="0.5" y="0.1" z="0.2"/>
- </detelement>
- </detelement>
-
- <!-- And the full shooting match of transformations for this sector -->
- <detelement path="TPC_SideA/TPC_SideA_sector03" check_overlaps="true">
- <position x="0" y="0" z="290.0*mm"/>
- <rotation x="0" y="pi/2" z="0"/>
- <pivot x="0" y="0" z="100"/>
- </detelement>
-
- ....
-
- <!-- Include alignment files to be processed in the context of the "TPC" DetElement
- <include ref="file-name"/>
-
- </detElement>
- </subdetectors>
-
- <!-- Include alignment files to be processed at the top level context -->
- <include ref="file-name"/>
-
- <!-- Close the alignment transaction -->
- <close_transaction/>
-</alignment>
-\end{code}
-The specification of any transformation element is optional:
-\begin{itemize}\itemcompact
-\item The absence of a translation implies the origin (0,0,0)
-\item The absence of a pivot point implies the origin (0,0,0)
-\item The absence of a rotation implies the identity rotation.
- Any supplied pivot point in this case is ignored.
-\end{itemize}
-
-\noindent
-The structure of the alignment file explained quickly:
-
-\noindent
-\begin{tabular} {l||p{0cm}}
-\docline{Line}{}
-\docline{1}{The {\tt root} tag for the primary alignment file is {\tt <alignment/>}.
- The primary tag name is mandatory and actually is used to invoke the correct interpreter.}
-\docline{2,41}{Trigger the alignment transaction by specifying the transaction tags in
- the main XML file.}
-\docline{4}{Defintion of the set of {\tt subdetectors} to be processed. A valid alias for this
- directove is {\tt detelements}.}
-\docline{5}{The first subdetector: {\tt TPC}. The subdetector tag is {\tt detelement}
- Each {\tt detelement} may recursively contain other {\tt detelement} tags.
- as they were defined in the {\tt DetElement} hierarchy.
- Internal {\tt detelement} elements are processed in the context of the outer
- element i.e. pathes may be specified relative to the parent or as absolute pathes
- with respect to the world (starting with a '/').}
-\docline{7}{Global movement of the TPC}
-\docline{12-20}{Realignment entry for the TPC endcap A named {\tt TPC\_SideA}}
-\docline{16-19}{Realignment entry for sector named {\tt TPC\_SideA\_sector02} of the TPC endcap A.
- Here the sector is specified directly as a daughter of the endcap. The name
- of the {\tt DetElement} is relative to the parent.}
-\docline{23-27}{Realignment entry for sector named {\tt TPC\_SideA\_sector03} of the TPC endcap A
- containing a full transformation: $Translation * Pivot * Rotation * Pivot^{-1}$}
-\docline{32}{Optionally {\tt detelement} elements may include other alignment files specifying
- lower volume levels. These files are interpreted in the context of the calling
- detector element. }
-\docline{38}{Optionally the subdetector alignment constants may be fragmented
- into several files, which can be loaded using the {\tt include}
- directive. Each file could for example describe one single detector.}
-\end{tabular}
-
-\newpage
-\noindent
-Included files may directly start with the {\tt root} tags {\tt subdetectors},
-{\tt detelements} or {\tt detelement} and may recursively include other
-files. Except for the top level these files are processed in the calling context.
-
-\vspace{1cm}
-\noindent
-And finally, the result:
-%=============================================================================
-\begin{figure}[h]
- \begin{center}
- \includegraphics[width=160mm] {DDAlign-misaligned-TPC.png}
- \caption{The ALEPH TPC after the import of the alignment file.}
- \label{fig:dd4hep-aligned-hierarchies}
- \end{center}
-\end{figure}
-
-
-\noindent
-%=============================================================================
-\subsubsection{Export Geometrical Imperfections to XML}
-\label{sec:ddalign-user-misalignment-expotr-xml}
-%=============================================================================
-\noindent
-In this section we describe how to export geometry imperfections to an XML file.
-A small helper class {\tt AlignmentWriter} achieves this task as shown in
-the snippet:
-\begin{code}
- LCDD& lcdd = ....;
- DetElement top = ....;
- if ( top.isValid() ) {
- AlignmentWriter wr(lcdd);
- return wr.write(top,output,enable\_transactions);
- }
-\end{code}
-This code will dump all alignment constants contained in the {\tt DetElement}
-hierarchy of {\tt top} to the output file {\tt output}. The optional argument
-{\tt enable\_transactions} (default: true) will add the tags
-{\tt <open\_transaction/>} and {\tt <close\_transaction/>} to the output
-file. The output file conforms to the specifications described in
-Section~\ref{sec:ddalign-user-manual-misalignment-manip-xml} and may later
-be imported by another process.
-
-\newpage
-%=============================================================================
-\begin{thebibliography}{9}
-\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.
-\end{thebibliography}
-%=============================================================================
-\end{document}
diff --git a/doc/LaTex/DDG4Manual.0.tex b/doc/LaTex/DDG4Manual.0.tex
deleted file mode 100644
index 4590bbaa5..000000000
--- a/doc/LaTex/DDG4Manual.0.tex
+++ /dev/null
@@ -1,1419 +0,0 @@
-%=============================================================================
-\documentclass[10pt,a4paper]{article}
-%
-\input{DD4hep-setup.tex}
-%
-\pagestyle{fancyplain}{\fancyfoot[C]{\sffamily{DDG4 User Manual}}}
-%
-\begin{document}
-%
-\mytitle{
-DDG4
-}{
-A Simulation Toolkit for \\
-\vspace{0.5cm}
-High Energy Physics Experiments\\
-\vspace{0.5cm}
-using Geant4 and the \\
-\vspace{0.5cm}
-DD4hep Geometry Description
-}{DDG4 User Manual}
-%
-%
-%== Abstract ===============================================================
-\pagestyle{plain}
-\pagenumbering{Roman}
-\setcounter{page}{1}
-\begin{abstract}
-%=============================================================================
-
-\noindent
-\normalsize
-Simulating the detector response is an essential tool in high energy physics
-to analyze the sensitivity of an experiment to the underlying physics.
-Such simulation tools require a detailed though convenient detector description as
-it is provided by the \DDhep toolkit.
-We will present the generic simulation toolkit \DDG using the \DDhep detector
-description toolkit.
-The toolkit implements a modular and flexible approach to simulation activities
-using Geant4. User defined simulation applications using \DDG
-can easily be configured, extended using specialzed action routines.
-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.
-
-\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
-%
-%
-%=============================================================================
-% Manual
-%=============================================================================
-\pagenumbering{arabic}
-\setcounter{page}{1}
-
-%=============================================================================
-\section{Introduction}
-\label{sec:ddg4-user-manual-introduction}
-%=============================================================================
-\noindent
-This manual should introduce to the DDG4 framework.
-One goal of \DDG is to easily configure the simulation applications
-capable of simulating the physics response of detector configurations
-as they are used for example in high energy physics experiments.
-In such simulation programs the user normally has to define the
-experimental setup in terms of its geometry and in terms of its
-active elements which sample the detector response.
-
-\noindent
-The goal of \DDG is to generalize the configuration of a simulation
-application to a degree, which does not force users to write code
-to test a detector design. At the same time it should of course
-be feasible to supply specialized user written modules which are supposed
-to seamlessly operate together with standard modules supplied by the toolkit.
-Detector-simulation depends strongly on the use of an underlying simulation toolkit,
-the most prominent candidate nowadays being Geant4~\cite{bib:geant4}.
-\DDhep supports simulation activities with Geant4 providing
-an automatic translation mechanism between geometry representations.
-The simulation response in the active elements of the detector
-is strongly influenced by the technical
-choices and precise simulations depends on the very specific detection techniques.
-
-\noindent
-Similar to the aim of \DDhep~\cite{bib:DD4hep},
-where with time a standard palette of detector
-components developed by users should become part of the toolkit,
-\DDG also hopes to provide a standard palette of components used
-to support simulation activities for detector layouts
-where detector designers may base the simulation of a planned experiment
-on these predefined components for initial design and optimization
-studies.
-
-\noindent
-This is not a manual to Geant4 nor the basic infrastructure of \DDhep.
-It is assumed that this knowledge is present and the typical glossary
-is known.
-
-%=============================================================================
-\section{The Geant4 User Interface}
-\label{sec:ddg4-user-manual-geant4-interface}
-%=============================================================================
-
-\noindent
-The Geant4 simulation toolkit~\cite{bib:geant4} implements a very complex
-machinery to simulate the energy deposition of particles traversing materials.
-To ease its usage for the clients and to shield clients from the complex
-internals when actually implementing a simulation applications for a
-given detector design, it provides several user hooks
-as shown in Figure~\ref{fig:ddg4-g4runmanager-anatomy}. Each of these hooks
-serves a well specialized purpose, but unfortunately also leads to very
-specialized applications. One aim of \DDG is to formalize these user
-actions so that the invocation at the appropriate time may be purely
-data driven.
-\begin{figure}[h]
- \begin{center}
- \includegraphics[height=70mm] {DDG4-G4RunManagerAnatomy.png}
- \caption{The various user hooks provided by Geant4. Not shown here
- is the callback system interfacing to the active elements
- of the detector design.}
- \label{fig:ddg4-g4runmanager-anatomy}
- \end{center}
-\end{figure}
-
-\noindent
-In detail the following object-hooks allow the client to define user provided actions:
-\begin{itemize}\itemcompact
-\item The \bold{User Physics List} allows the client to customize and define
- the underlying physics process(es) which define the particle interactions
- inside the detector defined with the geometry description.
- These interactions define the detector response in terms of
- energy depositions.
-\item The \bold{Run Action} is called once at the start and end of a run.
- i.e. a series of generated events. These two callbacks
- allow clients to define run-dependent actions such as statistics
- summaries etc.
-\item The \bold{Primary Generator Action} is called for every event.
- During the callback all particles are created which form the
- microscopic kinematic action of the particle collision.
- This input may either origin directly from an event generator program
- or come from file.
-\item The \bold{Event Action} is called once at the start and the end of each event.
- It is typically used for a simple analysis of the processed event.
- If the simulated data should be written to some persistent medium,
- the call at the end of the event processing is the appropriate place.
-\item The \bold{Tracking Action}
-\item The \bold{Stepping Action}
-\item The \bold{Stacking Action}
-\end{itemize}
-\noindent
-Geant4 provides all callbacks with the necessary information in the form of
-appropriate arguments.
-
-\noindent
-Besides the callback system, Geant4 provides callbacks whenever a particle
-traverses a sensitive volume. These callbacks are called
-- similar to event actions - once at the start and the end of the event,
-but in addition, if either the energy deposit of a particle in the
-sensitive volume exceeds some threshold. The callbacks are formalized within
-the base class \tts{G4VSensitiveDetector}.
-
-%=============================================================================
-\section{DDG4 Implementation}
-\label{sec:ddg4-user-manual-implementation}
-%=============================================================================
-
-\noindent
-A basic design criteria of the a \DDG simulation application was to
-process any user defined hook provided by Geant4 as a series of algorithmic
-procedures, which could be implemented either using inheritance or by
-a callback mechanism registering functions fulfilling a given signature.
-Such sequences are provided for all actions mentioned in the list in
-Section~\ref{sec:ddg4-user-manual-geant4-interface} as well as for
-the callbacks to sensitive detectors.
-
-\noindent
-The callback mechanism was introduced to allow for weak coupling between
-the various actions. For example could an action performing monitoring
-using histograms at the event level initialize or reset its histograms
-at the start/end of each run. To do so, clearly a callback at the
-start/end of a run would be necessary.
-
-\noindent
-In the following sections a flexible and extensible interface to hooks
-of Geant4 is discussed starting with the description of the basic
-components \tts{Geant4Kernel} and \tts{Geant4Action} followed by the
-implementation of the relevant specializations.
-The specializations exposed are sequences of such actions,
-which also call registered objects.
-In later section the configuration and the combination of these components
-forming a functional simulation application is presented.
-
-%=============================================================================
-\subsection{The Application Core Object: \tts{Geant4Kernel}}
-\label{sec:ddg4-user-manual-implementation-geant4kernel}
-%=============================================================================
-
-\noindent
-The kernel object is the central context of a \DDG simulation application and
-gives all clients access to the user hooks (see Figure~\ref{fig:ddg4-geant4-kernel}).
-All Geant4 callback structures are exposed so that clients can easily
-objects implementing the required interface or register callbacks with the
-correct signature.
-\begin{figure}[h]
- \begin{center}
- \includegraphics[height=80mm] {DDG4-Geant4Kernel.png}
- \caption{The sensitive detector design.}
- \label{fig:ddg4-geant4-kernel}
- \end{center}
-\end{figure}
-
-%=============================================================================
-\subsection{The Base Class of DDG4 Actions: \tts{Geant4Action}}
-\label{sec:ddg4-user-manual-implementation-geant4action-base}
-%=============================================================================
-
-\noindent
-The class \tts{Geant4Action} is a common component interface providing
-the basic interface to the framework to
-\begin{itemize}\itemcompact
-\item configure the component using a property mechanism
-\item provide an appropriate interface to Geant4 interactivity. The interactivity
- included a generic way to change and access properties from the Geant4 UI
- prompt as well as executing registered commands.
-\item As shown in Figure~\ref{fig:ddg4-implementation-geant4-action}, the
- base class also provides to its sub-class a reference to the \tts{Geant4Kernel}
- objects through the \tts{Geant4Context}.
-\end{itemize}
-The \tts{Geant4Action} is a named entity and can be uniquely identified within
-a sequence attached to one Geant4 user callback.
-%=============================================================================
-\begin{figure}[h]
- \begin{center}
- \includegraphics[height=30mm] {DDG4-Geant4Action.png}
- \caption{The design of the common base class \tts{Geant4Action}.}
- \label{fig:ddg4-implementation-geant4-action}
- \end{center}
-\end{figure}
-
-\noindent
-\DDG knowns two types of actions: global actions and anonymous actions.
-Global actions are accessible externally from the \tts{Geant4Kernel} instance.
-Global actions are also re-usable and hence may be contribute to several
-action sequences (see the following chapters for details). Global actions
-are uniquely identified by their name.
-Anonymous actions are known only within one sequence and normally
-are not shared between sequences.
-
-%=============================================================================
-\subsubsection{The Properties of \bold{Geant4Action} Instances}
-\label{sec:ddg4-implementation-geant4-action-properties}
-%=============================================================================
-
-\noindent
-Nearly any subclass of a \tts{Geant4Action} needs a flexible configuration
-in order to be reused, modified etc. The implementation of the mechanism
-uses a very flexible value conversion mechanism using \tts{boost::spirit},
-which support also conversions between unrelated types provided a dictionary
-is present.
-
-\noindent
-Properties are supposed to be member variables of a given action object.
-To publish a property it needs to be declared in the constructor as shown here:
-\begin{unnumberedcode}
- declareProperty("OutputLevel", m_outputLevel = INFO);
- declareProperty("Control", m_needsControl = false);
-\end{unnumberedcode}
-The internal setup of the \tts{Geant4Action} objects then ensure that
-all declared properties will be set after the object construction to the
-values set in the setup file.
-
-\noindent
-\bold{Note:} Because the values can only be set \bold{after} the object
-was constructed, the actual values may not be used in the constructor
-of any base or sub-class.
-
-%=============================================================================
-\subsection{Geant4 Action Sequences}
-\label{sec:ddg4-user-manual-implementation-geant4action-sequences}
-%=============================================================================
-
-\noindent
-The main action sequences have a fixed name. These are
-\begin{itemize}
-
-\item The \bold{RunAction} attached to the \tts{G4UserRunAction}, implemented
- by the \tts{Geant4RunActionSequence} class and is called at the start and the end of
- every run (beamOn). Members of the \tts{Geant4RunActionSequence} are of type
- \tts{Geant4RunAction} and receive the callbacks by overloading the two routines:
-\begin{unnumberedcode}
-/// begin-of-run callback
-virtual void begin(const G4Run* run);
-/// End-of-run callback
-virtual void end(const G4Run* run);
-\end{unnumberedcode}
- or register a callback with the signature {\tts{void (T::*)(const G4Run*)}}
- either to receive begin-of-run or end-or-calls using the methods:
-\begin{unnumberedcode}
-/// Register begin-of-run callback. Types Q and T must be polymorph!
-template <typename Q, typename T> void callAtBegin(Q* p, void (T::*f)(const G4Run*));
-/// Register end-of-run callback. Types Q and T must be polymorph!
-template <typename Q, typename T> void callAtEnd(Q* p, void (T::*f)(const G4Run*));
-\end{unnumberedcode}
- of the \tts{Geant4RunActionSequence} from the \tts{Geant4Context} object.
-
-
-\item The \bold{EventAction} attached to the \tts{G4UserEventAction}, implemented
- by the \tts{EventActionSequence} class and is called at the start and the end of
- every event. Members of the \tts{Geant4EventActionSequence} are of type
- \tts{Geant4EventAction} and receive the callbacks by overloading the two routines:
-\begin{unnumberedcode}
-/// Begin-of-event callback
-virtual void begin(const G4Event* event);
-/// End-of-event callback
-virtual void end(const G4Event* event);
-\end{unnumberedcode}
- or register a callback with the signature {\tts{void (T::*)(const G4Event*)}}
- either to receive begin-of-run or end-or-calls using the methods:
-\begin{unnumberedcode}
-/// Register begin-of-event callback
-template <typename Q, typename T> void callAtBegin(Q* p, void (T::*f)(const G4Event*));
-/// Register end-of-event callback
-template <typename Q, typename T> void callAtEnd(Q* p, void (T::*f)(const G4Event*));
-\end{unnumberedcode}
- of the \tts{Geant4EventActionSequence} from the \tts{Geant4Context} object.
-
-
-\item The \bold{GeneratorAction} attached to the \tts{G4VUserPrimaryGeneratorAction}, implemented
- by the \tts{Geant4GeneratorActionSequence} class and is called at the start of
- every event and provided all initial tracks from the Monte-Carlo generator.
- Members of the \tts{Geant4GeneratorActionSequence} are of type
- \tts{Geant4EventAction} and receive the callbacks by overloading the member function:
-\begin{unnumberedcode}
-/// Callback to generate primary particles
-virtual void operator()(G4Event* event);
-\end{unnumberedcode}
- or register a callback with the signature {\tts{void (T::*)(G4Event*)}}
- to receive calls using the method:
-\begin{unnumberedcode}
-/// Register primary particle generation callback.
-template <typename Q, typename T> void call(Q* p, void (T::*f)(G4Event*));
-\end{unnumberedcode}
- of the \tts{Geant4GeneratorActionSequence} from the \tts{Geant4Context} object.
-
-\end{itemize}
-\begin{figure}[t]
- \begin{center}
- \includegraphics[width=160mm] {DDG4-TrackingAction.png}
- \caption{The design of the tracking action sequence. Specialized
- tracking action objects inherit from the \tts{Geant4TrackingAction}
- object and must be attached to the sequence.}
- \label{fig:ddg4-implementation-tracking-action}
- \end{center}
-\end{figure}
-
-\begin{itemize}
-\item The \bold{TrackingAction} attached to the \tts{G4UserTrackingAction},
- implemented by the \tts{Geant4-} \tts{Tracking\-Action\-Sequence} class
- and is called at the start and the end of tracking one single particle
- trace through the material of the detector.
- Members of the \tts{Geant4\-Tracking\-ActionSequence} are of type
- \tts{Geant4TrackingAction} and receive the callbacks by overloading the member function:
-\begin{unnumberedcode}
-/// Pre-tracking action callback
-virtual void begin(const G4Track* trk);
-/// Post-tracking action callback
-virtual void end(const G4Track* trk);
-\end{unnumberedcode}
- or register a callback with the signature {\tts{void (T::*)(const G4Step*, G4SteppingManager*)}}
- to receive calls using the method:
-\begin{unnumberedcode}
-/// Register Pre-track action callback
-template <typename Q, typename T> void callAtBegin(Q* p, void (T::*f)(const G4Track*));
-/// Register Post-track action callback
-template <typename Q, typename T> void callAtEnd(Q* p, void (T::*f)(const G4Track*));
-\end{unnumberedcode}
-
-
-\item The \bold{SteppingAction} attached to the \tts{G4UserSteppingAction}, implemented
- by the \tts{Geant4-} \tts{SteppingActionSequence} class and is called for each
- step when tracking a particle.
- Members of the \tts{Geant4SteppingActionSequence} are of type
- \tts{Geant4SteppingAction} and receive the callbacks by overloading the member function:
-\begin{unnumberedcode}
-/// User stepping callback
-virtual void operator()(const G4Step* step, G4SteppingManager* mgr);
-\end{unnumberedcode}
- or register a callback with the signature {\tts{void (T::*)(const G4Step*, G4SteppingManager*)}}
- to receive calls using the method:
-\begin{unnumberedcode}
-/// Register stepping action callback.
-template <typename Q, typename T> void call(Q* p, void (T::*f)(const G4Step*,
- G4SteppingManager*));
-\end{unnumberedcode}
-
-
-\item The \bold{StackingAction} attached to the
- {\tts{G4UserStackingAction}}, implemented by the \tts{Geant4-}\\
- \tts{StackingActionSequence} class.
- Members of the \tts{Geant4StackingActionSequence} are of type\\
- \detdesc{html/class_d_d4hep_1_1_simulation_1_1_geant4_stacking_action.html}
- {\tts{Geant4StackingAction}} and receive the callbacks by overloading the member functions:
-\begin{unnumberedcode}
-/// New-stage callback
-virtual void newStage();
-/// Preparation callback
-virtual void prepare();
-\end{unnumberedcode}
- or register a callback with the signature {\tts{void (T::*)()}}
- to receive calls using the method:
-\begin{unnumberedcode}
-/// Register begin-of-event callback. Types Q and T must be polymorph!
-template <typename T> void callAtNewStage(T* p, void (T::*f)());
-/// Register end-of-event callback. Types Q and T must be polymorph!
-template <typename T> void callAtPrepare(T* p, void (T::*f)());
-\end{unnumberedcode}
-\end{itemize}
-
-\noindent
-All sequence types support the method \tts{void adopt(T* member\_reference)}
-to add the members. Once adopted, the sequence takes ownership and manages
-the member. The design of the sequences is very similar.
-Figure~\ref{fig:ddg4-implementation-tracking-action} show as an example
-the design of the \tts{Geant4TrackingAction}.
-
-\begin{figure}[h]
- \begin{center}
- \includegraphics[height=110mm] {DDG4-Sensitive-detector.png}
- \caption{The sensitive detector design. The actual energy deposits are
- collected in user defined subclasses of the \tts{Geant4Sensitive}.
- Here, as an example possible actions called \tts{TrackerHitCollector},
- \tts{TrackerDetailedHitCollector} and \tts{TrackerHitMonitor} are shown.}
- \label{fig:ddg4-implementation-sensitive-detector}
- \end{center}
-\end{figure}
-
-%=============================================================================
-\subsection{Sensitive Detectors}
-\label{sec:ddg4-user-manual-geant4sensitivedetectors}
-%=============================================================================
-
-\noindent
-Sensitive detectors are associated by the detector designers to all active
-materials, which would produce a signal which can be read out. In Geant4 this concept
-is realized by using a base class \tts{G4VSensitiveDetector}, which receives
-a callback at the begin and the end of the event processing and at each step
-inside the active material whenever an energy deposition occurred.
-
-\noindent
-The sensitive actions do not necessarily deal only the collection of energy
-deposits, but could also be used to simply monitor the performance of the
-active element e.g. by producing histograms of the absolute value or the
-spacial distribution of the depositions.
-
-\noindent
-Within \DDG the concept of sensitive detectors is implemented as a
-configurable action sequence of type
-\detdesc{html/class_d_d4hep_1_1_simulation_1_1_geant4_sens_det_action_sequence.html}
-{\tts{Geant4SensDetActionSequence}}
-calling members of the type
-\detdesc{html/struct_d_d4hep_1_1_simulation_1_1_geant4_sensitive.html}
-{\tts{Geant4Sensitive}} as shown in
-Figure~\ref{fig:ddg4-implementation-sensitive-detector}. The actual processing
-part of such a sensitive action is only called if the and of a set of
-required filters of type \tts{Geant4Filter} is positive (see also
-section~\ref{sec:ddg4-implementation-sensitive-detector-filters}). No filter
-is also positive. Possible filters are e.g. particle filters, which ignore the
-sensitive detector action if the particle is a \tts{geantino} or if the
-energy deposit is below a given threshold.
-
-\noindent
-Objects of type \tts{Geant4Sensitive} receive the callbacks by overloading the
-member function:
-\begin{unnumberedcode}
- /// Method invoked at the begining of each event.
- virtual void begin(G4HCofThisEvent* hce);
- /// Method invoked at the end of each event.
- virtual void end(G4HCofThisEvent* hce);
- /// Method for generating hit(s) using the information of G4Step object.
- virtual bool process(G4Step* step, G4TouchableHistory* history);
- /// Method invoked if the event was aborted.
- virtual void clear(G4HCofThisEvent* hce);
-\end{unnumberedcode}
-or register a callback with the signature {\tts{void (T::*)(G4HCofThisEvent*)}}
-respectively {\tts{void (T::*)(G4Step*, G4TouchableHistory*)}}
-to receive callbacks using the methods:
-\begin{unnumberedcode}
- /// Register begin-of-event callback
- template <typename T> void callAtBegin(T* p, void (T::*f)(G4HCofThisEvent*));
- /// Register end-of-event callback
- template <typename T> void callAtEnd(T* p, void (T::*f)(G4HCofThisEvent*));
- /// Register process-hit callback
- template <typename T> void callAtProcess(T* p, void (T::*f)(G4Step*, G4TouchableHistory*));
- /// Register clear callback
- template <typename T> void callAtClear(T* p, void (T::*f)(G4HCofThisEvent*));
-\end{unnumberedcode}
-
-%=============================================================================
-\subsubsection{Sensitive Detector Filters}
-\label{sec:ddg4-implementation-sensitive-detector-filters}
-%=============================================================================
-
-\noindent
-Filters are called by Geant4 before the
-hit processing in the sensitive detectors start. The global filters
-may be shared between many sensitive detectors. Alternatively filters
-may be directly attached to the sensitive detector in question.
-Attributes are directly passed as properties to the filter action.
-
-\newpage
-%=============================================================================
-\subsection{The Geant4 Physics List}
-\label{sec:ddg4-implementation-physics-list}
-%=============================================================================
-\noindent
-Geant4 provides the base class \tts{G4VUserPhysicsList}. Any user defined
-physics list must provide this interface. DDG4 provides such an interface
-through the ROOT plugin mechanism using the class \tts{G4VModularPhysicsList}.
-The flexibility of \DDG allows for several possibilities to setup the Geant4
-physics list.
-\begin{itemize}
-\item The \bold{physics list} may be configured as a sequence of type
- \detdesc{html/class_d_d4hep_1_1_simulation_1_1_geant4_physics_list_action_sequence.html}
- {\tts{Geant4PhysicsListActionSequence}}.
- Members of the \detdesc{html/class_d_d4hep_1_1_simulation_1_1_geant4_physics_list_action_sequence.html}
- {\tts{Geant4PhysicsListActionSequence}} are of type
- \detdesc{html/class_d_d4hep_1_1_simulation_1_1_geant4_physics_list.html}
- {\tts{Geant4PhysicsList}} and receive the callbacks by overloading
- the member functions:
-\begin{unnumberedcode}
- /// Callback to construct the physics constructors
- virtual void constructProcess(Geant4UserPhysics* interface);
- /// constructParticle callback
- virtual void constructParticles(Geant4UserPhysics* particle);
- /// constructPhysics callback
- virtual void constructPhysics(Geant4UserPhysics* physics);
-\end{unnumberedcode}
- or register a callback with the signature {\tts{void (T::*)(Geant4UserPhysics*)}}
- to receive calls using the method:
-\begin{unnumberedcode}
- /// Register process construction callback t
- template <typename Q, typename T> void constructProcess(Q* p, void (T::*f)(Geant4UserPhysics*));
- /// Register particle construction callback
- template <typename Q, typename T> void constructParticle(Q* p, void (T::*f)(Geant4UserPhysics*));
-\end{unnumberedcode}
- The argument of type \detdesc{html/class_d_d4hep_1_1_simulation_1_1_geant4_user_physics.html}
- {\tts{Geant4UserPhysics}} provides a basic interface to the original
- \tts{G4VModular}- \tts{PhysicsList}, which allows to register physics constructors etc.
-
-\item In most of the cases the above approach is an overkill and often even too flexible.
- Hence, alternatively, the physics list may consist of a single entry of type
- \detdesc{html/class_d_d4hep_1_1_simulation_1_1_geant4_physics_list.html}
- {\tts{Geant4PhysicsList}}.
-\end{itemize}
-
-\noindent
-The basic implementation of the \tts{Geant4PhysicsList} supports the usage of various
-\begin{itemize}\itemcompact
-\item \detdesc{}{particle constructors}, such as single particle constructors like
- \tts{G4Gamma} or \tts{G4Proton}, or whole particle groups like
- \tts{G4BosonConstructor} or \tts{G4IonConstrutor},
-\item \detdesc{}{physics process constructors}, such as e.g. \tts{G4GammaConversion},
- \tts{G4PhotoElectricEffect} or\\ \tts{G4ComptonScattering},
-\item \detdesc{}{physics constructors} combining particles and the corresponding
- interactions, such as\\ e.g. \tts{G4OpticalPhysics},
- \tts{HadronPhysicsLHEP} or \tts{G4HadronElasticPhysics} and
-\item \detdesc{}{predefined Geant4 physics lists}, such as \tts{FTFP\_BERT},
- \tts{CHIPS} or \tts{QGSP\_INCLXX}. This option is triggered by the
- content of the string property "extends" of the \tts{Geant4Kernel::physicsList()} action.
-\end{itemize}
-These constructors are internally connected to the above callbacks to register themselves.
-The constructors are instantiated using the ROOT plugin mechanism.
-
-\noindent
-The description of the above interface is only for completeness. The basic idea is,
-that the physics list with its particle and physics constructors is configured
-entirely data driven using the setup mechanism described in the following
-chapter. However, DDG4 is not limited to the data driven approach. Specialized
-physics lists may be supplied, but there should be no need.
-New physics lists could always be composed by actually providing new physics
-constructors and actually publishing these using the factory methods:
-\begin{code}
-// Framework include files
-#include "DDG4/Factories.h"
-
-#include "My_Very_Own_Physics_Constructor.h"
-DECLARE_GEANT4_PHYSICS(My_Very_Own_Physics_Constructor)
-\end{code}
-where \tts{My\_Very\_Own\_Physics\_Constructor} represents a sub-class of
-\tts{G4VPhysicsConstructor}.
-
-\newpage
-%=============================================================================
-\subsection{The Support of the Geant4 UI: \tw{Geant4UIMessenger}}
-\label{sec:ddg4-user-manual-geant4action-base}
-%=============================================================================
-
-\noindent
-The support of interactive in Geant4 is absolutely mandatory to debug detector
-setups in small steps. The Geant4 toolkit did provide for this reason
-a machinery of UI commands.
-\begin{figure}[h]
- \begin{center}
- \includegraphics[height=70mm] {DDG4-UIMessenger.png}
- \caption{The design of the \tts{Geant4UIMessenger} class responsible for
- the interaction between the user and the components of \DDG and Geant4.}
- \label{fig:ddg4-tracking-action}
- \end{center}
-\end{figure}
-
-\noindent
-The UI control is enabled, as soon as the property "Control" (boolean) is set to true.
-Be default all properties of the action are exported.
-Similar to the callback mechanism described above it is also feasible to
-register any object callback invoking a method of a \tts{Geant4Action}-subclass.
-
-\noindent
-The following (shortened) screen dump illustrates the usage of the
-generic interface any Geant4Action offers:
-\begin{unnumberedcode}
-Idle> ls
-Command directory path : /
- Sub-directories :
- /control/ UI control commands.
- /units/ Available units.
- /process/ Process Table control commands.
- /ddg4/ Control for all named Geant4 actions
- ...
-Idle> cd /ddg4
-Idle> ls
-...
-Control for all named Geant4 actions
-
- Sub-directories :
- /ddg4/EventAction/ Control hierarchy for Geant4 action:EventAction
- /ddg4/RunAction/ Control hierarchy for Geant4 action:RunAction
- /ddg4/Gun/ Control hierarchy for Geant4 action:Gun
- /ddg4/GeneratorAction/ Control hierarchy for Geant4 action:GeneratorAction
- /ddg4/PhysicsList/ Control hierarchy for Geant4 action:PhysicsList
-Idle> ls Gun
-...
-Control hierarchy for Geant4 action:Gun
-
- Sub-directories :
- Commands :
- show * Show all properties of Geant4 component:Gun
-...
- particle * Property item of type std::string
- pos_x * Property item of type double
- pos_y * Property item of type double
- pos_z * Property item of type double
-Idle> Gun/show
-...
-PropertyManager: Property multiplicity = 1
-PropertyManager: Property name = 'Gun'
-PropertyManager: Property particle = 'e-'
-PropertyManager: Property pos_x = 0
-PropertyManager: Property pos_y = 0
-PropertyManager: Property pos_z = 0
-
-Idle> Gun/pos_z 1.0
-Geant4UIMessenger: +++ Gun> Setting new property value pos_z = 1.0.
-Idle> Gun/pos_y 1.0
-Geant4UIMessenger: +++ Gun> Setting new property value pos_y = 1.0.
-Idle> Gun/pos_x 1.0
-Geant4UIMessenger: +++ Gun> Setting new property value pos_x = 1.0.
-Idle> Gun/show
-...
-PropertyManager: Property pos_x = 1
-PropertyManager: Property pos_y = 1
-PropertyManager: Property pos_z = 1
-
-\end{unnumberedcode}
-
-
-\newpage
-%=============================================================================
-\section{Setting up DDG4}
-\label{sec:ddg4-setup}
-%=============================================================================
-
-\noindent
-
-
-%=============================================================================
-\subsection{Setting up DDG4 using XML}
-\label{sec:ddg4-setup-xml}
-%=============================================================================
-
-\noindent
-A special plugin was developed to enable the configuration of \DDG using
-XML structures. These files are parsed identically to the geometry setup
-in \DDhep the only difference is the name of the root-element, which for
-\DDG is \tts{<geant4\_setup>}.
-The following code snippet shows the basic structure of a \DDG setup file:
-\begin{unnumberedcode}
-<geant4_setup>
- <physicslist> ,,, </physicslist> <!-- Defintiion of the physics list -->
- <actions> ... </actions> <!-- The list of global actions -->
- <phases> ... </phases> <!-- The definition of the various phases -->
- <filters> ... </filters> <!-- The list of global filter actions -->
- <sequences> ... </sequences> <!-- The list of defined sequences -->
- <sensitive_detectors> ... </sensitive_detectors> <!-- The list of sensitive detectors -->
- <properties> ... </properties> <!-- Free format option sequences -->
-</geant4_setup>
-\end{unnumberedcode}
-To setup a \DDG4 application any number of xml setup files may be interpreted
-iteratively. In the following subsections the content of these first level sub-trees will
-be discussed.
-
-%=============================================================================
-\subsubsection{Setup of the Physics List}
-\label{sec:ddg4-setup-xml-physicslist}
-%=============================================================================
-
-\noindent
-The main tag to setup a physics list is \tts{<physicslist>} with the
-\tts{name} attribute defining the instance of the \tts{Geant4PhysicsList} object.
-An example code snippet is shown below in Figure~\ref{fig:ddg4-setup-xml-physicslist}.
-
-\begin{code}
-<geant4_setup>
- <physicslist name="Geant4PhysicsList/MyPhysics.0">
-
- <extends name="QGSP_BERT"/> <!-- Geant4 basic Physics list -->
-
- <particles> <!-- Particle constructors -->
- <construct name="G4Geantino"/>
- <construct name="G4ChargedGeantino"/>
- <construct name="G4Electron"/>
- <construct name="G4Gamma"/>
- <construct name="G4BosonConstructor"/>
- <construct name="G4LeptonConstructor"/>
- <construct name="G4MesonConstructor"/>
- <construct name="G4BaryonConstructor"/>
- ...
- </particles>
-
- <processes> <!-- Process constructors -->
- <particle name="e[+-]" cut="1*mm">
- <process name="G4eMultipleScattering" ordAtRestDoIt="-1" ordAlongSteptDoIt="1"
- ordPostStepDoIt="1"/>
- <process name="G4eIonisation" ordAtRestDoIt="-1" ordAlongSteptDoIt="2"
- ordPostStepDoIt="2"/>
- </particle>
- <particle name="mu[+-]">
- <process name="G4MuMultipleScattering" ordAtRestDoIt="-1" ordAlongSteptDoIt="1"
- ordPostStepDoIt="1"/>
- <process name="G4MuIonisation" ordAtRestDoIt="-1" ordAlongSteptDoIt="2"
- ordPostStepDoIt="2"/>
- </particle>
- ...
- </processes>
-
- <physics> <!-- Physics constructors -->
- <construct name="G4EmStandardPhysics"/>
- <construct name="HadronPhysicsQGSP"/>
- ...
- </physics>
-
- </physicslist>
-</geant4_setup>
-\end{code}
-\begin{figure}[h]
-\caption{XML snippet showing the configuration of a physics list.}
-\label{fig:ddg4-setup-xml-physicslist}
-\end{figure}
-
-
-To trigger a call to a
-\begin{itemize}\itemcompact
-\item \bold{particle constructors} (line 7-14), use the \tts{<particles>} section
- and define the Geant4 particle constructor to be called by name. To trigger a call to
-\item \bold{physics process constructors}, as shown in line 19-30,
- Define for each particle matching the name pattern (regular expression!) and the
- default cut value for the corresponding processes. The attributes ordXXXX correspond
- to the arguments of the Geant4 call \\
- \tts{G4ProcessManager::AddProcess(process,ordAtRestDoIt, ordAlongSteptDoIt,ordPostStepDoIt);}
- The processes themself are created using the ROOT plugin mechanism.
- To trigger a call to
-\item \bold{physics constructors}, as shown in line 34-35, use the \tts{<physics>} section
- and
-\item to base all these constructs on an already existing predefined Geant4 physics list
- use the \tts{<extends>} tag with the attribute containing the name of the physics list
- as shown in line 4.
-\end{itemize}
-If only a predefined physics list is used, which probably already satisfies very many use cases,
-all these section collapse to:
-\begin{code}
-<geant4_setup>
- <physicslist name="Geant4PhysicsList/MyPhysics.0">
- <extends name="QGSP_BERT"/> <!-- Geant4 basic Physics list -->
- </physicslist>
-</geant4_setup>
-\end{code}
-
-%=============================================================================
-\subsubsection{Setup of Global Geant4 Actions}
-\label{sec:ddg4-setup-xml-geant4-actions}
-%=============================================================================
-
-\noindent
-Global actions must be defined in the \tts{<actions>} section as shown in the following snippet:
-\begin{code}
-<geant4_setup>
- <actions>
- <action name="Geant4TestRunAction/RunInit">
- <properties Property_int="12345"
- Property_double="-5e15"
- Property_string="Startrun: Hello_2"/>
- </action>
- <action name="Geant4TestEventAction/UserEvent_2"
- Property_int="1234"
- Property_double="5e15"
- Property_string="Hello_2" />
- </actions>
-</geant4_setup>
-\end{code}
-The default properties of \bold{every} \tts{Geant4Action} object are:
-\begin{unnumberedcode}
-Name [string] Action name
-OutputLevel [int] Flag to customize the level of printout
-Control [boolean] Flag if the UI messenger should be installed.
-\end{unnumberedcode}
-The \tts{name} attribute of an action child is a qualified name: The first part
-denotes the type of the plugin (i.e. its class), the second part the name of the instance.
-Within one collection the instance \tts{name} must be unique.
-Properties of Geant4Actions are set by placing them as attributes into the
-\tts{<properties>} section.
-
-%=============================================================================
-\subsubsection{Setup of Geant4 Filters}
-\label{sec:ddg4-setup-xml-geant4-filters}
-%=============================================================================
-\noindent
-Filters are special actions called by \tts{Geant4Sensitive}s.
-Filters may be global or anonymous i.e. reusable by several sensitive detector
-sequences as illustrated in Section~\ref{sec:ddg4-setup-xml-geant4-sequences}.
-The setup is analogous to the setup of global actions:
-\begin{code}
- <filters>
- <filter name="GeantinoRejectFilter/GeantinoRejector"/>
- <filter name="ParticleRejectFilter/OpticalPhotonRejector">
- <properties particle="opticalphoton"/>
- </filter>
- <filter name="ParticleSelectFilter/OpticalPhotonSelector">
- <properties particle="opticalphoton"/>
- </filter>
- <filter name="EnergyDepositMinimumCut">
- <properties Cut="10*MeV"/>
- </filter>
- <!-- ... next global filter ... -->
- </filters>
-\end{code}
-Global filters are accessible from the \tts{Geant4Kernel} object.
-
-%=============================================================================
-\subsubsection{Geant4 Action Sequences}
-\label{sec:ddg4-setup-xml-geant4-sequences}
-%=============================================================================
-
-\noindent
-\tts{Geant4 Action Sequences} by definition are \tts{Geant4Action} objects.
-Hence, they share the setup mechanism with properties etc. For the setup
-mechanism two different types of sequences are known to \DDG:
-{\it{Action sequences}} and {\it{Sensitive detector sequences}}. Bot are declared in
-the \tts{sequences} section:
-\begin{code}
-<geant4_setup>
- <sequences>
- <sequence name="Geant4EventActionSequence/EventAction"> <!-- Sequence "EventAction" of type
- "Geant4EventActionSequence" -->
- <action name="Geant4TestEventAction/UserEvent_1"> <!-- Anonymouns action -->
- <properties Property_int="01234" <!-- Properties go inline -->
- Property_double="1e11"
- Property_string="'Hello_1'"/>
- </action>
- <action name="UserEvent_2"/> <!-- Global action defined in "actions" -->
- <!-- Only the name is referenced here -->
- <action name="Geant4Output2ROOT/RootOutput"> <!-- ROOT I/O action -->
- <properties Output="simple.root"/> <!-- Output file property -->
- </action>
- <action name="Geant4Output2LCIO/LCIOOutput"> <!-- LCIO output action -->
- <properties Output="simple_lcio"/> <!-- Output file property -->
- </action>
- </sequence>
-
-
- <sequence sd="SiTrackerBarrel" type="Geant4SensDetActionSequence">
- <filter name="GeantinoRejector"/>
- <filter name="EnergyDepositMinimumCut"/>
- <action name="Geant4SimpleTrackerAction/SiTrackerBarrelHandler"/>
- </sequence>
- <sequence sd="SiTrackerEndcap" type="Geant4SensDetActionSequence">
- <filter name="GeantinoRejector"/>
- <filter name="EnergyDepositMinimumCut"/>
- <action name="Geant4SimpleTrackerAction/SiTrackerEndcapHandler"/>
- </sequence>
- <!-- ... next sequence ... -->
- </sequences>
-</geant4_setup>
-\end{code}
-Here firstly the \bold{EventAction} sequence is defined with its members.
-Secondly a sensitve detector sequence is defined for the subdetector
-\tts{SiTrackerBarrel} of type \tts{Geant4SensDetActionSequence}.
-The sequence uses two filters: \tts{GeantinoRejector} to not generate hits
-from geantinos and \tts{EnergyDepositMinimumCut} to enforce a minimal energy deposit.
-These filters are global i.e. they may be applied by many subdetectors.
-The setup of global filters is described in
-Section~\ref{sec:ddg4-setup-xml-geant4-filters}.
-Finally the action \tts{SiTrackerEndcapHandler} of type \tts{Geant4SimpleTrackerAction}
-is chained, which collects the deposited energy and
-creates a collection of hits. The \tts{Geant4SimpleTrackerAction} is a template
-callback to illustrate the usage of sensitive elements in \DDG.
-The resulting hit collection of these handlers by default have the same name as the
-object instance name.
-Analogous below the sensitive detector sequence for the subdetector
-\tts{SiTrackerEndcap} is shown, which reuses the same filter actions, but will build its own
-hit collection.
-
-\noindent
-\bold{Plase note:}
-\begin{itemize}\itemcompact
-\item \bold{It was already mentioned, but once again}: Event-, run-, generator-, tracking-,
- stepping- and stacking actions sequences have predefined names!
- These names are fixed and part of the \bold{common knowledge}, they cannot be altered.
- Please refer to
- Section~\ref{sec:ddg4-user-manual-implementation-geant4action-sequences}
- for the names of the global action sequences.
-\item the sensitive detector sequences are matched by the attribute \tts{sd} to the
- subdetectors created with the \DDhep detector description package. Values must match!
-\item In the event that several xml files are parsed it is absolutely vital that
- the \tts{<actions>} section is interpreted \bold{before} the \tts{sequences}.
-\item For each XML file several \tts{<sequences>} are allowed.
-\noindent
-\end{itemize}
-
-%=============================================================================
-\subsubsection{Setup of Geant4 Sensitive Detectors}
-\label{sec:ddg4-setup-xml-geant4-sensitive detectors}
-%=============================================================================
-\begin{code}
- <geant4_setup>
- <sensitive_detectors>
- <sd name="SiTrackerBarrel"
- type="Geant4SensDet"
- ecut="10.0*MeV"
- verbose="true"
- hit_aggregation="position">
- </sd>
- <!-- ... next sensitive detector ... -->
- </sensitive_detectors>
- </geant4_setup>
-\end{code}
-
-
-
-%=============================================================================
-\subsubsection{Miscellaneous Setup of Geant4 Objects}
-\label{sec:ddg4-setup-xml-geant4-objects}
-%=============================================================================
-
-\noindent
-This section is used for the flexible setup of auxiliary objects such as the
-electromagnetic fields used in Geant4:
-\begin{code}
- <geant4_setup>
- <properties>
- <attributes name="geant4_field"
- id="0"
- type="Geant4FieldSetup"
- object="GlobalSolenoid"
- global="true"
- min_chord_step="0.01*mm"
- delta_chord="0.25*mm"
- delta_intersection="1e-05*mm"
- delta_one_step="0.001*mm"
- eps_min="5e-05*mm"
- eps_max="0.001*mm"
- stepper="HelixSimpleRunge"
- equation="Mag_UsualEqRhs">
- </attributes>
- ...
- </properties>
- </geant4_setup>
-\end{code}
-Important are the tags \tts{type} and \tts{object}, which are used to firstly
-define the plugin to be called and secondly define the object from the \DDhep
-description to be configured for the use within Geant4.
-
-%=============================================================================
-\subsubsection{Setup of Geant4 Phases}
-\label{sec:ddg4-setup-xml-geant4-phases}
-%=============================================================================
-
-\noindent
-Phases are configured as shown below.
-However, the use is \bold{discouraged},
-since it is not yet clear if there are appropriate use cases!
-\begin{code}
- <phases>
- <phase type="RunAction/begin">
- <action name="RunInit"/>
- <action name="Geant4TestRunAction/UserRunInit">
- <properties Property_int="1234"
- Property_double="5e15"
- Property_string="'Hello_2'"/>
- </action>
- </phase>
- <phase type="EventAction/begin">
- <action name="UserEvent_2"/>
- </phase>
- <phase type="EventAction/end">
- <action name="UserEvent_2"/>
- </phase>
- ...
- </phases>
-\end{code}
-
-\newpage
-%=============================================================================
-\subsection{Setting up DDG4 using ROOT-CINT}
-\label{sec:ddg4-setup-root-cint}
-%=============================================================================
-
-\noindent
-The setup of \DDG directly from the the ROOT interpreter using the AClick
-mechanism is very simple, but mainly meant for purists (like me ;-)),
-since it is nearly equivalent to the explicit setup within a \tts{C++}
-main program.
-The following code section shows how to do it. For explanation the code
-secment is discussed below line by line.
-\begin{code}
-#include "DDG4/Geant4Config.h"
-#include "DDG4/Geant4TestActions.h"
-#include "DDG4/Geant4TrackHandler.h"
-#include <iostream>
-
-using namespace std;
-using namespace DD4hep;
-using namespace DD4hep::Simulation;
-using namespace DD4hep::Simulation::Test;
-using namespace DD4hep::Simulation::Setup;
-
-#if defined(__MAKECINT__)
-#pragma link C++ class Geant4RunActionSequence;
-#pragma link C++ class Geant4EventActionSequence;
-#pragma link C++ class Geant4SteppingActionSequence;
-#pragma link C++ class Geant4StackingActionSequence;
-#pragma link C++ class Geant4GeneratorActionSequence;
-#pragma link C++ class Geant4Action;
-#pragma link C++ class Geant4Kernel;
-#endif
-
-SensitiveSeq::handled_type* setupDetector(Kernel& kernel, const std::string& name) {
- SensitiveSeq sd = SensitiveSeq(kernel,name);
- Sensitive sens = Sensitive(kernel,"Geant4TestSensitive/"+name+"Handler",name);
- sd->adopt(sens);
- sens = Sensitive(kernel,"Geant4TestSensitive/"+name+"Monitor",name);
- sd->adopt(sens);
- return sd;
-}
-
-void exampleAClick() {
- Geant4Kernel& kernel = Geant4Kernel::instance(LCDD::getInstance());
- kernel.loadGeometry("file:../DD4hep.trunk/DDExamples/CLICSiD/compact/compact.xml");
- kernel.loadXML("DDG4_field.xml");
-
- GenAction gun(kernel,"Geant4ParticleGun/Gun");
- gun["energy"] = 0.5*GeV; // Set properties
- gun["particle"] = "e-";
- gun["multiplicity"] = 1;
- kernel.generatorAction().adopt(gun);
-
- Action run_init(kernel,"Geant4TestRunAction/RunInit");
- run_init["Property_int"] = 12345;
- kernel.runAction().callAtBegin (run_init.get(),&Geant4TestRunAction::begin);
- kernel.eventAction().callAtBegin(run_init.get(),&Geant4TestRunAction::beginEvent);
- kernel.eventAction().callAtEnd (run_init.get(),&Geant4TestRunAction::endEvent);
-
- Action evt_1(kernel,"Geant4TestEventAction/UserEvent_1");
- evt_1["Property_int"] = 12345; // Set properties
- evt_1["Property_string"] = "Events";
- kernel.eventAction().adopt(evt_1);
-
- EventAction evt_2(kernel,"Geant4TestEventAction/UserEvent_2");
- kernel.eventAction().adopt(evt_2);
-
- kernel.runAction().callAtBegin(evt_2.get(),&Geant4TestEventAction::begin);
- kernel.runAction().callAtEnd (evt_2.get(),&Geant4TestEventAction::end);
-
- setupDetector(kernel,"SiVertexBarrel");
- setupDetector(kernel,"SiVertexEndcap");
- // .... more subdetectors here .....
- setupDetector(kernel,"LumiCal");
- setupDetector(kernel,"BeamCal");
-
- kernel.configure();
- kernel.initialize();
- kernel.run();
- std::cout << "Successfully executed application .... " << std::endl;
- kernel.terminate();
-}
-\end{code}
-
-\noindent
-\begin{tabular} {l||p{0cm}}
-\docline{Line}{}
-\docline{1}{The header file \tts{Geant4Config.h} contains a set of wrapper
- classes to easy the creation of objects using the plugin mechanism and setting
- properties to \tts{Geant4Action} objects. These helpers and the corresponding
- functionality are not included in the wrapped classes themselves to not
- clutter the code with stuff only used for the setup.
- All contained objects are in the namespace \tts{DD4hep::Simulation::Setup}}.
-\docline{6-10}{Save yourself specifying all the namespaces objects are in....}
-\docline{13-19}{CINT processing pragmas.
- Classes defined here will be available at the ROOT prompt
- after this AClick is loaded.}
-\docline{22-29}{Sampler to fill the sensitive detector sequences for each
- subdetector with two entries: a handler and a monitor action.
- Please note, that this here is example code and in real life specialized actions
- will have to be provided for each subdetector.}
-\docline{31}{Let's go for it. here the entry point starts....}
-\docline{32}{Create the \tts{Geant4Kernel} object.}
-\docline{33}{Load the geometry into \DDhep.}
-\docline{34}{Redefine the setup of the sensitive detectors.}
-\docline{36-40}{Create the generator action of type \tts{Geant4ParticleGun} with name
- \tts{Gun}, set non-default properties and activate the configured object
- by attaching it to the \tts{Geant4Kernel}.}
-\docline{42-46}{Create a user defined begin-of-run action callback, set the properties
- and attach it to the begin of run calls. To collect statistics extra member functions
- are registered to be called at the beginning and the end of each event.}
-\docline{48-51}{Create a user defined event action routine, set its properties
- and attach it to the event action sequence.}
-\docline{53-54}{Create a second event action and register it to the event action sequence.
- This action will be called after the previously created action.}
-\docline{56-57}{For this event action we want to receive callbacks at start-
- and end-of-run to produce additional summary output.}
-\docline{59-63}{Call the sampler routine to attach test actions to the subdetectors defined.}
-\docline{65-66}{Configure, initialize and run the Geant4 application.
- Most of the Geant4 actions will only be created here and the action sequences
- created before will be attached now.}
-\docline{69}{Terminate the Geant4 application and exit.}
-\end{tabular}
-
-\newpage
-\noindent
-CINT currently cannot handle pointers to member functions~\footnote{This may change
-in the future once ROOT uses \tts{clang} and \tts{cling} as the interpreting engine.}.
-Hence the above AClick only works in compiled mode. To invoke the compilation the following
-action is necessary from the ROOT prompt:
-
-
-\begin{code}
-$> root.exe
- *******************************************
- * *
- * W E L C O M E to R O O T *
- * *
- * Version 5.34/10 29 August 2013 *
- * *
- * You are welcome to visit our Web site *
- * http://root.cern.ch *
- * *
- *******************************************
-
-ROOT 5.34/10 (heads/v5-34-00-patches@v5-34-10-5-g0e8bac8, Sep 04 2013, 11:52:19 on linux)
-
-CINT/ROOT C/C++ Interpreter version 5.18.00, July 2, 2010
-Type ? for help. Commands must be C++ statements.
-Enclose multiple statements between { }.
-root [0] .X initAClick.C
-.... Setting up the CINT include pathes and the link statements.
-
-root [1] .L ../DD4hep.trunk/DDG4/examples/exampleAClick.C+
-Info in <TUnixSystem::ACLiC>: creating shared library ....exampleAClick_C.so
-.... some Cint warnings concerning member function pointers .....
-
-root [2] exampleAClick()
-.... and it starts ...
-\end{code}
-
-\noindent
-The above scripts are present in the DDG4/example directory located in svn.
-The intialization script \tts{initAClick.C} may require customization
-to cope with the installation pathes.
-
-%=============================================================================
-\subsection{Setting up DDG4 using Python}
-\label{sec:ddg4-setup-python}
-%=============================================================================
-
-\noindent
-Given the reflection interface of ROOT, the setup of the simulation interface
-using DD4hep is of course also possible using the python interpreted language.
-In the following code example the setup of Geant4 using the \tw{ClicSid}
-example is shown using python~\footnote{For comparison, the same example was
-used to illustrate the setup using XML files.}.
-
-\begin{code}
-import DDG4
-from SystemOfUnits import *
-
-"""
-
- DD4hep example setup using the python configuration
-
- @author M.Frank
- @version 1.0
-
-"""
-def run():
- kernel = DDG4.Kernel()
- kernel.loadGeometry("file:../DD4hep.trunk/DDExamples/CLICSiD/compact/compact.xml")
- kernel.loadXML("DDG4_field.xml")
-
- lcdd = kernel.lcdd()
- print '+++ List of sensitive detectors:'
- for i in lcdd.detectors():
- o = DDG4.DetElement(i.second)
- sd = lcdd.sensitiveDetector(o.name())
- if sd.isValid():
- print '+++ %-32s type:%s'%(o.name(), sd.type(), )
-
- # Configure Run actions
- run1 = DDG4.RunAction(kernel,'Geant4TestRunAction/RunInit')
- run1.Property_int = 12345
- run1.Property_double = -5e15*keV
- run1.Property_string = 'Startrun: Hello_2'
- print run1.Property_string, run1.Property_double, run1.Property_int
- run1.enableUI()
- kernel.registerGlobalAction(run1)
- kernel.runAction().add(run1)
-
- # Configure Event actions
- evt2 = DDG4.EventAction(kernel,'Geant4TestEventAction/UserEvent_2')
- evt2.Property_int = 123454321
- evt2.Property_double = 5e15*GeV
- evt2.Property_string = 'Hello_2 from the python setup'
- evt2.enableUI()
- kernel.registerGlobalAction(evt2)
-
- evt1 = DDG4.EventAction(kernel,'Geant4TestEventAction/UserEvent_1')
- evt1.Property_int=01234
- evt1.Property_double=1e11
- evt1.Property_string='Hello_1'
- evt1.enableUI()
-
- kernel.eventAction().add(evt1)
- kernel.eventAction().add(evt2)
-
- # Configure I/O
- evt_root = DDG4.EventAction(kernel,'Geant4Output2ROOT/RootOutput')
- evt_root.Control = True
- evt_root.Output = "simple.root"
- evt_root.enableUI()
-
- evt_lcio = DDG4.EventAction(kernel,'Geant4Output2LCIO/LcioOutput')
- evt_lcio.Output = "simple_lcio"
- evt_lcio.enableUI()
-
- kernel.eventAction().add(evt_root)
- kernel.eventAction().add(evt_lcio)
-
- # Setup particle gun
- gun = DDG4.GeneratorAction(kernel,"Geant4ParticleGun/Gun")
- gun.energy = 0.5*GeV
- gun.particle = 'e-'
- gun.multiplicity = 1
- gun.enableUI()
- kernel.generatorAction().add(gun)
-
- # Setup global filters fur use in sensntive detectors
- f1 = DDG4.Filter(kernel,'GeantinoRejectFilter/GeantinoRejector')
- f2 = DDG4.Filter(kernel,'ParticleRejectFilter/OpticalPhotonRejector')
- f2.particle = 'opticalphoton'
- f3 = DDG4.Filter(kernel,'ParticleSelectFilter/OpticalPhotonSelector')
- f3.particle = 'opticalphoton'
- f4 = DDG4.Filter(kernel,'EnergyDepositMinimumCut')
- f4.Cut = 10*MeV
- f4.enableUI()
- kernel.registerGlobalFilter(f1)
- kernel.registerGlobalFilter(f2)
- kernel.registerGlobalFilter(f3)
- kernel.registerGlobalFilter(f4)
-
- # First the tracking detectors
- seq = DDG4.SensitiveSequence(kernel,'Geant4SensDetActionSequence/SiVertexBarrel')
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleTrackerAction/SiVertexBarrelHandler','SiVertexBarrel')
- seq.add(act)
- seq.add(f1)
- seq.add(f4)
- act.add(f1)
-
- seq = DDG4.SensitiveSequence(kernel,'Geant4SensDetActionSequence/SiVertexEndcap')
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleTrackerAction/SiVertexEndcapHandler','SiVertexEndcap')
- seq.add(act)
- seq.add(f1)
- seq.add(f4)
-
- seq = DDG4.SensitiveSequence(kernel,'Geant4SensDetActionSequence/SiTrackerBarrel')
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleTrackerAction/SiTrackerBarrelHandler','SiTrackerBarrel')
- seq.add(act)
- seq.add(f1)
- seq.add(f4)
-
- seq = DDG4.SensitiveSequence(kernel,'Geant4SensDetActionSequence/SiTrackerEndcap')
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleTrackerAction/SiTrackerEndcapHandler','SiTrackerEndcap')
- seq.add(act)
-
- seq = DDG4.SensitiveSequence(kernel,'Geant4SensDetActionSequence/SiTrackerForward')
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleTrackerAction/SiTrackerForwardHandler','SiTrackerForward')
- seq.add(act)
-
- # Now the calorimeters
- seq = DDG4.SensitiveSequence(kernel,'Geant4SensDetActionSequence/EcalBarrel')
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleCalorimeterAction/EcalBarrelHandler','EcalBarrel')
- seq.add(act)
-
- seq = DDG4.SensitiveSequence(kernel,'Geant4SensDetActionSequence/EcalEndcap')
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleCalorimeterAction/EcalEndCapHandler','EcalEndcap')
- seq.add(act)
-
- seq = DDG4.SensitiveSequence(kernel,'Geant4SensDetActionSequence/HcalBarrel')
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleCalorimeterAction/HcalBarrelHandler','HcalBarrel')
- act.adoptFilter(kernel.globalFilter('OpticalPhotonRejector'))
- seq.add(act)
-
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleCalorimeterAction/HcalOpticalBarrelHandler','HcalBarrel')
- act.adoptFilter(kernel.globalFilter('OpticalPhotonSelector'))
- seq.add(act)
-
- seq = DDG4.SensitiveSequence(kernel,'Geant4SensDetActionSequence/HcalEndcap')
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleCalorimeterAction/HcalEndcapHandler','HcalEndcap')
- seq.add(act)
-
- seq = DDG4.SensitiveSequence(kernel,'Geant4SensDetActionSequence/HcalPlug')
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleCalorimeterAction/HcalPlugHandler','HcalPlug')
- seq.add(act)
-
- seq = DDG4.SensitiveSequence(kernel,'Geant4SensDetActionSequence/MuonBarrel')
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleCalorimeterAction/MuonBarrelHandler','MuonBarrel')
- seq.add(act)
-
- seq = DDG4.SensitiveSequence(kernel,'Geant4SensDetActionSequence/MuonEndcap')
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleCalorimeterAction/MuonEndcapHandler','MuonEndcap')
- seq.add(act)
-
- seq = DDG4.SensitiveSequence(kernel,'Geant4SensDetActionSequence/LumiCal')
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleCalorimeterAction/LumiCalHandler','LumiCal')
- seq.add(act)
-
- seq = DDG4.SensitiveSequence(kernel,'Geant4SensDetActionSequence/BeamCal')
- act = DDG4.SensitiveAction(kernel,'Geant4SimpleCalorimeterAction/BeamCalHandler','BeamCal')
- seq.add(act)
-
- # Now build the physics list:
- phys = kernel.physicsList()
- phys.extends = 'FTFP_BERT'
- #phys.transportation = True
- phys.decays = True
- phys.enableUI()
-
- ph = DDG4.PhysicsList(kernel,'Geant4PhysicsList/Myphysics')
- ph.addParticleConstructor('G4BosonConstructor')
- ph.addParticleConstructor('G4LeptonConstructor')
- ph.addParticleProcess('e[+-]','G4eMultipleScattering',-1,1,1)
- ph.addPhysicsConstructor('G4OpticalPhysics')
- ph.enableUI()
- phys.add(ph)
-
- phys.dump()
-
- kernel.configure()
- kernel.initialize()
- kernel.run()
- kernel.terminate()
-
-if __name__ == "__main__":
- run()
-
-\end{code}
-
-
-%=============================================================================
-\newpage
-\begin{thebibliography}{9}
-\input{DD4hep-bibliography.tex}
-\bibitem{bib:DDSegmentations} C.Grefe et al.,
- "The DDSegmentation package",
- Non existing documentation to be written.
-\end{thebibliography}
-%=============================================================================
-\end{document}
--
GitLab