diff --git a/doc/DD4hepManual.pdf b/doc/DD4hepManual.pdf
index 46004f1b06f0f0b88f0505a2e119f7d49752d90d..7d5654c951273cc81f2cc0c7712fa8467f94b652 100644
Binary files a/doc/DD4hepManual.pdf and b/doc/DD4hepManual.pdf differ
diff --git a/doc/DD4hep_Diagrams.pdf b/doc/DD4hep_Diagrams.pdf
index f9a3776970ee8c4c08a6e38dfd88e001f0c7960b..481f7b8f5b5112856756e182ee552520c00f028c 100644
Binary files a/doc/DD4hep_Diagrams.pdf and b/doc/DD4hep_Diagrams.pdf differ
diff --git a/doc/DDAlignManual.pdf b/doc/DDAlignManual.pdf
new file mode 100644
index 0000000000000000000000000000000000000000..4ce768c98f5561218d6eafe6e8273de466324fbf
Binary files /dev/null and b/doc/DDAlignManual.pdf differ
diff --git a/doc/DDG4Manual.pdf b/doc/DDG4Manual.pdf
index 4c7b828e2215c14a5ef40cf9d339778c5b2cd426..48e7b2e76fa04fea785a84bc8d12a4f01f859d6d 100644
Binary files a/doc/DDG4Manual.pdf and b/doc/DDG4Manual.pdf differ
diff --git a/doc/LaTex/DD4hep-setup.tex b/doc/LaTex/DD4hep-setup.tex
index 2f2380b149c679ba933f671f585e2b8d14918748..1408e70a0c789b24bc473ac97673190a2ab4c94e 100644
--- a/doc/LaTex/DD4hep-setup.tex
+++ b/doc/LaTex/DD4hep-setup.tex
@@ -7,6 +7,7 @@
\usepackage{lineno}
\usepackage{fancyhdr}
%
+\usepackage{amsmath}
%
\oddsidemargin 0.1 in
\evensidemargin 0.1 in
@@ -39,11 +40,9 @@
%
\newcommand{\DDE}{{$\tt{DDEve}$\space}}
\newcommand{\DDhep}{{$\tt{DD4hep}$\space}}
-\newcommand{\DDH}{{$\tt{DD4hep}$\space}}
\newcommand{\DDG}{{\tt{DDG4}\space}}
\newcommand{\DDA}{{\tt{DDAlign}\space}}
-\newcommand{\DDR}{{\tt{DDRec}\space}}
-%%
+%
%
\newcommand{\docline}[2]{\vspace{0.1cm}{\bf{#1}} & \parbox{14.5cm}{#2}\\}
%
@@ -66,7 +65,7 @@
%
\newcommand{\detdesc}[2]
{
- \href{http://www.cern.ch/frankm/DD4hep/doc/#1}{#2}
+ \href{http://www.cern.ch/frankm/DD4hep/#1}{#2}
}
%
% === Command to insert http links to the ROOT geomtery package
@@ -75,6 +74,10 @@
{
\href{http://root.cern.ch/root/html/#1.html}{#2}
}
+\newcommand{\tgeoO}[3]
+{
+ \href{http://root.cern.ch/root/html/#1:#2}{#3}
+}
%
% === Compactify the item list =========================
%
@@ -83,7 +86,7 @@
%
% === Title page command ===============================
%
-\newcommand{\mytitle}[3]{
+\newcommand{\mytitle}[2]{
\begin{titlepage}
%
\pagestyle{empty}
@@ -103,13 +106,13 @@
{\Huge\bf{#2}}
\vspace{5cm}
-{#3}
-%M.Frank%\textsuperscript{1},
+M.Frank%\textsuperscript{1},
%F.Gaede\textsuperscript{2},
%C.Grefe\textsuperscript{1},
%P.Mato\textsuperscript{1}
+
%{\textsuperscript{1}
-%{CERN, 1211 Geneva 23, Switzerland}
+{CERN, 1211 Geneva 23, Switzerland}
%{\textsuperscript{2} Desy, 22607 Hamburg, Germany}
\end{center}
\end{titlepage}
diff --git a/doc/LaTex/DD4hepManual.tex b/doc/LaTex/DD4hepManual.tex
index 29505865ee6d0a9da1c9826497ea412f202a8b1a..62f388e414867d6e637d34a0a591997f29704d36 100644
--- a/doc/LaTex/DD4hepManual.tex
+++ b/doc/LaTex/DD4hepManual.tex
@@ -15,15 +15,6 @@ A Detector Description Toolkit\\
for High Energy Physics\\
\vspace{0.3cm}
Experiments
-}{
-M.Frank%\textsuperscript{1},
-%F.Gaede\textsuperscript{2},
-%C.Grefe\textsuperscript{1},
-%P.Mato\textsuperscript{1}
-
-%{\textsuperscript{1}
-{CERN, 1211 Geneva 23, Switzerland}
-%{\textsuperscript{2} Desy, 22607 Hamburg, Germany}
}
%
%
@@ -69,6 +60,11 @@ version & Date & Author \\[0.2cm] \hline
\pagenumbering{arabic}
\setcounter{page}{1}
\input{DD4hep-Overview.tex}
+
+\noindent
+The alignment support will be subject to a separate development line of the
+\DDhep toolkit, called \DDA and hence will be discussed in another
+manual~\cite{bib:DDAlign}.
%
\newpage
%=============================================================================
@@ -88,11 +84,12 @@ 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.
+to provide the specific detector information to software algorithms, which
+process data from particle collisions.
\noindent
In the following sections an overview is given over the various independent
-elements of DD4hep followed by the discussion of an example which leads to
+elements of \DDhep followed by the discussion of an example which leads to
the description of a detector when combining these elements.
This includes a discussion of the features of the \DDhep detector description
and of its structure.
@@ -126,8 +123,8 @@ to ROOT's TGeom classes.
\noindent
Supported platforms for DD4hep are the CERN Linux operating systems:
\begin{itemize}
-\item \tw{Scientic Linux CERN 6}
-\item \tw{Scientic Linux CERN 7} - once approved.
+\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.
@@ -137,15 +134,18 @@ be actively supported by users who submit the necessary patches.
\label{sec:dd4hep-user-manual-prerequisites}
%=============================================================================
\noindent
-DD4hep depends on a number of ‘external’ packages.
+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 \tw{ROOT} (version 5.34 or higher) installations.~\footnote{Please
+not, that due to the removal of the Reflex plugin mechanism from ROOT 6,
+version 6 of ROOT is currently not supported. This deficiency will be waved
+in the future.}
\item If the \tw{Xerces-C} is used to parse compact descriptions and
installation of {Xerces-C} will be required.
-\item To build \DDG it is useful to have an installation of the Boost
+\item To build \DDG it is mandatory to have an installation of the Boost
header files.
\item To build and run the simulation examples \tw{Geant4} will be required.
\end{itemize}
@@ -316,29 +316,35 @@ 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;
+template <typename T> class Handle {
+public:
+ // Type definitions and class specific abbreviations and forward declarations
+ typedef T Implementation;
+ typedef Handle<Implementation> handle_t;
+public:
+ // Single and only data member: pointer to the underlying object
+ T* m_element;
+
+public:
+ Handle() : m_element(0) { }
+ Handle(T* e) : m_element(e) { }
+ Handle(const Handle<T>& e) : m_element(e.m_element) { }
+ template<typename Q> Handle(Q* e)
+ : m_element((T*)e) { verifyObject(); }
+ template<typename Q> Handle(const Handle<Q>& e)
+ : m_element((T*)e.m_element) { verifyObject(); }
+ Handle<T>& operator=(const Handle<T>& e) { m_element=e.m_element; return *this;}
+ bool isValid() const { return 0 != m_element; }
+ bool operator!() const { return 0 == m_element; }
+ void clear() { m_element = 0; }
+ T* operator->() const { return m_element; }
+ operator T& () const { return *m_element; }
+ T& operator*() const { return *m_element; }
+ T* ptr() const { return m_element; }
+ template <typename Q> Q* _ptr() const { return (Q*)m_element; }
+ template <typename Q> Q* data() const { return (Q*)m_element; }
+ template <typename Q> Q& object() const { return *(Q*)m_element; }
+ const char* name() const;
};
\end{code}
@@ -1166,6 +1172,75 @@ have constructors as shown here for the UnionSolid:
UnionSolid(const Solid& shape1, const Solid& shape2, const Transform3D& pos);
\end{code}
+\paragraph{Shape factories} Sometimes it is useful to create shapes in an "abstract" way
+e.g. to define areas in the detector. To create such shapes a factory method was implemented,
+which allows to create a valid shape handle given a valid XML element providing the
+required attributes. The factory methods are invoked using from XML elements of the following form:
+\begin{unnumberedcode}
+ <some_element type="shape-type" .... args ....>
+\end{unnumberedcode}
+The shape is then constructed using the XML component object:
+\begin{unnumberedcode}
+#include "DD4hep/DetFactoryHelper.h"
+
+ xml_h e = <shape-element>;
+ Box box = xml_comp_t(e).createShape();
+ if ( !box.isValid() ) { ...handle error ... }
+\end{unnumberedcode}
+The required arguments for the various shapes are then:
+\begin{itemize}
+\item For a Box:
+\vspace{-0.2cm}
+\begin{unnumberedcode}
+ <some_element type="Box" x="x-value" y="y-value" z="z-value"/>
+\end{unnumberedcode}
+fulfiling a constructor of the type: $Box(dim.dx(),~dim.dy(),~dim.dz())$.
+
+\item For a Polycone:
+\vspace{-0.2cm}
+\begin{unnumberedcode}
+ <some_element type="Polycone" start="start-phi-value" deltaphi="delta-phi-value">
+ <zplane z="z-value" rmin="rmin-value" rmax="rmax-value"/>
+ <zplane z="z-value" rmin="rmin-value" rmax="rmax-value"/>
+ .... any number of Z-planes ....
+ <zplane z="z-value" rmin="rmin-value" rmax="rmax-value"/>
+ </some_element>
+\end{unnumberedcode}
+
+\item For a ConeSegment the following constructor must be fulfilled:\\
+ $ ConeSegment(e.rmin(0.0),~e.rmax(),~e.z(0.0),~e.startphi(0.0),~e.deltaphi(2*M\_PI))$,\\
+where the above default values for the XML attributes $rmin, z, startphi$ and
+$deltaphi$ are used if not explicitly stated in the XML element $e$.
+
+\item For a Tube the constructor is:\\
+ $ Tube(e.rmin(0.0),~e.rmax(),~e.z(0.0),~e.startphi(0.0),~e.deltaphi(2*M\_PI))$.
+
+\item For a Cone the constructor is:\\
+ $double rmi1 = e.rmin1(0.0), rma1 = e.rmax1();$\\
+ $ Cone(e.z(0.0),~rmi1,rma1,~e.rmin2(rmi1),~e.rmax2(rma1))$.
+
+\item For a Trap the constructor is:\\
+ if $dz$ is specified: $ Trap(e.dz(),~e.dy(),~e.dx(),_toDouble(_Unicode(pLTX)))$
+ Otherwise: \\
+ $ Trap(e.z(0.0),~e.theta(),~e.phi(0),~e.y1(),~e.x1(),~e.x2(),~e.alpha(),
+ e.y2(),~e.x3(),~e.x4(),~e.alpha2())$.
+
+\item For a Trapezoid the constructor is:\\
+ $ Trapezoid(e.x1(),~e.x2(),~e.y1(),~e.y2(),~e.z(0.0))$.
+
+\item For a Torus the constructor is:\\
+ $ Torus(e.r(),~e.rmin(),~e.rmax(),~e.phi(M\_PI),~e.deltaphi(2.*M\_PI))$.
+
+\item For a Sphere the constructor is:\\
+ $ Sphere(e.rmin(),~e.rmax(),~e.deltatheta(M\_PI),~e.phi(0e0),e.deltaphi(2.*M\_PI))$.
+
+\item For a Paraboloid the constructor is:\\
+ $ Paraboloid(e.rmin(0.0),~e.rmax(),~e.dz())$.
+
+\item For a PolyhedraRegular the constructor is:\\
+ $ PolyhedraRegular(e.numsides(),~e.rmin(),~e.rmax(),~e.dz())$.
+
+\end{itemize}
\newpage
%=============================================================================
@@ -1496,6 +1571,162 @@ toolkit, but an independent package call
\tw{DDSegmentation}~\cite{bib:DDSegmentations}. Though the usage is an
integral part of DD4hep.
+\subsubsection{Volume Manager}
+%=============================================================================
+\noindent
+The \tw{VolumeManager} is a tool to seek a lookup table of placements of
+sensitive volumes and their corresponding unique volume identifier, the
+\tw{cellID}. The volume manager analyzes - once the geometry is closed -
+the hierarchical tree and stores the various placements in the hierarchy
+with respect to their identifiers. In other words the the tree is
+reused volumes shown e.g. in Figure~\ref{fig:dd4hep-hierarchies} is
+degenerated according to the full pathes of the various volumes. This
+use case is very common to reconstruction and analysis applications
+whenever a given raw-data (aka "hit") element must be related to its
+geometrical location.
+
+\noindent
+Figure~\ref{fig:dd4hep-user-manual-volmgr} shows the design diagram of this component:
+\begin{figure}[h]
+ \begin{center}
+ \includegraphics[width=170mm] {DD4hep-volmgr.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{Static Electric and Magnetic Fields}
+\label{sec:dd4hep-manual-static-fields}
+
+\noindent
+The generic field is described by a structure of any field type (electric or magnetic)
+with field components in Cartesian coordinates.
+The overlay field is the sum of several magnetic of electric field components
+and the resulting field vectors are computed by the vector addition
+of the individual components. The available components are described in the following.
+If necessary new field implementations may be added at any time: they are
+instantiated when necessary by the factory mechanism.
+Fields are described in the compact model within the {\tt{<fields>}} tags the
+following examople shows:
+\begin{code}
+ <fields>
+ <field name="MyMagnet" type="solenoid" .... />
+ </fields>
+\end{code}
+The actual components are defined one by one within the {\tt{<field>}} tags.
+
+\paragraph{Constant Electric or Magnetic Fields} are defined as follows:
+\begin{code}
+ <field name="MyMagnet" type="ConstantField" field="electric">
+ <strength x="x-val" y="y-val" z="z-val"/>
+ </field>
+\end{code}
+The {\tw{field}} attribute accepts take the values {\tw{[electric,magnetic]}}
+depending on it's nature.
+
+\paragraph{Magnetic Dipoles} are defined as follows:
+\begin{code}
+ <field name="MyMagnet" type="DipoleMagnet"
+ rmax="50*cm"
+ zmin="0*cm"
+ zmax="50*cm">
+ <dipole_coeff>1.0*tesla</dipole_coeff>
+ <dipole_coeff>0.1*tesla/pow(cm,1)</dipole_coeff>
+ <dipole_coeff>0.01*tesla/pow(cm,2)</dipole_coeff>
+ </field>
+\end{code}
+
+\paragraph{Magnetic Multipole Fields} are developed according to their
+approximation using the multipole coefficients.
+The dipole is assumed to be horizontal as it is used for bending beams in large colliders
+ie. the dipole field lines are vertical.
+
+The different momenta are given by: $ B_y + i B_x $\footnote{
+See for detailed documentation about multipoles:\\
+http://cas.web.cern.ch/cas/Belgium-2009/Lectures/PDFs/Wolski-1.pdf \\
+http://cas.web.cern.ch/cas/Bulgaria-2010/Talks-web/Brandt-1-web.pdf \\
+https://en.wikipedia.org/wiki/Multipole\_magnet
+}, where:
+\begin{align*}
+ & & B_y + i B_x &=& C_n (x + iy)^{n-1} \\
+B_{sum} &=& B_y + i B_x &=& \Sigma_{n=1..m} (b_n + ia_n) (x + iy)^{n-1}\\
+\end{align*}
+With $C_n$ being the complex multipole coefficients,
+$b_n$ the "normal multipole coefficients" and $a_n$ the "skew multipole coefficients".
+The maximal momentum used is the octopole momentum. The lower four momenta are used
+to describe the magnetic field:
+\begin{itemize}\itemcompact
+\item Dipole (n=1):
+ \begin{align*}
+ B_y &=& b_1 \\
+ B_x &=& a_1 \\
+ B_z &=& constant \\
+ \end{align*}
+\item Quadrupole (n=2):
+ \begin{align*}
+ B_y &=& b_2 x - a_2 y \\
+ B_x &=& b_2 y + a_2 x \\
+ \end{align*}
+\item Sextupole (n=3):
+ \begin{align*}
+ B_y + i B_x &=& (b_3 +ia_3) (x^2 + 2ixy - y^2) \\
+ B_y &=& b_3 x^2 - b_3 y^2 - 2 a_3 xy \\
+ B_x &=& a_3 x^2 - a_3 y^2 + 2 b_3 xy \\
+ \end{align*}
+
+\item Octopole (n=4):
+ \begin{align*}
+ B_y + i B_x &=& (b_4 +ia_4) (x^3 + 3ix^2y - 3xy^2 -iy^3) \\
+ B_y &=& b_4 x^3 - 3 b_4 x y^2 - 3 a_4 x^2 y + a_4 y^3 \\
+ B_x &=& 3 b_4 x^2 y + b_4 y^3 + a_4 x^3 - 3 a_4 x y^2 \\
+ \end{align*}
+\end{itemize}
+The defined field components only apply within the shape 'volume'.
+If 'volume' is an invalid shape (ie. not defined), then the field
+components are valied throughout the 'universe'.
+
+\noindent
+The magnetic multipoles are defined as follows:
+\begin{code}
+ <field name="MyMagnet" type="MultipoleMagnet">
+ <position x="0" y="0" z="0"/>
+ <rotation x="pi" y="0" z="0"/>
+ <shape type="shape-constructor-type" .... args .... >
+ <coeffizient coefficient="coeff(n=1)" skew="skew(n=1)"/>
+ .... maximum of 4 coefficients ....
+ <coeffizient coefficient="coeff(n=4)" skew="skew(n=4)"/>
+ </field>
+\end{code}
+The shape defines the geometrical coverage of the multipole
+field in the origin (See section~\ref{dd4hep-basic-shapes} for details).
+This shape may then be transformed to
+the required location in the detector area using the position
+and the rotation elements, which define this transformation.
+
\newpage
%=============================================================================
\subsection{Detector Constructors}
@@ -1709,54 +1940,9 @@ DECLARE_DETELEMENT(CylindricalEndcapCalorimeter,create_detector);
at construction time.}
\end{tabular}
+\newpage
%=============================================================================
-\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}
+\subsection{Tools and Utilities}
%=============================================================================
\subsubsection{Geometry Visualization}
@@ -1790,10 +1976,21 @@ 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!
+ DD4hepGeometryDisplay -opt [-opt]
+ -compact <file> Specify the compact geometry file
+ [REQUIRED] At least one compact geo file is required!
+ -build_type <number/string> Specify the build type
+ [OPTIONAL] MUST come immediately after the -compact input.
+ Default for each file is: BUILD_DEFAULT [=1]
+ Allowed values: BUILD_SIMU [=1], BUILD_RECO [=2] or BUILD_DISPLAY [=3]
+ -destroy [OPTIONAL] Force destruction of the LCDD instance
+ before exiting the application
+ -volmgr [OPTIONAL] Load and populate phys.volume manager to
+ check the volume ids for duplicates etc.
+ -print <number/string> Specify output level. Default: INFO(=3)
+ [OPTIONAL] Allowed values: VERBOSE(=1), DEBUG(=2),
+ INFO(=3), WARNING(=4), ERROR(=5), FATAL(=6)
+ The lower the level, the more printout...
-load_only [OPTIONAL] Dry-run to only load geometry without
starting the dispay.
\end{code}
@@ -1828,10 +2025,138 @@ Both conversions are supported in \DDhep with the geoConverter application:
[Only valid for -compact2vis]
\end{code}
+%=============================================================================
+\subsubsection{Overlap checking}
+\label{sec:dd4hep-manual-overlap-checking}
+%=============================================================================
+\noindent
+Overlap checks are an important tool to verify the consistency of the
+implemented geometrical design. As in the real world, where overlaps are
+impossible, also simulated geometries may not have overlaps. In simulation
+overlaps tend to create particle reflections possibly leading to infinite
+loops.
+\begin{code}
+ python <install>/DD4hep/bin/checkOverlaps.py --help
+ Usage: checkOverlaps.py [options]
+
+ Check TGeo geometries for overlaps.
+
+ Options:
+ -h, --help show this help message and exit
+ -c <FILE>, --compact=<FILE> Define LCCDD style compact xml input
+ -p <boolean>, --print=<boolean> Print overlap information to standard output
+ (default:True)
+ -q, --quiet Do not print (disable --print)
+ -t <double number>, --tolerance=<double number>
+ Overlap checking tolerance. Unit is in [mm].
+ (default:0.1 mm)
+ -o <string>, --option=<string> Overlap checking option ('' or 's')
+\end{code}
+
+%=============================================================================
+\subsubsection{Geometry checking}
+\label{sec:dd4hep-manual-geometry-checking}
+%=============================================================================
+\noindent
+Perform extensive geometry checks. For details and up to date information
+please refer to the ROOT documentation of the class {\tt{TGeoManager}}:
+\begin{itemize}\itemcompact
+\item Member function {\tgeoO{TGeoManager.html}{TGeoManager:CheckGeometry}{TGeoManager::CheckGeometry}} and
+\item Member function {\tgeoO{TGeoManager.html}{TGeoManager:CheckGeometryFull}{TGeoManager::CheckGeometryFull}}
+\end{itemize}
+
+\begin{code}
+ python <install>DD4hep/bin/checkGeometry.py --help
+ Usage: checkGeometry.py [options]
+
+ TGeo Geometry checking.
+
+ Options:
+ -h, --help show this help message and exit
+ -c <FILE>, --compact=<FILE> Define LCCDD style compact xml input
+ -f <boolean>, --full=<boolean> Full geometry checking
+ -n <integer>, --ntracks=<integer> Number of tracks [requires 'full']
+ -x <double>, --vx=<double> X-position of track origine vertex [requires 'full']
+ -y <double>, --vy=<double> Y-position of track origine vertex [requires 'full']
+ -z <double>, --vz=<double> Z-position of track origine vertex [requires 'full']
+ -o <string>, --option=<string> Geometry checking option default:ob
+\end{code}
+
+The full geometry check performs the \tgeoO{TGeoManager.html}{TGeoManager:CheckGeometryFull}
+{following actions}:
+\begin{itemize}\itemcompact
+\item if option contains 'o': Optional overlap checkings (by sampling and by mesh).
+\item if option contains 'b': Optional boundary crossing check + timing per volume.
+
+\item{\bf{STAGE 1:}} extensive overlap checking by sampling per volume. Stdout need to be
+ checked by user to get report, then TGeoVolume::CheckOverlaps(0.01, "s") can
+ be called for the suspicious volumes.
+\item{\bf{STAGE 2:}} normal overlap checking using the shapes mesh - fills the list of
+ overlaps.
+\item{\bf{STAGE 3:}} shooting NTRACKS rays from vertex (vx,vy,vz)
+ and counting the total number of
+ crossings per volume (rays propagated from boundary to boundary until
+ geometry exit). Timing computed and results stored in a histogram.
+\item{\bf{STAGE 4:}} shooting 1 mil. random rays inside EACH volume and calling
+ FindNextBoundary() + Safety() for each call. The timing is normalized by the
+ number of crossings computed at stage 2 and presented as percentage.
+ One can get a picture on which are the most "burned" volumes during
+ transportation from geometry point of view. Another plot of the timing per
+ volume vs. number of daughters is produced.
+\end{itemize}
+
+%=============================================================================
+\subsubsection{Directional Material Scans}
+\label{sec:dd4hep-manual-directional-material-scans}
+%=============================================================================
+\noindent
+Print the materials on a straight line between the two given points:
+\begin{code}
+materialScan
+ usage: print_materials compact.xml x0 y0 z0 x1 y1 z1
+ -> prints the materials on a straight line between the two given points ( unit is cm)
+\end{code}
+$materialScan$ uses the python bindings provided by Geant4 and may be not
+always availible. Alternatively the command $print\_materials$ may be used,
+which does not use the python binding, but produces less pretty output.
+
+%=============================================================================
+\subsubsection{Plugin Test Program}
+\label{sec:dd4hep-manual-plugin-test}
+%=============================================================================
+\noindent
+The plugin tester loads a given geometry and the executes a plugin
+defined at the command line. The main purpose of this program is to quickly
+invoke new detector plugins while developing. The arguments for this
+program are:
+\begin{code}
+ geoPluginRun -opt [-opt]
+
+ -plugin <name> [REQUIRED] Plugin to be executed and applied.
+ -input <file> [OPTIONAL] Specify geometry input file.
+ -build_type <number/string> Specify the build type
+ [OPTIONAL] MUST come immediately after the -compact input.
+ Default for each file is: BUILD_DEFAULT [=1]
+ Allowed values: BUILD_SIMU [=1], BUILD_RECO [=2] or BUILD_DISPLAY [=3]
+ -destroy [OPTIONAL] Force destruction of the LCDD instance
+ before exiting the application
+ -volmgr [OPTIONAL] Load and populate phys.volume manager to
+ check the volume ids for duplicates etc.
+ -print <number/string> Specify output level. Default: INFO(=3)
+ [OPTIONAL] Allowed values: VERBOSE(=1), DEBUG(=2),
+ INFO(=3), WARNING(=4), ERROR(=5), FATAL(=6)
+ The lower the level, the more printout...
+
+
+\end{code}
+
%=============================================================================
\newpage
\begin{thebibliography}{9}
\input{DD4hep-bibliography.tex}
+\bibitem{bib:DDAlign} M.Frank,
+ "DDAlign User Manual:
+ Alignment Support for the DD4hep Geometry Description Toolkit".
\bibitem{bib:DDSegmentations} C.Grefe et al.,
"The DDSegmentation package",
Non existing documentation to be written.
diff --git a/doc/LaTex/DDAlignManual.tex b/doc/LaTex/DDAlignManual.tex
index 4095631b2bf0dde40767e4397e8040472c6890e2..2e6421191a5bb60a27d13436a2e564a79476b309 100644
--- a/doc/LaTex/DDAlignManual.tex
+++ b/doc/LaTex/DDAlignManual.tex
@@ -17,17 +17,7 @@ DD4hep Geometry Description \\
\vspace{0.5cm}
Toolkit
\vspace{2cm}
-}{
-M.Frank%\textsuperscript{1},
-%F.Gaede\textsuperscript{2},
-%C.Grefe\textsuperscript{1},
-%P.Mato\textsuperscript{1}
-
-%{\textsuperscript{1}
-{CERN, 1211 Geneva 23, Switzerland}
-%{\textsuperscript{2} Desy, 22607 Hamburg, Germany}
-}
-{DDAlign User Manual}
+}{DDAlign User Manual}
%
%
%== Abstract ===============================================================
diff --git a/doc/LaTex/DDConditionsManual.tex b/doc/LaTex/DDConditionsManual.tex
index 7ff618bfe996d7dedbc127ddd1f83f51199b2655..103da1d9a72004fd3e5c9978cccae7ce306d29df 100644
--- a/doc/LaTex/DDConditionsManual.tex
+++ b/doc/LaTex/DDConditionsManual.tex
@@ -16,17 +16,7 @@ DD4hep Geometry Description \\
\vspace{0.5cm}
Toolkit
\vspace{2cm}
-}{
-M.Frank%\textsuperscript{1},
-%F.Gaede\textsuperscript{2},
-%C.Grefe\textsuperscript{1},
-%P.Mato\textsuperscript{1}
-
-%{\textsuperscript{1}
-{CERN, 1211 Geneva 23, Switzerland}
-%{\textsuperscript{2} Desy, 22607 Hamburg, Germany}
-}
-{DDAlign User Manual}
+}{DDAlign User Manual}
%
%
%== Abstract ===============================================================
diff --git a/doc/LaTex/DDEveManual.tex b/doc/LaTex/DDEveManual.tex
index 09b87f2595723feedfcfbfd572b4aef01adcd745..034ac70f2486fa508ed10f12fb13cbb001c8b01b 100644
--- a/doc/LaTex/DDEveManual.tex
+++ b/doc/LaTex/DDEveManual.tex
@@ -15,17 +15,7 @@ An Event Display for \\
DD4hep Geometries \\
\vspace{2.5cm}
-- DRAFT -- \\
-}{
-M.Frank%\textsuperscript{1},
-%F.Gaede\textsuperscript{2},
-%C.Grefe\textsuperscript{1},
-%P.Mato\textsuperscript{1}
-
-%{\textsuperscript{1}
-{CERN, 1211 Geneva 23, Switzerland}
-%{\textsuperscript{2} Desy, 22607 Hamburg, Germany}
-}
-{DDEve User Manual}
+}{DDEve User Manual}
%
%
%== Abstract ===============================================================
diff --git a/doc/LaTex/DDG4-Geant4Kernel.png b/doc/LaTex/DDG4-Geant4Kernel.png
index 32adb857355575b6ee99f145dc82a0425c4115e9..00b0d0c76cd20534da9c4508e0bf8eb684fae257 100644
Binary files a/doc/LaTex/DDG4-Geant4Kernel.png and b/doc/LaTex/DDG4-Geant4Kernel.png differ
diff --git a/doc/LaTex/DDG4-SensitiveFilterClasses.png b/doc/LaTex/DDG4-SensitiveFilterClasses.png
new file mode 100644
index 0000000000000000000000000000000000000000..e29ac30312903f4896573b63dff774d57052a440
Binary files /dev/null and b/doc/LaTex/DDG4-SensitiveFilterClasses.png differ
diff --git a/doc/LaTex/DDG4-TrackingActionCalls.png b/doc/LaTex/DDG4-TrackingActionCalls.png
new file mode 100644
index 0000000000000000000000000000000000000000..b06fdf002dc7e2adf6b69c02b85c34c9c3c55944
Binary files /dev/null and b/doc/LaTex/DDG4-TrackingActionCalls.png differ
diff --git a/doc/LaTex/DDG4Manual.tex b/doc/LaTex/DDG4Manual.tex
index b1e28334fdd79e97591f25b35164b14c76df6c15..4e0d03bd9de676ad2a3db170162aa43b80dcb525 100644
--- a/doc/LaTex/DDG4Manual.tex
+++ b/doc/LaTex/DDG4Manual.tex
@@ -219,7 +219,7 @@ 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}}
+\subsection{The Application Core Object: Geant4Kernel}
\label{sec:ddg4-user-manual-implementation-geant4kernel}
%=============================================================================
@@ -228,17 +228,30 @@ 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.
+correct signature. Each of these action sequences is connected to an instance
+of a geant4 provided callback structure as it is shown in
+Figure~\ref{fig:ddg4-g4runmanager-anatomy}.
\begin{figure}[h]
\begin{center}
- \includegraphics[height=80mm] {DDG4-Geant4Kernel.png}
- \caption{The sensitive detector design.}
+ \includegraphics[height=65mm] {DDG4-Geant4Kernel.png}
+ \caption{The main application object gives access to all sequencing actions
+ in a \DDG4 application. Sequence actions are only container of user actions
+ calling one user action after the other. Optionally single callbacks may
+ be registered to a user action.}
\label{fig:ddg4-geant4-kernel}
\end{center}
\end{figure}
%=============================================================================
-\subsection{The Base Class of DDG4 Actions: \tts{Geant4Action}}
+\subsection{Action Sequences}
+\label{sec:ddg4-user-manual-implementation-geant4action-sequences}
+%=============================================================================
+
+\noindent
+As shown in
+
+%=============================================================================
+\subsection{The Base Class of DDG4 Actions: Geant4Action}
\label{sec:ddg4-user-manual-implementation-geant4action-base}
%=============================================================================
@@ -307,6 +320,31 @@ of any base or sub-class.
\label{sec:ddg4-user-manual-implementation-geant4action-sequences}
%=============================================================================
+\noindent
+All Geant4 user hooks are realized as action sequences. As shown in
+Figure~\ref{fig:ddg4-geant4-kernel} these sequences are accessible to the user,
+who may attach specialized actions to the different action sequences. This
+allows a flexible handing of specialized user actions e.g. to dynamically
+add monitoring actions filling histograms or to implement alternative hit
+creation mechanism in a sensitive detector for detailed detector studies.
+Figure~\ref{fig:ddg4-implementation-sequence-calls} shows the schematic
+call structure of an example {\tt{Geant4TrackingActionSequence}}:\\
+\begin{figure}[h]
+ \begin{center}
+ \includegraphics[width=150mm] {DDG4-TrackingActionCalls.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-sequence-calls}
+ \end{center}
+\end{figure}
+
+\noindent
+Geant4 calls the function from the virtual interface (\tw{G4UserTrackingAction}),
+which is realised by the \tw{Geant4UserTrackingAction} with the single purpose to
+propagate the call to the action sequence, which then calls all registered clients
+of type \tw{Geant4TrackingAction}.
+
\noindent
The main action sequences have a fixed name. These are
\begin{itemize}
@@ -402,6 +440,8 @@ template <typename Q, typename T> void callAtBegin(Q* p, void (T::*f)(const G4Tr
/// Register Post-track action callback
template <typename Q, typename T> void callAtEnd(Q* p, void (T::*f)(const G4Track*));
\end{unnumberedcode}
+Figure~\ref{fig:ddg4-implementation-tracking-action} show as an example
+the design (class-diagram) of the \tts{Geant4TrackingAction}.
\item The \bold{SteppingAction} attached to the \tts{G4UserSteppingAction}, implemented
@@ -447,20 +487,7 @@ template <typename T> void callAtPrepare(T* p, void (T::*f)());
\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}
+the member. The design of all sequences is very similar.
%=============================================================================
\subsection{Sensitive Detectors}
@@ -470,10 +497,24 @@ the design of the \tts{Geant4TrackingAction}.
\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
+is realized by using a base class \tts{G4VSensitiveDetector}.
+The mandate of a sensitive detector is the construction of hit objects
+using information from steps along a particle track.
+The \tts{G4VSensitiveDetector} 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.
+\begin{figure}[t]
+ \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}
+
\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
@@ -522,12 +563,124 @@ to receive callbacks using the methods:
/// Register clear callback
template <typename T> void callAtClear(T* p, void (T::*f)(G4HCofThisEvent*));
\end{unnumberedcode}
+Please refer to the Geant4 Applications manual from the Geant4 web page for
+further details about the concept of sensitive detectors.
+
+%=============================================================================
+\subsubsection{Helpers of Sensitive Detectors: The Geant4VolumeManager}
+\label{sec:ddg4-user-manual-geant4volumemanager}%=============================================================================
+
+\noindent
+Sooner or later, when a hit is created in a sensitive placed volume, the
+hit must be associated with this volume. For this purpose \DDhep provides
+the concept of the \tw{VolumeManager}, which identifies placed volumes uniquely
+by a 64-bit identifier, the $CellID$. This mechanism allows to quickly
+retrieve a given volume given the hit data containing the $CellID$.
+The $CellID$ is a very compressed representation for any element in the
+hierarchy of placed volumes to the sensitive volume in question.
+
+\noindent
+During the simulation the reverse mechanism must be applied: Geant4 provides
+the hierarchy of \tw{G4PhysicalVolumes} to the hit location and the local coordinates
+of the hit within the sensitive volume. Hence to determine the volume identifier
+is essential to store hits so that they can be later accessed and processed efficiently.
+This mechanism is provided by the \tw{Geant4VolumeManager}. Clients typically do not
+interact with this object, any access necessary is provided by the
+\tw{Geant4Sensitive} action:
+\begin{unnumberedcode}
+ /// Method for generating hit(s) using the information of G4Step object.
+ bool MySensitiveAction:process(G4Step* step,G4TouchableHistory* /*hist*/ ) {
+ ...
+ Hit* hit = new Hit();
+ // *** Retrieve the cellID ***
+ hit->cellID = cellID(step);
+ ...
+ }
+\end{unnumberedcode}
+The call is realized using a member function provided by the
+\tw{Geant4Sensitive} action:
+\begin{unnumberedcode}
+ /// Returns the cellID of the sensitive volume corresponding to the step
+ /** The CellID is the VolumeID + the local coordinates of the sensitive area.
+ * Calculated by combining the VolIDS of the complete geometry path (Geant4TouchableHistory)
+ * from the current sensitive volume to the world volume
+ */
+ long long int cellID(G4Step* step);
+\end{unnumberedcode}
+
+\noindent
+\bold{Note:}\\
+The \tw{Geant4VolumeManager} functionality is not for free! It requires that
+
+
+\noindent
+-- match geant4 volume with TGeo volume
+
+%=============================================================================
+\subsubsection{DDG4 Intrinsic Sensitive Detectors}
+%=============================================================================
+\noindent
+Currently there are two generic sensitive detectors implemented in DDG4:
+\begin{itemize}\itemcompact
+\item The \tw{Geant4TrackerAction}, which may be used to handle tracking devices.
+ This sensitive detector produces one hit for every energy deposition of Geant4
+ i.e. for every callback to
+\begin{unnumberedcode}
+ /// Method for generating hit(s) using the information of G4Step object.
+ virtual bool process(G4Step* step, G4TouchableHistory* history);
+\end{unnumberedcode}
+ See the implementation file
+ \detdesc{html/_geant4_s_d_actions_8cpp_source.html}{DDG4/plugins/Geant4SDAction.cpp}
+ for details. The produced hits are of type
+ \detdesc{html/_geant4_data_8h_source.html}{Geant4Tracker::Hit}.
+
+\item The \tw{Geant4CalorimeterAction}, which may be used to handle
+ generic calorimeter like devices.
+ This sensitive detector produces at most one hit for every cell in the calorimeter.
+ If several tracks contribute to the energy deposit of this cell, the contributions
+ are added up.
+ See the implementation file
+ \detdesc{html/_geant4_s_d_actions_8cpp_source.html}{DDG4/plugins/Geant4SDAction.cpp}
+ for details. The produced hits are of type
+ \detdesc{html/_geant4_data_8h_source.html}{Geant4Calorimeter::Hit}.
+ propagate the MC truth information with respect to each track kept in the
+ particle record.
+\end{itemize}
+
+\noindent
+Both sensitive detectors use the \tw{Geant4VolumeManager} discussed in
+section~\ref{sec:ddg4-user-manual-geant4volumemanager} to identify the sensitive elements.
+
+\noindent
+\bold{PLEASE NOTE:}\\
+The above palette of generic sensitive detectors only contains two very
+often used implementations. We hope, that this palette over time grows from
+external contributions of other generic sensitive detectors. We would be happy
+to extend this palette with other generic implementations. One example would
+be the handling of the simulation response for optical detectors like RICH-Cerenkov
+detectors.
%=============================================================================
\subsubsection{Sensitive Detector Filters}
\label{sec:ddg4-implementation-sensitive-detector-filters}
%=============================================================================
+\noindent
+The concept of filters allows to build more flexible sensitive detectors by
+restricting the hit processing of a given instance of a sensitive action.
+
+\begin{itemize}\itemcompact
+\item Examples would be to demand a given particle type before a sensitive action is
+invoked: a sensitive action dealing with optical photons (RICH detectors, etc),
+would e.g. not be interested in energy depositions of other particles.
+A filter object restricting the particle type to optical photons would
+be appropriate.
+\item Another example would be to implement a special action instance, which would
+be only called if the filter requires a minimum energy deposit.
+\end{itemize}
+There are plenty of possible applications, hence we would like
+to introduce this feature here.
+
\noindent
Filters are called by Geant4 before the
hit processing in the sensitive detectors start. The global filters
@@ -535,19 +688,44 @@ 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.
+\noindent
+Technically do \tw{Geant4Filter} objects inherit from the base class
+\tw{Geant4Filter} (see Figure~\ref{fig:ddg4-implementation-sensitive-detector-filters}.
+Any filter inherits from the common base class \tw{Geant4Filter}, then
+several specializations may be configured like filters to select/reject
+particles, to specify the minimal energy deposit to be processed etc.
+A sensitive detector is called if the filter callback with the signature
+returns a true result:
+\begin{unnumberedcode}
+ /// Filter action. Return true if hits should be processed
+ virtual bool operator()(const G4Step* step) const;
+\end{unnumberedcode}
+\begin{figure}[h]
+ \begin{center}
+ \includegraphics[height=65mm] {DDG4-SensitiveFilterClasses.png}
+ \caption{The sensitive detector filters design. The shown class
+ diagram is actually implemented.}
+ \label{fig:ddg4-implementation-sensitive-detector-filters}
+ \end{center}
+\end{figure}
+
\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
+Geant4 provides the base class \tts{G4VUserPhysicsList}, which allows users
+to implement customized physics according to the studies to be made.
+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.
+physics list. Instead of explicitly coding the physics list, \DDG foresees the
+usage of the plugin mechanism to instantiate the necessary calls to Geant4 in a
+sequence of actions:
\begin{itemize}
-\item The \bold{physics list} may be configured as a sequence of type
+\item The \bold{physics list} is realized as a sequence of actions 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}
@@ -584,15 +762,19 @@ physics list.
\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
+\item \detdesc{html/_geant4_particles_8cpp_source.html}{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},
+\item \detdesc{html/_geant4_processes_8cpp_source.html}{physics process constructors},
+ such as e.g. \tts{G4GammaConversion},
\tts{G4PhotoElectricEffect} or\\ \tts{G4ComptonScattering},
-\item \detdesc{}{physics constructors} combining particles and the corresponding
+\item \detdesc{html/_geant4_physics_constructors_8cpp_source.html}{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},
+\item \detdesc{html/_geant4_particles_8cpp_source.html}{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}
@@ -624,7 +806,7 @@ where \tts{My\_Very\_Own\_Physics\_Constructor} represents a sub-class of
%=============================================================================
\noindent
-The support of interactive in Geant4 is absolutely mandatory to debug detector
+The support of interactivity in Geant4 is mandatory to debug detector
setups in small steps. The Geant4 toolkit did provide for this reason
a machinery of UI commands.
\begin{figure}[h]
@@ -660,43 +842,45 @@ Idle> ls
Control for all named Geant4 actions
Sub-directories :
- /ddg4/EventAction/ Control hierarchy for Geant4 action:EventAction
+ /ddg4/RunInit/ Control hierarchy for Geant4 action:RunInit
/ddg4/RunAction/ Control hierarchy for Geant4 action:RunAction
- /ddg4/Gun/ Control hierarchy for Geant4 action:Gun
+ /ddg4/EventAction/ Control hierarchy for Geant4 action:EventAction
/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 :
+ /ddg4/LCIO1/ Control hierarchy for Geant4 action:LCIO1
+ /ddg4/Smear1/ Control hierarchy for Geant4 action:Smear1
+ /ddg4/PrimaryHandler/ Control hierarchy for Geant4 action:PrimaryHandler
+ /ddg4/TrackingAction/ Control hierarchy for Geant4 action:TrackingAction
+ /ddg4/SteppingAction/ Control hierarchy for Geant4 action:SteppingAction
+ /ddg4/ParticleHandler/ Control hierarchy for Geant4 action:ParticleHandler
+ /ddg4/UserParticleHandler/ Control hierarchy for Geant4 action:UserParticleHandler
+ ...
+Idle> ls Smear1
+Command directory path : /ddg4/Smear1/
+ ...
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
+ show * Show all properties of Geant4 component:Smear1
+ Control * Property item of type bool
+ Mask * Property item of type int
+ Name * Property item of type std::string
+ Offset * Property item of type ROOT::Math::LorentzVector<ROOT::Math::PxPyPzE4D<double> >
+ OutputLevel * Property item of type int
+ Sigma * Property item of type ROOT::Math::LorentzVector<ROOT::Math::PxPyPzE4D<double> >
+ name * Property item of type std::string
+Idle> Smear1/show
+PropertyManager: Property Control = True
+PropertyManager: Property Mask = 1
+PropertyManager: Property Name = 'Smear1'
+PropertyManager: Property Offset = ( -20 , -10 , -10 , 0 )
+PropertyManager: Property OutputLevel = 4
+PropertyManager: Property Sigma = ( 12 , 8 , 8 , 0 )
+PropertyManager: Property name = 'Smear1'
+
+Idle> Smear1/Offset (200*mm, -3*mm, 15*mm, 10*ns)
+Geant4UIMessenger: +++ Smear1> Setting property value Offset = (200*mm, -3*mm, 15*mm, 10*ns)
+ native:( 200 , -3 , 15 , 10 ).
+Idle> Smear1/show
...
-PropertyManager: Property pos_x = 1
-PropertyManager: Property pos_y = 1
-PropertyManager: Property pos_z = 1
+PropertyManager: Property Offset = ( 200 , -3 , 15 , 10 )
\end{unnumberedcode}
@@ -717,8 +901,8 @@ using
\item by creating a setup script using \tts{python} and
\tts{ROOT}'s reflection mechanism exposed by \tts{PyROOT}.
\end{itemize}
-The follwing subsection describe these different mechanism.
-
+The follwing subsection describe these different mechanism. An attempt was made
+to match the naming conventions of all approaches where possible.
%=============================================================================
\subsection{Setting up DDG4 using XML}
@@ -804,10 +988,11 @@ An example code snippet is shown below in Figure~\ref{fig:ddg4-setup-xml-physics
\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
+\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.
+\item To trigger a call to a \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
@@ -816,11 +1001,7 @@ To trigger a call to a
\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.
+\item \bold{physics constructors}, as shown in line 34-35, use the \tts{<physics>} section.
\end{itemize}
If only a predefined physics list is used, which probably already satisfies very many use cases,
all these section collapse to:
@@ -1420,6 +1601,155 @@ if __name__ == "__main__":
\end{code}
\newpage
+%=============================================================================
+\subsection{A Simple Example}
+\label{sec:ddg4-implementation-simple-example}
+%=============================================================================
+\noindent
+Bla-bal.
+
+\newpage
+%=============================================================================
+\section{Higher Level Components}
+\label{sec:ddg4-implementation-higher-level-components}
+%=============================================================================
+\noindent
+Layered components, which base on the general framework implement higher
+level functionality such as the handling of Monte-Carlo truth associations
+between simulated energy deposits and the corresponding particles or the
+generic handling of input to the simulation.
+
+\noindent
+To generalize such common behavior it is mandatory that the participating
+components collaborate and understand the data components the commonly access.
+The data model is shown in Figure~\ref{fig:ddg4-event-data-model}.
+\begin{figure}[t]
+ \begin{center}
+ \includegraphics[width=120mm] {DDG4_event_data_model.png}
+ \caption{The DDG4 event data model.}
+ \label{fig:ddg4-event-data-model}
+ \end{center}
+\end{figure}
+
+\noindent
+Please note, that this data model is by no means to be made persistent
+and used for physics user analysis. This model is optimized to support
+the simulation process and the necessary user actions to handle MC truth,
+to easily and relatively fast look up and modify parent-daughter
+relationships etc. This choice is based on the assumption, that the
+additional overhead to convert particles at the input/output
+stage is small compared to the actual resource consumption of Geant4
+to simulate the proper detector response.
+On the other hand this choice has numerous advantages:
+\begin{itemize}\itemcompact
+\item Accepting the fact to convert input records allows to adapt
+ DDG4 in a simple and flexible manner to any input format. Currently
+ supported is the input from raw {\tw{LCIO}} files, {\tw{StdHep}}
+ records using {\tw{LCIO}} and {\tw{ASCII}} files using the
+ {\tw{HEPEvt}} format.
+\item Similarly as for the input stage, also the output format
+ can be freely chosen by the clients.
+\item No assumptions was made concerning the structure to store
+ information from energy deposits. Any information extract produced
+ by the sensitive actions can be adapted provided at the output
+ stage the proper conversion mechanism is present. The sensitive
+ detectors provided by DDG4 are {\bf{optional only and by no means mandatory}}.
+ User defined classes may be provided at any time. Appropriate tools
+ to extract MC truth information is provided at the output stage.
+\item The modular approach of the action sequences described
+ in~\ref{sec:ddg4-user-manual-implementation-geant4action-sequences}
+ allows to easily extend the generation sequence to handle multiple
+ simultaneous interactions, event overlay or spillover response
+ very easily~\footnote{The handling of spillover is only possible
+ if during the digitization step the correct signal shape corresponding
+ to the shift of signal creation is taken into account.}
+\end{itemize}
+
+\noindent
+In section~\ref{sec:ddg4-implementation-input-handling} the generic mechanism
+of input data handling is described. \\
+In section~\ref{sec:ddg4-implementation-particle-handling} the MC truth
+handling is discussed. \\
+In section~\ref{sec:ddg4-implementation-output-handling} we describe the
+output mechanism.
+\newpage
+
+%=============================================================================
+\subsection{Input Data Handling}
+\label{sec:ddg4-implementation-input-handling}
+%=============================================================================
+\begin{figure}[t]
+ \begin{center}
+ \includegraphics[width=160mm] {DDG4_input_stage.png}
+ \caption{The generic handling of input sources to DDG4.}
+ \label{fig:ddg4-input-stage}
+ \end{center}
+\end{figure}
+
+\noindent
+Input handling has several stages and uses several modules:
+\begin{itemize}\itemcompact
+\item First the data structures \tw{Geant4PrimaryEvent},
+ \tw{Geant4PrimaryInteraction} and \tw{Geant4\-Primary}\-\tw{Map} are initialized
+ by the action \tw{Geant4GenerationActionInit}
+ and attached to the {\tw{Geant4Event}} structure.
+\item The initialization is then followed by any number of input modules.
+ Typically each input module add one interaction. Each interaction has a
+ unique identifier, which is propagated later to all particles. Hence all
+ primary particles can later be unambiguously be correlated to one of the
+ initial interactions.
+ Each instance of a \tw{Geant4InputAction} creates and fills a separate instance
+ of a \tw{Geant4PrimaryInteraction}.
+ In section~\ref{sec:ddg4-implementation-geant4inputaction} the functionality and
+ extensions are discussed in more detail.
+\item All individual primary interactions are then merged to only single record
+ using the \tw{Geant4}\-\tw{Interaction}\-\tw{Merger} component.
+ This components fills the \tw{Geant4PrimaryInteraction} registered to the
+ \tw{Geant4Event}, which serves as input record for the next component,
+\item the \tw{Geant4PrimaryHandler}. The primary handler creates the proper
+ \tw{G4PrimaryParticle} and \tw{G4PrimaryVertex} objects passed to \tw{Geant4}.
+ After this step all event related user interaction with Geant4 has completed,
+ and the detector simulation may commence.
+\end{itemize}
+All modules used are subclasses of the {\tw{Geant4}\-\tw{Generator}\-\tw{Action}} and must be
+added to the \tw{Geant4}\-\tw{Generator}\-\tw{Action}\-\tw{Sequence} as described
+in~\ref{sec:ddg4-user-manual-implementation-geant4action-sequences}.
+\newpage
+
+%=============================================================================
+\subsection{Anatomy of the Input Action}
+\label{sec:ddg4-implementation-geant4inputaction}
+%=============================================================================
+
+\newpage
+One input action fills one primary interaction.
+\tw{Geant4InputAction} instances may be followed by decorators, which
+allow to to smear primary vertex (\tw{Geant4InteractionVertexSmear}) or
+to boost the primary vertex \tw{Geant4InteractionVertexBoost} and all
+related particles/vertices.
+
+
+Please note, that a possible reduction of particles in
+the output record may break this unambiguous relationship between
+"hits" and particles.
+......
+
+%=============================================================================
+\subsection{Monte-Carlo Truth Handling}
+\label{sec:ddg4-implementation-particle-handling}
+%=============================================================================
+
+\newpage
+......
+
+%=============================================================================
+\section{Output Data Handling}
+\label{sec:ddg4-implementation-output-handling}
+%=============================================================================
+
+\newpage
+......
+
%=============================================================================
\section{Existing DDG4 components}
%=============================================================================
@@ -1441,6 +1771,7 @@ All components defer from the basic type \tts{Geant4Action}. This means
table below:
\vspace{0.5cm}
+\noindent
\begin{tabular}{ l l p{9cm} }
\hline
Component Properties: & & \tts{default} \\
@@ -1476,11 +1807,455 @@ components.
\end{center}
\clearpage
+%=============================================================================
+\subsection{Generic Action Modules}
+%=============================================================================
+\noindent
+%=============================================================================
+\subsubsection{Geant4UIManager}
+%=============================================================================
+\noindent
+The {\tt{Geant4UIManager}} handles interactivity aspects between Geant4,
+its command handlers (ie. terminal) and the various components the actions
+interact.
+
+\noindent
+The {\tt{Geant4UIManager}} is a component attached to the {\tt{Geant4Kernel}}
+object. All properties of all {\tt{Geant4Action}} instances may be exported to
+Geant4 messengers and {\em{may}} hence be accessible directly from the Geant4
+prompt. To export properties from any action, call the {\tt{enableUI()}}
+method of the action.
+\noindent
+The callback signature is: void operator()(G4Event* event)
+
+\vspace{0.5cm}
+\noindent
+\begin{tabular}{ l p{10cm} }
+\hline
+\bold{Class name} & \tts{Geant4} \\
+\bold{File name} & \tts{DDG4/src/Geant4.cpp} \\
+\bold{Type} & \tts{Geant4Action} \\
+\hline
+\bold{Component Properties:} & defaults apply \\
+\hline
+\bold{SessionType} (string) & Session type (csh, tcsh, etc. \\
+\bold{SetupUI} (string) & Name of the UI macro file \\
+\bold{SetupVIS} (string) & Name of the visualization macro file \\
+\bold{HaveVIS} (bool) & Flag to instantiate Vis manager
+ (def:false, unless VisSetup set) \\
+\bold{HaveUI} (bool) & Flag to instantiate UI (default=true) \\
+\end{tabular}
+
%=============================================================================
-\subsection{Physics Lists}
+\subsection{Predfined Geant4 Physics List Objects}
%=============================================================================
\noindent
+The physics list may be defined entirely data driven using the factory mechanism
+using a variety of predefined objects:
+\noindent
+\begin{itemize}\itemcompact
+\item Inventory of predefined physics lists, which may be inherited:\\
+\detdesc{html/_geant4_physics_lists_8cpp_source.html}
+{DDG4/plugins/Geant4PhysiscsLists.cpp}
+\item Inventory of predefined physics constructors, which may be instantiated:\\
+\detdesc{html/_geant4_physics_constructors_8cpp_source.html}
+{DDG4/plugins/Geant4PhysicsConstructors.cpp}
+\item Inventory of predefined process constructors, which may be instantiated:\\
+\detdesc{html/_geant4_processes_8cpp_source.html}
+{DDG4/plugins/Geant4Processes.cpp}
+\item Inventory of predefined particle constructors, which may be instantiated:\\
+\detdesc{html/_geant4_particles_8cpp_source.html}
+{DDG4/plugins/Geant4Particles.cpp}
+\end{itemize}
+\newpage
+
+%=============================================================================
+\subsection{Geant4 Generation Action Modules}
+%=============================================================================
+\noindent
+Here we discuss modules, which are instrinsically part of DDG4 and may be
+attached to the {\tt{Geant4GeneratorActionSequence}}.
+
+%=============================================================================
+\subsubsection{Base class: Geant4GeneratorAction}
+%=============================================================================
+\noindent
+The \tw{Geant4GeneratorAction} 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.
+
+\noindent
+The callback signature is: void operator()(G4Event* event)
+\noindent
+See also:
+\detdesc{html/class_d_d4hep_1_1_simulation_1_1_geant4_generator_action.html}
+{\tts{Geant4EventAction}} in the doxygen documentation.
+
+\vspace{0.5cm}
+\noindent
+\begin{tabular}{ l p{10cm} }
+\hline
+\bold{Class name} & \tts{Geant4GeneratorAction} \\
+\bold{File name} & \tts{DDG4/src/Geant4GeneratorAction.cpp} \\
+\bold{Type} & \tts{Geant4Action, Geant4GeneratorAction} \\
+\hline
+\bold{Component Properties:} & defaults apply \\
+\hline
+\end{tabular}
+
+%=============================================================================
+\subsubsection{Geant4GeneratorActionSequence}
+%=============================================================================
+\noindent
+The sequence dispatches the callbacks at the beginning
+of an event to all registered \tw{Geant4GeneratorAction} members and all
+registered callbacks.
+
+\noindent
+See also:
+\noindent
+The {\tt{Geant4GeneratorActionSequence}} is directly steered by the single
+instance of the {\tt{G4VUserPrimaryGeneratorAction}}, the Geant4 provided user hook,
+which is private.\\
+See also:
+\detdesc{html/struct_d_d4hep_1_1_simulation_1_1_geant4_user_generator_action.html}
+{\tts{Geant4UserGeneratorAction}} and
+\detdesc{html/class_d_d4hep_1_1_simulation_1_1_geant4_generator_action_sequence.html}
+{\tts{Geant4GeneratorActionSequence}} in the doxygen documentation.
+
+\vspace{0.5cm}
+\noindent
+\begin{tabular}{ l p{10cm} }
+\hline
+\bold{Class name} & \tts{Geant4Geant4GeneratorActionSequence} \\
+\bold{File name} & \tts{DDG4/src/Geant4GeneratorAction.cpp} \\
+\bold{Type} & \tts{Geant4Action} \\
+\hline
+\bold{Component Properties:} & defaults apply \\
+\hline
+\end{tabular}
+
+%=============================================================================
+\subsubsection{Geant4GeneratorActionInit}
+%=============================================================================
+\noindent
+Initialize the Geant4Event objects to host generator and MC truth related information
+Geant4 actions to collect the MC particle information.
+This action should register all event extension required for the further
+processing. We want to avoid that every client has to check if a given
+object is present or not and than later install the required data structures.
+
+\noindent
+These by default are extensions of type:
+\begin{itemize}\itemcompact
+\item \tw{Geant4PrimaryEvent} with multiple interaction sections, one for each interaction
+ This is the MAIN and ONLY information to feed Geant4
+\item \tw{Geant4PrimaryInteraction} containing the track/vertex information to create
+ the primary particles for Geant4. This record is build from the \tw{Geant4PrimaryEvent}
+ information.
+\item \tw{Geant4PrimaryMap} a map of the \tw{Geant4Particles} converted to
+ \tw{G4PrimaryParticles} to ease particle handling later.
+\item \tw{Geant4ParticleMap} the map of particles created during the event simulation.
+ This map has directly the correct particle offsets, so that the merging of
+ \tw{Geant4PrimaryInteraction} particles and the simulation particles is easy....
+\end{itemize}
+
+\vspace{0.5cm}
+\noindent
+\begin{tabular}{ l p{10cm} }
+\hline
+\bold{Class name} & \tts{Geant4Geant4GeneratorActionInit} \\
+\bold{File name} & \tts{DDG4/src/Geant4GeneratorActionInit.cpp} \\
+\bold{Type} & \tts{Geant4GeneratorAction} \\
+\hline
+\bold{Component Properties:} & defaults apply \\
+\bold{Angle} (double) & Lorentz-Angle of boost \\
+\bold{Mask} (double) & Interaction identifier \\
+\hline
+\end{tabular}
+
+%=============================================================================
+\subsubsection{Geant4InteractionVertexBoost}
+%=============================================================================
+\noindent
+Boost the primary vertex and all particles outgoing the primary interaction.
+
+\vspace{0.5cm}
+\noindent
+\begin{tabular}{ l p{10cm} }
+\hline
+\bold{Class name} & \tts{Geant4InteractionVertexBoost} \\
+\bold{File name} & \tts{DDG4/src/Geant4InteractionVertexBoost.cpp} \\
+\bold{Type} & \tts{Geant4GeneratorAction} \\
+\hline
+\bold{Component Properties:} & defaults apply \\
+\bold{Angle} (double) & \tts{Lorentz-Angle of boost} \\
+\bold{Mask} (double) & \tts{Interaction identifier} \\
+\hline
+\end{tabular}
+
+%=============================================================================
+\subsubsection{Geant4InteractionVertexBoost}
+%=============================================================================
+\noindent
+Boost the primary vertex and all particles outgoing the primary interaction.
+
+\vspace{0.5cm}
+\noindent
+\begin{tabular}{ l p{10cm} }
+\hline
+\bold{Class name} & \tts{Geant4InteractionVertexBoost} \\
+\bold{File name} & \tts{DDG4/src/Geant4InteractionVertexBoost.cpp} \\
+\bold{Type} & \tts{Geant4GeneratorAction} \\
+\hline
+\bold{Component Properties:} & defaults apply \\
+\bold{Angle} (double) & \tts{Lorentz-Angle of boost} \\
+\bold{Mask} (double) & \tts{Interaction identifier} \\
+\hline
+\end{tabular}
+
+%=============================================================================
+\subsubsection{Geant4InteractionVertexBoost}
+%=============================================================================
+\noindent
+Boost the primary vertex and all particles outgoing the primary interaction.
+
+\vspace{0.5cm}
+\noindent
+\begin{tabular}{ l p{10cm} }
+\hline
+\bold{Class name} & \tts{Geant4InteractionVertexBoost} \\
+\bold{File name} & \tts{DDG4/src/Geant4InteractionVertexBoost.cpp} \\
+\hline
+\bold{Component Properties:} & defaults apply \\
+\bold{Offset} (PxPyPzEVector) & \tts{Smearing offset} \\
+\bold{Mask} (PxPyPzEVector) & \tts{Sigma on offset} \\
+\hline
+\end{tabular}
+
+%=============================================================================
+\subsubsection{Geant4InteractionMerger}
+%=============================================================================
+\noindent
+Merge all interactions created by each {\tt{Geant4InputAction}} into one single
+record. The input records are taken from the item {\tt{Geant4PrimaryEvent}}
+and are merged into the {\tt{Geant4PrimaryInteraction}} object attached to the
+{\tt{Geant4Event}} event context.
+
+\vspace{0.5cm}
+\noindent
+\begin{tabular}{ l p{10cm} }
+\hline
+\bold{Class name} & \tts{Geant4InteractionMerger} \\
+\bold{File name} & \tts{DDG4/src/Geant4InteractionMerger.cpp} \\
+\bold{Type} & \tts{Geant4GeneratorAction} \\
+\hline
+\bold{Component Properties:} & defaults apply \\
+\hline
+\end{tabular}
+
+%=============================================================================
+\subsubsection{Geant4PrimaryHandler}
+%=============================================================================
+\noindent
+Convert the primary interaction (object {\tt{Geant4PrimaryInteraction}} object
+attached to the {\tt{Geant4Event}} event context) and pass the result
+to Geant4 for simulation.
+
+\vspace{0.5cm}
+\noindent
+\begin{tabular}{ l p{10cm} }
+\hline
+\bold{Class name} & \tts{Geant4PrimaryHandler} \\
+\bold{File name} & \tts{DDG4/src/Geant4PrimaryHandler.cpp} \\
+\bold{Type} & \tts{Geant4GeneratorAction} \\
+\hline
+\bold{Component Properties:} & defaults apply \\
+\hline
+\end{tabular}
+
+%=============================================================================
+\subsubsection{Geant4ParticleGun}
+%=============================================================================
+\noindent
+Implementation of a particle gun using Geant4Particles.
+
+\noindent
+The {\tt{Geant4ParticleGun}} is a tool to shoot a number of
+particles with identical properties into a given region of the
+detector to be simulated.
+
+\noindent
+The particle gun is a input source like any other and participates
+in the general input stage merging process like any other input
+e.g. from file. Hence, there may be several particle guns present
+each generating it's own primary vertex. Use the mask property to
+ensure each gun generates it's own, well identified primary vertex.
+
+\noindent
+There is one 'user lazyness' support though:
+If there is only one particle gun in use, the property 'Standalone',
+which by default is set to true invokes the interaction merging and he
+Geant4 primary generation directly.
+
+\vspace{0.5cm}
+\noindent
+\begin{tabular}{ l p{10cm} }
+\hline
+\bold{Class name} & \tts{Geant4PrimaryHandler} \\
+\bold{File name} & \tts{DDG4/src/Geant4PrimaryHandler.cpp} \\
+\bold{Type} & \tts{Geant4GeneratorAction} \\
+\hline
+Component Properties: & default \\
+\bold{particle} (string) & Particle type to be shot \\
+\bold{energy} (double) & Particle energy in $MeV$ \\
+\bold{position} (XYZVector) & Pole position of the generated particles in $mm$\\
+\bold{direction} (XYZVector) & Momentum direction of the generated particles\\
+\bold{isotrop} (bool) & Isotrp particle directions in space. \\
+\bold{Mask} (int.bitmask) & Interaction identifier \\
+\bold{Standalone} (bool) & Setup for standalone execution \\
+ & including interaction merging etc. \\
+\hline
+\end{tabular}
+
+%=============================================================================
+\subsubsection{Geant4ParticleHandler}
+%=============================================================================
+\noindent
+Extract the relevant particle information during the simulation step.
+
+\noindent
+This procedure works as follows:
+\begin{itemize}\itemcompact
+\item At the beginning of the event generation the object registers itself as
+ Monte-Carlo truth handler to the event context.
+\item At the begin of each track action a particle candidate is created and filled
+ with all properties known at this time.
+\item At each stepping action a flag is set if the step produced secondaries.
+\item Sensitive detectors call the MC truth handler if a hit was created.
+ This fact is remembered.
+\item At the end of the tracking action a first decision is taken if the candidate is to be
+ kept for the final record.
+\item At the end of the event action finally all particles are reduced to the
+ final record. This logic can be overridden by a user handler to be attached.
+\end{itemize}
+\noindent
+Any of these actions may be intercepted by a {\tt{Geant4UserParticleHandler}}
+attached to the particle handler.
+See class {\tt{Geant4UserParticleHandler}} for details.
+
+\vspace{0.5cm}
+\noindent
+\begin{tabular}{ l p{9cm} }
+\hline
+\bold{Class name} & \tts{Geant4ParticleHandler} \\
+\bold{File name} & \tts{DDG4/src/Geant4ParticleHandler.cpp} \\
+\bold{Type} & \tts{Geant4GeneratorAction} \\
+\hline
+\bold{Component Properties:} & defaults apply \\
+\bold{KeepAllParticles} (bool) & Flag to keep entire particle record without any reduction.
+ This may result in a huge output record. \\
+\bold{SaveProcesses} (vector(string)) & Array of Geant4 process names,
+ which products and parent should NOT be reduced.\\
+\bold{MinimalKineticEnergy} (double) & Minimal energy below which particles should be
+ ignored unless other criteria
+ (Process, created hits, etc) apply.\\
+\hline
+\end{tabular}
+\newpage
+
+%=============================================================================
+\subsection{Geant4 Event Action Modules}
+%=============================================================================
+\noindent
+
+%=============================================================================
+\subsubsection{Base class: Geant4EventAction}
+%=============================================================================
+\noindent
+The EventAction is called for every event.
+
+\noindent
+This class is the base class for all user actions, which have
+to hook into the begin- and end-of-event actions.
+Typical use cases are the collection/computation of event
+related properties.
+
+\noindent
+Examples of this functionality may include for example:
+\begin{itemize}\itemcompact
+\item Reset variables summing event related information in the
+ begin-event callback.
+\item Monitoring activities such as filling histograms
+ from hits collected during the end-event action.
+\end{itemize}
+See also:
+\detdesc{html/class_d_d4hep_1_1_simulation_1_1_geant4_event_action.html}
+{\tts{Geant4EventAction}} in the doxygen documentation.
+
+\vspace{0.5cm}
+\noindent
+\begin{tabular}{ l p{10cm} }
+\hline
+\bold{Class name} & \tts{Geant4EventAction} \\
+\bold{File name} & \tts{DDG4/src/Geant4EventAction.cpp} \\
+\bold{Type} & \tts{Geant4EventAction} \\
+\hline
+\bold{Component Properties:} & defaults apply \\
+\hline
+\end{tabular}
+
+%=============================================================================
+\subsubsection{Geant4EventActionSequence}
+%=============================================================================
+\noindent
+
+\noindent
+The {\tt{Geant4EventActionSequence}} is directly steered by the single
+instance of the {\tt{G4UserEventAction}}, the Geant4 provided user hook,
+which is private.\\
+See also:
+\detdesc{html/struct_d_d4hep_1_1_simulation_1_1_geant4_user_event_action.html}
+{\tts{Geant4UserEventAction}} in the doxygen documentation.
+
+\vspace{0.5cm}
+\noindent
+\begin{tabular}{ l p{10cm} }
+\hline
+\bold{Class name} & \tts{Geant4EventAction} \\
+\bold{File name} & \tts{DDG4/src/Geant4EventAction.cpp} \\
+\bold{Type} & \tts{Geant4EventAction} \\
+\hline
+\bold{Component Properties:} & defaults apply \\
+\hline
+\end{tabular}
+
+%=============================================================================
+\subsubsection{Geant4ParticlePrint}
+%=============================================================================
+\noindent
+Geant4Action to print MC particle information.
+
+\vspace{0.5cm}
+\noindent
+\begin{tabular}{ l p{10cm} }
+\hline
+\bold{Class name} & \tts{Geant4ParticlePrint} \\
+\bold{File name} & \tts{DDG4/src/Geant4ParticlePrint.cpp} \\
+\bold{Type} & \tts{Geant4EventAction} \\
+\hline
+\bold{Component Properties:} & defaults apply \\
+\bold{OutputType} (bool) & Flag to steer output type. \\
+ & 1: Print table of particles. \\
+ & 2: Print table of particles. \\
+ & 3: Print table and tree of particles. \\
+\bold{PrintHits} & Print associated hits to every particle (big output!)\\
+\hline
+\end{tabular}
+\newpage
%=============================================================================
@@ -1489,61 +2264,58 @@ components.
\noindent
%=============================================================================
-\subsubsection{Geant4SimpleTracker}
+\subsubsection{Geant4TrackerAction}
%=============================================================================
\noindent
Simple sensitive detector for tracking detectors. These trackers create one
single hit collection. The created hits may be written out with the output
-modules of type "Simple" described in
-Section~\ref{sec:ddg4-components-IO-ROOT-simple}
-and~\ref{sec:ddg4-components-IO-ROOT-simple}. Here the basic specifications:
+modules described in Section~\ref{sec:ddg4-components-IO-ROOT-simple}
+and~\ref{sec:ddg4-components-IO-LCIO-simple}. \\
+The basic specifications are:
\vspace{0.5cm}
+\noindent
\begin{tabular}{ l p{10cm} }
\hline
Basics: & \\
\hline
-\bold{Class name} & \tts{Geant4SensitiveAction<SimpleTracker>} \\
+\bold{Class name} & \tts{Geant4SensitiveAction<Geant4Tracker>} \\
\bold{File name} & \tts{DDG4/plugins/Geant4SDActions.cpp} \\
-\bold{Hit collection} & \tts{<detector name>} \\
-\bold{Hit class} & \tts{SimpleTracker::Hit} \\
+\bold{Hit collection} & \tts{Name of the readout object} \\
+\bold{Hit class} & \tts{Geant4Tracker::Hit} \\
\bold{File name} & \tts{DDG4/include/Geant4Data.h} \\
\hline
-Component Properties: & \tts{default} \\
+\bold{Component Properties:} & defaults apply \\
\hline
\end{tabular}
%=============================================================================
-\subsubsection{Geant4SimpleCalorimeter}
+\subsubsection{Geant4CalorimeterAction}
%=============================================================================
\noindent
Simple sensitive detector for calorimeters. The sensitive detector creates one
single hit collection. The created hits may be written out with the output
-modules of type "Simple" described in
-Section~\ref{sec:ddg4-components-IO-ROOT-simple}
-and~\ref{sec:ddg4-components-IO-ROOT-simple}. Here the basic specifications:
+modules described in Section~\ref{sec:ddg4-components-IO-ROOT-simple}
+and~\ref{sec:ddg4-components-IO-LCIO-simple}. \\
+The basic specifications are:
\vspace{0.5cm}
+\noindent
\begin{tabular}{ l p{10cm} }
\hline
Basics: & \\
\hline
-\bold{Class name} & \tts{Geant4SensitiveAction<SimpleCalorimeter>} \\
+\bold{Class name} & \tts{Geant4SensitiveAction<Geant4Calorimeter>} \\
\bold{File name} & \tts{DDG4/plugins/Geant4SDActions.cpp} \\
-\bold{Hit collection} & \tts{<detector name>} \\
-\bold{Hit class} & \tts{SimpleCalorimeter::Hit} \\
+\bold{Hit collection} & \tts{Name of the readout object} \\
+\bold{Hit class} & \tts{Geant4Calorimeter::Hit} \\
\bold{File name} & \tts{DDG4/include/Geant4Data.h} \\
\hline
-Component Properties: & \tts{default} \\
+\bold{Component Properties:} & defaults apply \\
\hline
\end{tabular}
-
-%=============================================================================
-\subsubsection{Geant4SimpleOpticalCalorimeter}
-%=============================================================================
-\noindent
-
+\newpage
%=============================================================================
\subsection{I/O Components}
diff --git a/doc/LaTex/DDG4_event_data_model.png b/doc/LaTex/DDG4_event_data_model.png
new file mode 100644
index 0000000000000000000000000000000000000000..a757f10bde5e8b7009dc8bf089f88cfff93f5204
Binary files /dev/null and b/doc/LaTex/DDG4_event_data_model.png differ
diff --git a/doc/LaTex/DDG4_input_stage.png b/doc/LaTex/DDG4_input_stage.png
new file mode 100644
index 0000000000000000000000000000000000000000..3bc863cd3150f02e6301a61168f089a4441ae460
Binary files /dev/null and b/doc/LaTex/DDG4_input_stage.png differ
diff --git a/doc/LaTex/ulineno.tex b/doc/LaTex/ulineno.tex
new file mode 100644
index 0000000000000000000000000000000000000000..25d20bcaec4a9e5efb89f5ac5fa5986cb4c2806b
--- /dev/null
+++ b/doc/LaTex/ulineno.tex
@@ -0,0 +1,986 @@
+% Copyright 1995--1999 Stephan I. B"ottcher <stephan@nevis1.columbia.edu>
+%
+% This program can be redistributed and/or modified under the terms
+% of the LaTeX Project Public License Distributed from CTAN
+% archives in directory macros/latex/base/lppl.txt; either
+% version 1 of the License, or any later version.
+%
+% $Id: ulineno.tex,v 3.1 2001/08/03 03:29:19 stephan Exp $
+%
+% 1999-06-11 SiB: updated for lineno.sty v3.00
+\ProvidesFile{ulineno.tex}[2001/08/03 lineno.sty users manual]
+ %% <- UL 2011/02/13 for readprov.sty
+
+\documentclass[12pt,a4paper,titlepage]{article}
+
+ \date{\def\$##1: ##2 ##3${##2}%$
+ Version
+ \$Revision: 3.1 $,
+ \$Date: 2001/08/03 03:29:19 $
+ }
+ \def\lineno.sty{\texttt{\itshape lineno.sty}}
+
+
+\title{ \lineno.sty
+\\ Users Manual
+}
+\author{ Stephan I. B\"ottcher
+}
+
+\usepackage{lineno}
+\usepackage{url}
+
+\def~{\verb~}
+\catcode`\<\catcode`\~
+\def<#1>{$\langle${\itshape#1}\/$\rangle$}
+\catcode`\|\catcode`\~
+\def|#1{{\ttfamily\string#1}}
+\def\NL{<number>]}
+
+\begin{document}
+\begin{runninglinenumbers}
+\renewcommand\linenumberfont{\normalfont\small\bfseries}
+\setlength\linenumbersep{1cm}
+\maketitle
+\thispagestyle{empty}
+\resetlinenumber
+\tableofcontents
+\clearpage
+\setcounter{page}{1}
+\pagewiselinenumbers
+
+\section{When to use \lineno.sty}
+
+The primary use of \lineno.sty is to get line numbers in your LaTeX
+document. \lineno.sty directly supports line numbers in various
+modes, and if you have any wishes that are not directly supported,
+chances are good that \lineno.sty can be adapted to do it. And if it
+turns out to be difficult with \lineno.sty, then it will be even more
+difficult without.
+
+There is one class of cases however, where \lineno.sty is not the most
+appropriate tool. When your text already comes in lines, like source
+listings, tables, poetry, then \lineno.sty will propably do the job,
+but other tools could do it much more efficiently.
+
+\lineno.sty can only number lines in the main text. Lines in any kind
+of boxes cannot be numbered. But see section \ref{sec:ilineno} below.
+
+\lineno.sty is especially useful when the text is broken into lines by
+\TeX\ itself. In this case, the task to attach line numbers is not
+easy, and a tool like \lineno.sty has good chances to break when used
+together with other packages.
+
+On the other hand, \lineno.sty proved to be quite stable, and I did
+not get any reports of complete failure yet.
+
+With \lineno.sty, you can refer to the line numbers via \LaTeX s
+~\ref~ and ~\pageref~ macros.
+
+There are other applications, not directly related to line numbering.
+Whenever you want to attach something to your text, after a paragraph
+was broken into lines, across pagebreaks, lineno may do the job.
+
+\begin{bframe}
+ Say, you need a frame around some text, but the text should be able
+ to break across pages, \lineno.sty can be used to draw rules on both
+ margins, which can be completed at the top and bottom by some
+ special environment, see section\,\,\ref{sec:bframe}.
+\end{bframe}
+
+There may be cases, where other packages do a better job, e.g.,
+\url{CTAN:macros/latex/contrib/supported/numline}.
+
+
+\section{Where to get \lineno.sty}
+
+\lineno.sty is available on the \emph{Comprehensive TeX Archive
+ Network} (CTAN), e.g, \url{ftp:// ftp.tex.ac.uk/ tex-archive/
+ macros/ latex/ contrib/ supported/ lineno/ lineno.sty}.
+
+The home of \lineno.sty is \url{http:// www.nevis.columbia.edu/
+ ~stephan/ tex/ #lineno}. Here you can get the latest version.
+
+\end{runninglinenumbers}
+
+\section{How to use \lineno.sty}
+
+As any other \LaTeXe\ package, you need to load it with
+\begin{quote}
+ ~\usepackage[~<options>~]{lineno}~
+\end{quote}
+
+\subsection{Package options}
+
+The available <options> are:
+\begin{description}
+
+\item[\texttt{[left]}:] Put the line numbers into the left margin
+ (default).
+
+\item[\texttt{[right]}:] Put the line numbers into the right margin.
+
+\item[\texttt{[switch]}:] Put the line numbers into the outer margin
+ (left on even numbered pager, right on odd numbered pages).
+
+\item[\texttt{[switch*]}:] Put the line numbers into the inner
+ margin.
+
+\item[\texttt{[pagewise]}:] Number the lines from 1 on each page.
+
+\item[\texttt{[running]}:] Continuously number the lines (default).
+
+\item[\texttt{[modulo]}:] Print line numbers only if they are
+ multiples of five.
+
+\item[\texttt{[mathlines]}:] When using the ~{linenomath}~
+ environment for display math, put line numbers also on the lines of
+ the display.
+
+\item[\texttt{[displaymath]}:] Automatically wrap the standard LaTeX
+ display math environments in ~{linenomath}~.
+
+ \begin{itshape}
+ Change from v2 to v3: ~[mathlines]~ was called ~[displaymath]~
+ before, and ~[displaymath]~ was ~\usepacke{mlineno}~.
+ \end{itshape}
+
+\end{description}
+All effects of these option can also be obtained by calling certain
+macros later in the document, except for ~[displaymath]~.
+
+\subsection{How to turn on line numbering}
+
+The line numbering is not activated by default. If you want line
+numbers, you have to turn it on. The simplest way is to say
+\begin{quote}
+ ~\linenumbers~
+\end{quote}
+This will turn on line numbers within the current group, according to
+the currently selected mode. If you do it right at the beginning, the
+whole document will be numbered.
+
+~\linenumbers~ takes effect only when a paragraph is finished. This
+is important if you use ~\linenumbers~ for a single paragraph only.
+This will \emph{not} work:
+\begin{quote}\obeylines
+ ~\begingroup~\\%
+ ~\linenumbers~
+ Text of your paragraph.
+ ~\endgroup~
+\end{quote}
+because the ~\endgroup~ terminates the effect of ~\linenumbers~ before
+the paragraph is finished. The solution is to insert an empty line,
+or an explicit ~\par~ before the ~\endgroup~.
+
+The prefered solution is to use an enviroment:
+\begin{quote}\obeylines
+ ~\begin{linenumbers}~
+ Text of your paragraph.
+ ~\end{linenumbers}~
+\end{quote}
+~\end{linenumbers}~ terminates the paragraph for you. It will also
+make sure that the next paragraph is not indented, if there is no
+empty line in between.
+
+This form will not finish any preceeding paragraph. If you do not
+leave an empty line before ~\begin{linenumbers}~, the previous
+ paragraph may also get line numbers (this is not true after a list
+ environment).
+
+A quite esoteric form to number a single paragraph is:
+\begin{quote}\obeylines
+ Text of your paragraph.
+ ~{\linenumbers\par}~
+\end{quote}
+Here, the ~\linenumbers~ is turned on in a group that just executes
+the ~\par~ to terminate the previous paragraph. Only this paragraph
+will have line numbers. (~\par~ is exactly equivalent to an empty
+line).
+
+
+\subsection{How to turn off line numbering}
+
+You do not usualy turn of line numbering explicitly, but rather
+restrict line numbering to a group or an environment. However, you
+can turn it off with the command
+\begin{quote}
+ ~\nolinenumbers~
+\end{quote}
+This macro can also be used as an environment. The same restrictions
+apply as for ~\linenumbers~.
+
+
+\section{Numbering modes}
+
+Attaching line numbers after \TeX\ has broken the paragraph into lines
+is already quite a difficult job for \TeX. Why? Because \TeX\ does
+not normally give you any control after line breaking. \lineno.sty
+does it by pretending that the current page ends after each and every
+line. This keeps \TeX\ quite busy, but works.
+
+Often, you want the line numbers to depend on the page they finally end
+up. E.g., you want the numbers to start with~ ~1 one each new page,
+or you want them to appear on the outer margins in twoside mode. This
+is an almost impossible demand, but \lineno.sty can do it, at some
+cost, in terms of computing time, memory, and disk space. \lineno.sty
+needs to write a note into the auxiliary file for each line in the
+numbered part of the text, and \TeX\ keeps some memory for each page,
+and all that takes some computation time to figure out on which page
+the line was in the last \LaTeX\ run.
+
+Thus, there are two basic numbering modes
+\begin{enumerate}
+
+\item \emph{Running} line numbers. The numbers run continuously along
+ the document, without considering page breaks.
+
+ The line numbers can be reset, or preset at any point in the
+ document (except within a paragraph). Margin switching (or any
+ other dependence on the page breaks) is not possible.
+
+\item \emph{Pagewise} line numbers. The lines on each page are
+ numbered from one. Automatic margin switching is possible.
+
+ \emph{Running} mode can be simulated in pagewise mode, to get
+ automatic margin switching with continuous line numbers, but without
+ the ability to reset/preset the line numbers anywhere in the
+ document.
+
+ Any feature that depends on the page breaks must use this mode.
+
+\end{enumerate}
+
+\begin{runninglinenumbers*}
+
+\subsection{\emph{Running} line numbers}
+
+This is the default mode of operation. The lines of your text are
+numbered continuously across page breaks.
+
+You cannot get automatic margin switching in this mode, because at the
+time when the line numbers are attached, it is not yet decided on
+which page the line will end up. However, you can simulate continuous
+line numbers in \emph{pagewise} mode (see below), where margin
+switching becomes possible.
+
+You get this mode by
+\begin{itemize}\raggedright
+\item \emph{not} specifying any of the package options
+ ~[switch,pagewise]~,
+\item specifying the package option ~[running]~,
+\item give the command ~\setrunninglinenumbers~ in the document, or
+\item turn on line numbering with ~\runninglinenumbers~ or
+ ~\begin{runninglinenumbers}~.
+\end{itemize}
+
+\subsubsection{Reseting or setting the line number}
+
+You can reset the line number with
+\begin{quote}
+ ~\resetlinenumber[~<number>~]~
+\end{quote}
+where the default is to reset the line number to one.
+
+Alternatively, you can give the line number in an optional argument to
+any command that turns on the line numbering in this mode:
+\begin{quote}\obeylines
+ ~\linenumbers[~<number>~]~
+ ~\runninglinenumbers[~<number>~]~
+ ~\begin{linenumbers}[~<number>~]~
+ ~\begin{runninglinenumbers}[~<number>~]~
+\end{quote}
+or reset the line number to 1 with any of the following:
+\begin{quote}\obeylines
+ ~\linenumbers*~
+ ~\runninglinenumbers*~
+ ~\begin{linenumbers*}~
+ ~\begin{linenumbers}*~
+ ~\begin{runninglinenumbers*}~
+ ~\begin{runninglinenumbers}*~
+\end{quote}
+This section of the manual is enclosed in
+\begin{quote}\obeylines
+ ~\begin{runninglinenumbers*}~
+ ~\end{runninglinenumbers*}~
+\end{quote}
+\end{runninglinenumbers*}
+
+
+\begin{pagewiselinenumbers}
+
+\subsection{\emph{Pagewise} line numbers}
+
+Basically, this mode prints line numbers starting with 1 on top of
+each page, counting only lines where this mode is active. If you
+turn on this mode in the middle of a page, the numbers start with 1
+at that point.
+
+The \emph{pagewise} mode of operation is quite a bit more work for
+\TeX. When the line numbers are printed, \TeX\ does not know on which
+page the current line will go. To get \emph{pagewise} mode working,
+\LaTeX\ has to remember on which page the line went in a previous run.
+This information is written into the ~.aux~ file, and like a table of
+contents, you will not see the numbers until you run \LaTeX\ at least
+twice on the document. Sometimes the information in the ~.aux~ file
+becomes invalid in a way that causes \lineno.sty to hang. In such a
+case you'll have to delete all ~.aux~ files of the document to get it
+going again.
+
+You get this mode by
+\begin{itemize}\raggedright
+\item specifying the package option
+ ~[pagewise]~, but not ~[running]~,
+\item give the command ~\setpagewiselinenumbers~ in the document, or
+\item turn on line numbering with ~\pagewiselinenumbers~ or
+ ~\begin{pagewiselinenumbers}~.
+\end{itemize}
+
+You cannot reset or preset the line numbers in \emph{pagewise} mode.
+This mode uses a different counter than \emph{running} mode. You can
+switch between the mode, and the \emph{running} numbers will continue
+where they left of, unless you reset the counter.
+
+\subsubsection{Margin switching}
+
+As a side effect of all the business to find out on which page the lines
+end up, margin switching becomes possible. It is now possible to
+print the line number differently on odd and even pages. The command
+\begin{quote}
+ ~\switchlinenumbers~
+\end{quote}
+will cause the line numbers to be printed on the outer margins, on the
+right side for odd pages, and on the left side for even numbered
+pages. If you add a star, the numbers go on the inner margins
+\begin{quote}
+ ~\switchlinenumbers*~
+\end{quote}
+You can achieve the same effect by specifying the package
+option ~[switch]~ or ~[switch*]~ together with ~[pagewise]~.
+
+Margin switching is independent of any ~[twoside]~ option of the
+document class.
+
+\subsubsection{\emph{Running} mode with margin switching}
+
+Margin switching is not possible in \emph{running} mode, but you can
+abuse the pagewise mode to produce continuous line numbers. This mode
+is activated with the command
+\begin{quote}
+ ~\runningpagewiselinenumbers~
+\end{quote}
+It is not possible to reset the line number counter for this mode, the
+lines will be numbered starting from one at the beginning of the
+document, and continue. You can switch back to real pagewise mode with
+\begin{quote}
+ ~\realpagewiselinenumbers~
+\end{quote}
+but when you resume \emph{running-pagewise}, the numbers will not
+continue where they left off, but jump by the number of lines that
+were numbered \emph{real-pagewise}.
+
+The package options ~[switch]~ and ~[switch*]~ will turn on
+\emph{running pagewise} mode with margin switching, unless you also
+specify ~[pagewise]~.
+
+Finally, if you give these options together with ~[running]~, like
+\begin{quote}
+ ~\usepackage[switch,pagewise,running]{lineno}~
+\end{quote}
+the mode is set to plain \emph{running} line numbers, but later in
+your document, if you say ~\pagewiselinenumbers~, the setings of the
+~[switch]~ and ~[pagewise]~ options will take effect.
+
+\subsubsection{Page numbers}
+
+Any pages that contain \emph{pagewise} numbered lines must have a
+different page number. This may cause trouble with titlepages or
+simmilar fudging with the page number counter in the document. (I am
+talking about ~\c@page~ or ~\count 0~ here, not ~\thepage~).
+
+If you get strange errors, like \emph{``the use of} ~\nextLN~
+\emph{does not match its definition''}, you should first delete all
+~.aux~ files, and rerun \LaTeX\ several times. If the error does not
+reappear, fine, else check your page numbers, including those that are
+not printed. You may use \emph{running} line numbers on your
+titlepages, since the page boundaries are predefined, usually.
+
+\end{pagewiselinenumbers}
+
+\begin{linenumbers*}
+
+\subsection{Margin selection}
+
+In any mode you can select a fixed margin on which the numbers shall
+be printed. You can either give a package option ~[left]~ or
+~[right]~, or change the margin within the document with
+\begin{quote}\obeylines
+ ~\leftlinenumbers~
+\rightlinenumbers
+ ~\rightlinenumbers~
+\end{quote}
+\rightlinenumbers
+Neither of these commands actually turns on line numbering. The
+margin setting is changed for the currently selected mode
+\emph{running} or \emph{pagewise}. If you want to set the margin for
+both modes, append a star
+\begin{quote}\obeylines
+ ~\leftlinenumbers*~
+ ~\rightlinenumbers*~
+\end{quote}
+The default is ~\leftlinenumbers*~.
+
+\end{linenumbers*}
+
+
+\subsection{Summary of mode selection commands}
+
+The following commands change the major line numbering mode.
+\begin{description}\itemsep=0pt\parskip=0pt
+\item [|\setrunninglinenumbers]
+\item [|\setpagewiselinenumbers] \leavevmode\\
+ set the current mode, without activating or deactivating line
+ numbering.
+\item [|\runninglinenumbers\texttt{*[\NL}]
+\item [|\pagewiselinenumbers] \leavevmode\\
+ set the current mode and activate line numbering, optionally reset
+ (~*~), or set the line number for \emph{running} mode.
+\end{description}
+The following commands do not change the major mode, but modify the
+the behaviour of \emph{pagewise} mode
+\begin{description}\itemsep=0pt\parskip=0pt
+\item [|\realpagewiselinenumbers]
+\item [|\runningpagewiselinenumbers] \leavevmode\\
+ select if \emph{pagewise} mode should number continuously, or really
+ pagewise.
+\end{description}
+
+
+\subsection{Summary of margin selection commands}
+
+The following command select into which margin the numbers should be
+printed
+\begin{description}\itemsep=0pt\parskip=0pt
+\item [|\leftlinenumbers\texttt*]
+\item [|\rightlinenumbers\texttt*] \leavevmode\\
+ put the line numbers in the left/right margin in both modes.
+\item [|\leftlinenumbers]
+\item [|\rightlinenumbers] \leavevmode\\
+ put the line number into the left/right margin in the currently
+ selected mode.
+\item [|\switchlinenumbers] \leavevmode\\
+ put the line numbers into the outer margin, when using
+ \emph{pagewise} mode.
+\item [|\switchlinenumbers\texttt*] \leavevmode\\
+ put the line numbers into the inner margin, when using
+ \emph{pagewise} mode.
+\end{description}
+
+\begin{linenumbers*}
+\modulolinenumbers[2]
+
+\subsection{Numbering only one in five lines}
+
+You can ask lineno to print the line numbers only if they devide by
+<n>, by saying
+\begin{quote}
+ ~\modulolinenumbers[~<n>~]~
+\end{quote}
+If you omit the optional argument, it will be every fifth line, or
+whatever you used last (the current value of the counter
+~linenumbermodulo~). You get the same effect by giving the package
+option ~[modulo]~.
+
+If you set <n> to 1, the modulo value is not changed, but modulo
+numbering is turned off.
+
+Changing the counter ~linenumbermodulo~ does not turn on modulo
+numbering, it just changes the modulo, if it is turned on without the
+optional argument.
+
+This section of the manual is enclosed in
+\begin{quote}
+ ~\begin{linenumbers*}~ \\
+ ~\modulolinenumbers[2]~
+
+ ~\end{linenumbers*}~
+\end{quote}
+
+\end{linenumbers*}
+
+\begin{pagewiselinenumbers}
+\switchlinenumbers
+
+\subsection{How the line numbers look like}
+
+This section of the manual is enclosed in
+\begin{quote}
+ ~\begin{pagewiselinenumbers}~ \\
+ ~\switchlinenumbers~
+
+ ~\end{pagewiselinenumbers}~
+\end{quote}
+By default, the line numbers are set in
+\begin{quote}
+ ~\normalfont\tiny\sffamily~
+\end{quote}
+right justified to 10\,pt left of the nominal left edge of the text.
+If the number is to appear on the right margin, it is right justified
+to 20\,pt right of the nominal right edge of the text.
+
+You can easily change that, of course. The font is defined by the
+macro
+\begin{quote}
+ ~\linenumberfont~
+\end{quote}
+You can redefine it to make the numbers appear in a differnt font
+(with ~\renewcommand~). I'll say right here in this manual
+\renewcommand\linenumberfont{\normalfont\bfseries\small}
+\begin{quote}
+ ~\renewcommand\linenumberfont{\normalfont\bfseries\small}~
+\end{quote}
+The distance on the left margin can be changed with
+\begin{quote}
+ ~\setlength\linenumbersep{~<distance>~}~
+\end{quote}
+The distance on the right margin is ~\linenumbersep~ plus
+~\linenumberwidth~, both are set to 10\,pt by default.
+Let's do right here
+\setlength\linenumberwidth{1cm}
+\begin{quote}
+ ~\setlength\linenumbersep{1cm}~
+\end{quote}
+I put the command at the end of the paragraph, but it effects the
+whole paragraph, because that is where everything happens: at the end
+of the paragraphs.
+
+The line numbers are printed as arabic numerals, as defined in the
+macro
+\begin{quote}
+ ~\thelinenumber~
+\end{quote}
+for the \LaTeX\ counter ~{linenumber}~. You can redefine that, as
+for any other \LaTeX\ counter. E.g.,
+\renewcommand\thelinenumber{\roman{linenumber}}
+\begin{quote}
+ ~\renewcommand\thelinenumber{\roman{linenumber}}~
+\end{quote}
+(For heavy duty line numbering, you should use \LaTeX s internal
+format, e.g., ~\@roman\c@linenumber~.)
+
+\subsubsection{Deeper customization}
+
+The line number is attached to the line by the macro
+\begin{quote}
+ ~\makeLineNumber~
+\end{quote}
+which is expanded inside a zero width ~\hbox~ alligned to the
+origin of the current line (left edge, baselines alligned). You can
+do anything in this macro. Let's assume you do not want line numbers
+at all, but just attach something else to each line of text: this is
+the macro to modify. You can refer to the line number by the macro
+~\LineNumber~, which prints the current value of the counter
+~{linenumber}~, or nothing if \emph{modulo} mode is active, and the
+number does not divide by ~{linenumbermodulo}~. You should not modify
+this macro when using any form of \emph{pagewise} mode. At the end of
+this paragraph I put the following
+\begin{runninglinenumbers}
+\renewcommand\makeLineNumber
+ {\hss$\rightarrow$\ \rlap{\hskip\textwidth\ $\leftarrow$}}
+\end{runninglinenumbers}
+\begin{quote}
+ ~\begin{runninglinenumbers}~\\
+ ~\renewcommand\makeLineNumber~\\
+ ~ {\hss$\rightarrow$\ \rlap{\hskip\textwidth\ $\leftarrow$}}~\\
+ ~\end{runninglinenumbers}~
+\end{quote}
+
+Redefining ~\makeLineNumber~ cuts deep into the linenumber mode
+setting. If you still want to use the basic modes \emph{running} and
+\emph{pagewise} you should go one level up and modify one of the
+following macros, which are called by (or assigned to)
+~\makeLineNumber~ depending on the current mode, and with the counter
+~{linenumber}~ allready adjusted for the current page when using
+\emph{pagewise} mode.
+\begin{quote}\obeylines
+ ~\makeLineNumberRunning~
+ ~\makeLineNumberOdd~
+ ~\makeLineNumberEven~
+\end{quote}
+The first is used in \emph{running} mode, the other two in
+\emph{pagewise} mode. If you modify those, you cut into the
+margin selection mechanism as advertised above. You will have to call
+a mode selection command after changing these macros, to make them take
+effect (at least for ~\makeLineNumberRunning~).
+
+You can go up one more step. The margin selection commands redefine
+the above macros by making them equivalent (~\let~) to one of the
+following macros
+\begin{quote}\obeylines
+ ~\makeLineNumberLeft~
+ ~\makeLineNumberRight~
+\end{quote}
+You may redefine these, and afterwards issue a margin selection
+command followed by a mode selection command. The default definitions
+are
+\begin{quote}
+ ~\def\makeLineNumberLeft~\\
+ ~ {\hss\linenumberfont\LineNumber\hskip\linenumbersep}~
+\end{quote}
+and
+\begin{quote}
+ ~\def\makeLineNumberRight~\\
+ ~ {\linenumberfont\hskip\linenumbersep\hskip\textwidth~\\
+ ~ \hbox to\linenumberwidth{\hss\LineNumber}\hss}~
+\end{quote}
+Whatever you do, use ~\LineNumber~ to print the digits. This ensures
+that the modulo mode setting is acknowledged. If you want to
+customize that as well, this is the macro to change. ~\LineNumber~
+eventually refers to ~\thelinenumber~, which is the place to customize
+the numerals themselves. At the end of this paragraph I said
+\renewcommand\LineNumber{\ifodd\value{linenumber} \thelinenumber)\fi}
+\begin{quote}
+ ~\renewcommand\LineNumber~\\
+ ~ {\ifodd\value{linenumber} \thelinenumber)\fi}~
+\end{quote}
+Line number references are not affected by ~\LineNumber~, but you
+should keep track of ~\thelinenumber~. Look at the following
+reference
+\begin{quote}
+ The setion title of the next section is on page \pageref{ll1}, line
+ \ref{ll1}.
+\end{quote}
+There is a mismatch in the definition of ~\thelinenumber~, from the
+point of the refered line to the reference here.
+\end{pagewiselinenumbers}
+
+\begin{pagewiselinenumbers}
+
+\section[Line number references]
+ {Line number references\linelabel{ll1}}
+
+\lineno.sty allows to refer to a line number with ~\ref{~<label>~}~.
+The label is set by ~\linelabel{~<label>~}~, anywhere in a paragraph
+that gets line numbers. If you put a ~\linelabel~ somewhere else, the
+line number it refers to is pretty meaningless, but no error message
+is issued. (This section begins on line \ref{ll1}, page
+\pageref{ll1} and ends on line \ref{ll2}, page \pageref{ll2}.)
+
+References work both in \emph{running} and \emph{pagewise} modes.
+However, you have to be very careful when using both \emph{real
+ pagewise} mode and \emph{running pagewise} mode: The mode setting
+must be the same during reference as during labeling.
+
+The restrictions on placing a ~\linelabel~ are the same as for a
+~\marginpar~. (In fact, they are implemented as fake ~\marginpar~s.)
+E.g., the linelabel on the section header of this chapter could not be
+placed in the straight forward way, because it would cause an error in
+the table of contents. (It should be disabled during \emph{toc}
+processing.) Instead, I typed
+\begin{quote}
+ ~\section[Line number references]~\\
+ ~ {Line number references\linelabel{ll1}}~
+\end{quote}
+This works fine, with the standard \LaTeX\ ~{article}~ document
+style. If more generic markup is required, you should avoid things
+like this (you should avoid \lineno.sty altogether, in that case).
+
+~\linelabel~ does not work in display math. (Why, you do not use
+equation numbers?)
+
+The ~\linelabel~ command starts a new paragraph if it is issued after
+an empty line. It will properly ignore further whitespace before the
+first word of text. Thus you can easily get a label to the first line
+of a paragraph.
+
+Furthermore, ~\linelabel~ uses \LaTeX s standart tricks to avoid
+unnecessary spaces if you place is between two words with spaces
+around, but you should not do that anyway, if you want to make sure
+that the label applies to a certain word in the text. You should
+attach the line label to the word in question without intervening
+spaces, either before of after the word. If you leave spaces both
+before and after the ~\linelabel~ command, the current implemenation
+attaches the line label to the following word (by ignoring the
+trailing space).
+
+Special care should be taken at the end of a paragraph. You better
+put the line label without intervening spaces behind the period, like
+this
+\begin{quote}
+ ~This is the end of this section.%~\\
+ ~\linelabel{ll2}~
+\end{quote}
+This is the end of this section.%
+\linelabel{ll2}
+
+\end{pagewiselinenumbers}
+
+\begin{linenumbers*}
+
+
+\section{Known incompatibilities}
+
+This section will expand whenever somebody discovers problems when
+using \lineno.sty together with other \LaTeX\ packages.
+
+\subsection{\texttt{wrapfig.sty}}
+
+\lineno.sty used to have problems with \texttt{wrapfig.sty}, but this
+is solved but \lineno.sty, version 2.05.
+
+
+\section{Extension packages}
+
+The extension packages were abolished with version v3.00 of
+\lineno.sty. One package, ~itemrule.sty~, was dropped, the others
+were put directly into the the main \lineno.sty package file.
+
+\subsection{Display math, \texttt{\itshape mlineno}}
+
+\lineno.sty does not work well with display math. The parts of a
+paragraph preceeding a display math will not get line numbers. The
+reason is that the paragraph is not finished, but the part above the
+display is broken into lines anyway.
+
+Let me demonstrate the effect. This paragraph contains a
+~{displaymath}~ environment. The part before the Formula does not get
+line numbers. Here comes the Formula
+\begin{displaymath}
+ \mathrm{6\,H_2O + 6\,CO_2 \ \rightarrow\ C_6H_{12}O_6 + 6\,O_2}
+\end{displaymath}
+which makes the line numbers disappear. The trailing part of the
+paragraph does get line numbers.
+
+There are several means to solve the problem, but none of them is
+fully satisfactory. \lineno.sty defines a ~{linenomath}~ environment,
+which can be wrapped around a display math to make the line numbering
+work. This will work with any kind of display math, even if you use
+explicit ~$$~ pairs. There is a ~*~-form ~{linenomath*}~ which also
+numbers the lines of the display itself, as good as it can. Here
+comes an example use of ~{linenomath*}~
+\begin{linenomath*}
+\begin{eqnarray*}
+ b_1 &=& a_{11}x_1 + a_{12}x_2 \\
+ b_2 &=& a_{21}x_1 + a_{22}x_2
+\end{eqnarray*}
+\end{linenomath*}
+wrapping an ~{egnarray*}~ like this
+\begin{quote}
+ ~\begin{linenomath*}~\\
+ ~ \begin{eqnarray*}~\\
+ ~ b_1 &=& a_{11}x_1 + a_{12}x_2 \\~\\
+ ~ b_2 &=& a_{21}x_1 + a_{22}x_2~\\
+ ~ \end{eqnarray*}~\\
+ ~\end{linenomath*}~
+\end{quote}
+Specifying the package option ~[mathlines]~, causes the
+~{linenomath}~ environment to switch its function with its *-form.
+This allows you to later decide if you want the numbers on the formulas
+or not, without putting in stars everywhere (as long as you have been
+consistent).
+
+The ~{linenomath}~ wrapper does nothing if line numbering is not
+activated. You do not need to remove them if you decide to omit the
+line numbering later (although you still have to load \lineno.sty).
+
+The \texttt{\itshape mlineno} extension redefines the standard \LaTeX\
+display math environments to wrap themselves automatically into
+~{linenomath}~:
+\begin{quote}\obeylines
+ ~\[~ ~\]~
+ ~{displaymath}~
+ ~{equation}~
+ ~{eqnarray}~
+ ~{eqnarray*}~
+\end{quote}
+As of version 3.00 you can activate this by the package option
+~[displaymath]~. You can keep existing explicit ~{linenomath}~
+wrappers without harm.
+
+This will probably not work with AMSmath.
+
+Other solutions to make \lineno.sty work with display math are either
+ugly or less stable. The ugly possibility is to precede every display
+math with an empty line, or better with
+\begin{quote}
+ ~{\par\nobreak\noindent}~
+\end{quote}
+but this gains you nothing compared to using the ~{linenomath}~
+environment, since you still have to modify your document.
+
+\end{linenumbers*}
+
+
+\subsection{\texttt{\itshape rlineno}}
+
+\begin{runninglinenumbers}
+It is currently not possible to put a ~\linelabel~ into math mode.
+This should not impose problems with inline math, since you can attach
+the label just outside the math shift, like\linelabel{rll1}
+\begin{quote}
+ ~... \linelabel{~<label>~}$x=f(y)$ ...~
+\end{quote}
+but to refer to a line in display math, you cannot label it directly.
+\end{runninglinenumbers}
+
+\begin{pagewiselinenumbers}
+The extension \texttt{\itshape rlineno} offers a solution,
+allowing to refer to a line number with an offset.
+
+This extension is now available with plain \lineno.sty v3.00.
+
+You put the ~\linelabel~ at the end of the preceeding line, and refer
+to that number, plus 1 or, in case of multiline displays, by any other
+offset.\linelabel{rll2}
+\begin{quote}
+ ~...\linelabel{~<label>~}~ \\
+ ~\begin{equation}~ \\
+ ~ y=f'(x)~ \\
+ ~\end{equation}~ \\
+ ~... the formula in line \lineref[+1]{~<label>~}~
+\end{quote}
+The offset calculation is different for pagewise or running line
+numbers, and you will have to make sure the right method is used.
+\end{pagewiselinenumbers}
+
+The macro ~\lineref[~<offset>~]{~<label>~}~ uses the method of the
+currently selected mode (line numbering need not be activated). To
+specify the mode explicitly, use ~\linerefr~ or ~\linerefp~ for
+running or pagewise mode respectively.
+
+For example, the manual sets a ~\linelabel{rll1}~ at the end of the
+line preceeding the single line quote environment at
+line\,\linerefr[+1]{rll1} in the first paragraph of this chapter, and
+refered to it via
+\begin{quote}
+ ~\linerefr[+1]{rll1}~
+\end{quote}
+and another one preceeding the quote environment in the second
+paragraph of this chapter, with the central line
+numbered\,\linerefp[+3]{rll2}, which I just refered to via
+\begin{quote}
+ ~\linerefp[+3]{rll2}~
+\end{quote}
+\begin{runninglinenumbers}
+If the correct mode is selected (e.g., ~\setrunninglinenumbers~),
+you can use ~\lineref[+1]{rll1}~ to refer to
+line\,\lineref[+1]{rll1}.
+\end{runninglinenumbers}
+
+
+\subsection{\texttt{\itshape numquote}}
+
+This extension defines two environments, each of them with a *-form or
+alternatively an optional argument.
+\begin{quote}\obeylines
+ ~\begin{numquote}~
+ ~\end{numquote}~
+\end{quote}
+is like ~{quote}~,
+\begin{quote}\obeylines
+ ~\begin{numquotation}~
+ ~\end{numquotation}~
+\end{quote}
+is like ~{quotation}~, but with the lines numbered. Numbering
+restarts with 1 each time it is used, except you use the *-form, or
+specify the line number to start with in an optional argument.
+\begin{numquote}
+The line numbers set to the left of the text, indented by the same
+amount as the quote or quotation. This works as expected even if the
+quote appears in a nested list.
+\end{numquote}
+To customize the distance from the text or the shape of the
+numbers, you can modify the macros ~\quotelinenumbersep~ and
+~\quotelinenumberfont~ respectively.
+
+As of version 3.00, this is available directly with \lineno.sty.
+
+\clearpage
+
+\subsection{\texttt{\itshape ilineno}}
+\label{sec:ilineno}
+
+\begin{center}
+\noindent\fbox{\parbox{0.8\textwidth}{
+ \internallinenumbers \resetlinenumber[13]
+ Sometimes you need line numbers within a |\parbox\ or figure. This
+ extension can do that, if the text is simple enough. It works by
+ drawing a ladder of numbers next to the paragraph, each number
+ vertically separated by |\baselineskip\ from the other. This
+ obviously dose not work nicely with anything but straight text.
+ Extra high lines (like this: $\displaystyle x=\frac AB$) will
+ disturb the alignment. The power of \lineno.sty is not necessary to
+ achieve this, but you may need both in one document with a somewhat
+ coherent interface, and some of the necessary infrastructure from
+ \lineno.sty is actually useful.
+}}\end{center}
+% Why is the v-spacing wrong here?
+
+The preceding paragraph was set like this:
+\begin{quote}
+ ~\begin{center}\fbox{\parbox{0.8\textwidth}{~ \\
+ ~\internallinenumbers~ \\
+ ~\resetlinenumber[13]~ \\
+ ~ ~ Sometimes you need \dots \\
+ ~}}\end{center}~
+\end{quote}
+
+\subsection{\texttt{\itshape itemrule.sty}}
+
+Somebody asked me if he can get a rule next to an itemized item, from
+the bullet downwards. This style did that. It was unstable and of
+little interest, so it is gone from the \lineno.sty distribution.
+
+\subsection{\texttt{\itshape bframe}}
+\label{sec:bframe}
+
+\setlength\bframesep{10pt}
+\begin{bframe}
+\lineno.sty can be used for unexpected purposes. The environment
+\begin{quote}\obeylines
+ ~\begin{bframe}~
+ ~\end{bframe}~
+\end{quote}
+draws boxes around some text, even across page breaks. At a page
+break, the box is open (it is difficult to fix that). There are two
+parameters:
+\begin{description}\itemsep=0pt\parskip=0pt
+\item [|\bframesep] \leavevmode\\
+ defines the separation of the box from the text.
+\item [|\bframerule] \leavevmode\\
+ defines the thickness of the lines around the text.
+\end{description}
+
+It works by asking \lineno.sty to draw small rules left and right to
+the lines. The total height of the rules is ~\baselineskip~ plus
+~\bframesep~. This leaves some extra space for extra high lines.
+
+The current version is very preliminary. In a future version there
+may be a possibility to move the vertical lines inwards for indented
+text. The box may optionally be closed at page breaks. It will not
+likely be possible to have a colored background in the box, at least
+not with a graphics driver that cannot put a background behind
+existing foreground (Postscript cannot, I've been told). Tell me how
+to make a gray background, like block dots on transparent, and I can
+do shaded boxes.
+
+\end{bframe}
+
+\section{How to print the documented source}
+
+\begin{bframe}
+\lineno.sty is written in three programming languages: \TeX, sh,
+and awk.
+
+The file can be loaded as a \LaTeXe\ package as it is. However, if
+you feed it into a Unix shell, like
+\begin{quote}
+ ~csh> source ./lineno.sty~
+\end{quote}
+it will produce the files ~lineno.tex~ and ~lineno.dvi~, which is the
+documented source of \lineno.sty. If you want to learn how it works,
+or you need to adapt \lineno.sty for some special requirements, you
+should read that document.
+\end{bframe}
+
+\end{document}
diff --git a/doc/Volumes.cpp b/doc/Volumes.cpp
deleted file mode 100644
index b5d3d8116e4045a02d2ca08e91add9171b05f282..0000000000000000000000000000000000000000
--- a/doc/Volumes.cpp
+++ /dev/null
@@ -1,395 +0,0 @@
-// $Id: Volumes.cpp 574 2013-05-17 20:38:31Z markus.frank $
-//====================================================================
-// AIDA Detector description implementation for LCD
-//--------------------------------------------------------------------
-//
-// Author : M.Frank
-//
-//====================================================================
-
-// Framework include files
-#include "DD4hep/LCDD.h"
-#include "DD4hep/InstanceCount.h"
-
-// ROOT include files
-#include "TColor.h"
-#include "TGeoShape.h"
-#include "TGeoVolume.h"
-#include "TGeoNode.h"
-#include "TGeoMatrix.h"
-#include "TGeoMedium.h"
-#include "TGeoVoxelFinder.h"
-#include "TGeoShapeAssembly.h"
-
-// C/C++ include files
-#include <climits>
-#include <iostream>
-#include <stdexcept>
-#include <sstream>
-
-using namespace std;
-using namespace DD4hep::Geometry;
-
-/// Default constructor
-PlacedVolume::Object::Object() : refCount(0), magic(0), volIDs() {
- InstanceCount::increment(this);
-}
-
-/// Copy constructor
-PlacedVolume::Object::Object(const Object& c) : refCount(0), magic(c.magic), volIDs(c.volIDs) {
- InstanceCount::increment(this);
-}
-
-/// Default destructor
-PlacedVolume::Object::~Object() {
- InstanceCount::decrement(this);
-}
-
-/// TGeoExtension overload: Method called whenever requiring a pointer to the extension
-TGeoExtension* PlacedVolume::Object::Grab() const {
- Object* ext = const_cast<Object*>(this);
- ++ext->refCount;
- return ext;
-}
-
-/// TGeoExtension overload: Method called always when the pointer to the extension is not needed anymore
-void PlacedVolume::Object::Release() const {
- Object* ext = const_cast<Object*>(this);
- --ext->refCount;
- if ( 0 == ext->refCount ) delete ext;
-}
-
-/// Lookup volume ID
-vector<PlacedVolume::VolID>::const_iterator
-PlacedVolume::VolIDs::find(const string& name) const {
- for(Base::const_iterator i=this->Base::begin(); i!=this->Base::end(); ++i)
- if ( name == (*i).first ) return i;
- return this->end();
-}
-
-/// Insert a new value into the volume ID container
-std::pair<vector<PlacedVolume::VolID>::iterator,bool>
-PlacedVolume::VolIDs::insert(const string& name, int value) {
- Base::iterator i = this->Base::begin();
- for(; i!=this->Base::end(); ++i)
- if ( name == (*i).first ) break;
- //
- if ( i != this->Base::end() ) {
- return make_pair(i,false);
- }
- i = this->Base::insert(this->Base::end(),make_pair(name,value));
- return make_pair(i,true);
-}
-
-/// Accessor to user structure
-PlacedVolume::Object& PlacedVolume::data() const {
- Object* o = (Object*)(ptr()->GetUserExtension());
- return *o;
-}
-
-/// Add identifier
-PlacedVolume& PlacedVolume::addPhysVolID(const string& name, int value) {
- data().volIDs.push_back(VolID(name,value));
- return *this;
-}
-
-/// Volume material
-Material PlacedVolume::material() const
-{ return Material::handle_t(m_element ? m_element->GetMedium() : 0); }
-
-/// Logical volume of this placement
-Volume PlacedVolume::volume() const
-{ return Volume::handle_t(m_element ? m_element->GetVolume() : 0); }
-
-/// Parent volume (envelope)
-Volume PlacedVolume::motherVol() const
-{ return Volume::handle_t(m_element ? m_element->GetMotherVolume() : 0); }
-
-/// Access to the volume IDs
-const PlacedVolume::VolIDs& PlacedVolume::volIDs() const
-{ return data().volIDs; }
-
-/// String dump
-string PlacedVolume::toString() const {
- stringstream s;
- Object& obj = data();
- s << m_element->GetName() << ": vol='" << m_element->GetVolume()->GetName()
- << "' mat:'" << m_element->GetMatrix()->GetName() << "' volID[" << obj.volIDs.size() << "] ";
- for(VolIDs::const_iterator i=obj.volIDs.begin(); i!=obj.volIDs.end();++i)
- s << (*i).first << "=" << (*i).second << " ";
- s << ends;
- return s.str();
-}
-
-/// Default constructor
-Volume::Object::Object() : refCount(0), magic(0), region(), limits(), vis(), sens_det() {
- InstanceCount::increment(this);
-}
-
-/// Default destructor
-Volume::Object::~Object() {
- vis.clear();
- region.clear();
- limits.clear();
- sens_det.clear();
- InstanceCount::decrement(this);
-}
-
-/// TGeoExtension overload: Method called whenever requiring a pointer to the extension
-TGeoExtension* Volume::Object::Grab() const {
- Object* ext = const_cast<Object*>(this);
- ++ext->refCount;
- return ext;
-}
-
-/// TGeoExtension overload: Method called always when the pointer to the extension is not needed anymore
-void Volume::Object::Release() const {
- Object* ext = const_cast<Object*>(this);
- --ext->refCount;
- if ( 0 == ext->refCount ) {
- delete ext;
- }
- else {
- cout << "Volume::Object::Release::refCount:" << ext->refCount << endl;
- }
-}
-
-/// Constructor to be used when creating a new geometry tree.
-Volume::Volume(const string& name) {
- m_element = new TGeoVolume();
- m_element->SetName(name.c_str());
- m_element->SetUserExtension(new Object());
-}
-
-/// Constructor to be used when creating a new geometry tree. Also sets materuial and solid attributes
-Volume::Volume(const string& name, const Solid& s, const Material& m) {
- m_element = new TGeoVolume(name.c_str(), s.ptr(), m.ptr());
- m_element->SetUserExtension(new Object());
-}
-
-/// Accessor to user structure
-Volume::Object& Volume::data() const {
- Object* o = (Object*)(ptr()->GetUserExtension());
- return *o;
-}
-
-/// Set the volume's material
-void Volume::setMaterial(const Material& m) const {
- if ( m.isValid() ) {
- TGeoMedium* medium = m._ptr<TGeoMedium>();
- if ( medium ) {
- m_element->SetMedium(medium);
- return;
- }
- throw runtime_error("Volume: Medium "+string(m.name())+" is not registered with geometry manager.");
- }
- throw runtime_error("Volume: Attempt to assign invalid material.");
-}
-
-static PlacedVolume _addNode(TGeoVolume* par, TGeoVolume* daughter, TGeoMatrix* transform) {
- TGeoVolume* parent = par;
- TObjArray* a = parent->GetNodes();
- Int_t id = a ? a->GetEntries() : 0;
- if ( transform && transform != identityTransform() ) {
- string nam = string(daughter->GetName())+"_placement";
- transform->SetName(nam.c_str());
- }
- parent->AddNode(daughter,id,transform);
- TGeoNodeMatrix* n = dynamic_cast<TGeoNodeMatrix*>(parent->GetNode(id));
- PlacedVolume pv(n);
- pv->SetUserExtension(new PlacedVolume::Object());
- return pv;
-}
-
-static TGeoTranslation* _translation(const Position& pos) {
- return new TGeoTranslation("",pos.X()*MM_2_CM,pos.Y()*MM_2_CM,pos.Z()*MM_2_CM);
-}
-
-static TGeoRotation* _rotation(const Rotation& rot) {
- return new TGeoRotation("",rot.Phi()*RAD_2_DEGREE,rot.Theta()*RAD_2_DEGREE,rot.Psi()*RAD_2_DEGREE);
-}
-
-/// Place daughter volume according to generic Transform3D
-PlacedVolume Volume::placeVolume(const Volume& volume, const Transform3D& tr) const {
- Rotation rot;
- Position pos;
- tr.GetDecomposition(rot,pos);
- return placeVolume(volume,rot,pos);
-}
-
-/// Place translated and rotated daughter volume
-PlacedVolume Volume::placeVolume(const Volume& volume, const Position& pos, const Rotation& rot) const {
- if ( volume.isValid() ) {
- TGeoCombiTrans* transform = new TGeoCombiTrans("",pos.X()*MM_2_CM,pos.Y()*MM_2_CM,pos.Z()*MM_2_CM,_rotation(rot));
- return _addNode(m_element,volume,transform);
- }
- throw runtime_error("Volume: Attempt to assign an invalid physical volume.");
-}
-
-/// Place daughter volume in rotated and then translated mother coordinate system
-PlacedVolume Volume::placeVolume(const Volume& volume, const Rotation& rot, const Position& pos) const {
- if ( volume.isValid() ) {
- TGeoHMatrix *trans = new TGeoHMatrix();
- double t[3];
- trans->RotateZ(rot.Phi()*RAD_2_DEGREE);
- trans->RotateY(rot.Theta()*RAD_2_DEGREE);
- trans->RotateX(rot.Psi()*RAD_2_DEGREE);
- pos.GetCoordinates(t);
- trans->SetDx(t[0]*MM_2_CM);
- trans->SetDy(t[1]*MM_2_CM);
- trans->SetDz(t[2]*MM_2_CM);
- return _addNode(m_element,volume,trans);
- }
- throw runtime_error("Volume: Attempt to assign an invalid physical volume.");
-}
-
-/// Place un-rotated daughter volume at the given position.
-PlacedVolume Volume::placeVolume(const Volume& volume, const Position& pos) const {
- if ( volume.isValid() ) {
- return _addNode(m_element,volume,_translation(pos));
- }
- throw runtime_error("Volume: Attempt to assign an invalid physical volume.");
-}
-
-/// Place rotated daughter volume. The position is automatically the identity position
-PlacedVolume Volume::placeVolume(const Volume& volume, const Rotation& rot) const {
- if ( volume.isValid() ) {
- return _addNode(m_element,volume,_rotation(rot));
- }
- throw runtime_error("Volume: Attempt to assign an invalid physical volume.");
-}
-
-/// Place daughter volume. The position and rotation are the identity
-PlacedVolume Volume::placeVolume(const Volume& volume, const IdentityPos& /* pos */) const {
- if ( volume.isValid() ) {
- return _addNode(m_element,volume,identityTransform());
- }
- throw runtime_error("Volume: Attempt to assign an invalid physical volume.");
-}
-
-/// Place daughter volume. The position and rotation are the identity
-PlacedVolume Volume::placeVolume(const Volume& volume, const IdentityRot& /* rot */) const {
- if ( volume.isValid() ) {
- return _addNode(m_element,volume,identityTransform());
- }
- throw runtime_error("Volume: Attempt to assign an invalid physical volume.");
-}
-
-/// Set Visualization attributes to the volume
-void Volume::setVisAttributes(const VisAttr& attr) const {
- if ( attr.isValid() ) {
- VisAttr::Object* vis = attr.data<VisAttr::Object>();
- Color_t bright = TColor::GetColorBright(vis->color);
- Color_t dark = TColor::GetColorDark(vis->color);
- int draw_style = vis->drawingStyle;
- int line_style = vis->lineStyle;
- m_element->SetLineColor(dark);
- if ( draw_style == VisAttr::SOLID ) {
- m_element->SetFillColor(bright);
- m_element->SetFillStyle(1001); // Root: solid
- }
- else {
- m_element->SetFillColor(0);
- m_element->SetFillStyle(0); // Root: hollow
- }
- if ( line_style == VisAttr::SOLID )
- m_element->SetFillStyle(1);
- else if ( line_style == VisAttr::DASHED )
- m_element->SetFillStyle(2);
- else
- m_element->SetFillStyle(line_style);
-
- m_element->SetLineWidth(10);
- m_element->SetVisibility(vis->visible ? kTRUE : kFALSE);
- m_element->SetAttBit(TGeoAtt::kVisContainers,kTRUE);
- m_element->SetVisDaughters(vis->showDaughters ? kTRUE : kFALSE);
- }
- data().vis = attr;
-}
-
-/// Set Visualization attributes to the volume
-void Volume::setVisAttributes(const LCDD& lcdd, const string& name) const {
- if ( !name.empty() ) {
- VisAttr attr = lcdd.visAttributes(name);
- data().vis = attr;
- setVisAttributes(attr);
- }
- else {
- /*
- string tag = this->name();
- if ( ::strstr(tag.c_str(),"_slice") ) // Slices turned off by default
- setVisAttributes(lcdd.visAttributes("InvisibleNoDaughters"));
- else if ( ::strstr(tag.c_str(),"_layer") ) // Layers turned off, but daughters possibly visible
- setVisAttributes(lcdd.visAttributes("InvisibleWithDaughters"));
- else if ( ::strstr(tag.c_str(),"_module") ) // Tracker modules similar to layers
- setVisAttributes(lcdd.visAttributes("InvisibleWithDaughters"));
- else if ( ::strstr(tag.c_str(),"_module_component") ) // Tracker modules similar to layers
- setVisAttributes(lcdd.visAttributes("InvisibleNoDaughters"));
- */
- }
-}
-
-/// Attach attributes to the volume
-void Volume::setAttributes(const LCDD& lcdd,
- const string& region,
- const string& limits,
- const string& vis) const
-{
- if ( !region.empty() ) setRegion(lcdd.region(region));
- if ( !limits.empty() ) setLimitSet(lcdd.limitSet(limits));
- setVisAttributes(lcdd,vis);
-}
-
-/// Set the volume's solid shape
-void Volume::setSolid(const Solid& solid) const
-{ m_element->SetShape(solid); }
-
-/// Set the regional attributes to the volume
-void Volume::setRegion(const Region& obj) const
-{ data().region = obj; }
-
-/// Set the limits to the volume
-void Volume::setLimitSet(const LimitSet& obj) const
-{ data().limits = obj; }
-
-/// Assign the sensitive detector structure
-void Volume::setSensitiveDetector(const SensitiveDetector& obj) const {
- //cout << "Setting sensitive detector '" << obj.name() << "' to volume:" << ptr() << " " << name() << endl;
- data().sens_det = obj;
-}
-
-/// Access to the handle to the sensitive detector
-Ref_t Volume::sensitiveDetector() const
-{ return data().sens_det; }
-
-/// Accessor if volume is sensitive (ie. is attached to a sensitive detector)
-bool Volume::isSensitive() const
-{ return data().sens_det.isValid(); }
-
-/// Access to Solid (Shape)
-Solid Volume::solid() const
-{ return Solid((*this)->GetShape()); }
-
-/// Access to the Volume material
-Material Volume::material() const
-{ return Ref_t(m_element->GetMedium()); }
-
-/// Access the visualisation attributes
-VisAttr Volume::visAttributes() const
-{ return data().vis; }
-
-/// Access to the handle to the region structure
-Region Volume::region() const
-{ return data().region; }
-
-/// Access to the limit set
-LimitSet Volume::limitSet() const
-{ return data().limits; }
-
-/// Constructor to be used when creating a new geometry tree.
-Assembly::Assembly(const string& name) {
- Object* ext = new Object();
- m_element = new TGeoVolumeAssembly(name.c_str());
- m_element->SetUserExtension(ext);
-}
-
diff --git a/doc/Volumes.h b/doc/Volumes.h
deleted file mode 100644
index c6b5ecaf802ce38e03aeaf9916673936d302b494..0000000000000000000000000000000000000000
--- a/doc/Volumes.h
+++ /dev/null
@@ -1,261 +0,0 @@
-// $Id: Volumes.h 574 2013-05-17 20:38:31Z markus.frank $
-//====================================================================
-// AIDA Detector description implementation for LCD
-//--------------------------------------------------------------------
-//
-// Author : M.Frank
-//
-//====================================================================
-
-#ifndef DD4hep_GEOMETRY_VOLUMES_H
-#define DD4hep_GEOMETRY_VOLUMES_H
-
-// Framework include files
-#include "DD4hep/Handle.h"
-#include "DD4hep/Shapes.h"
-#include "DD4hep/Objects.h"
-
-// C/C++ include files
-#include <map>
-
-// ROOT include file (includes TGeoVolume + TGeoShape)
-#include "TGeoNode.h"
-#include "TGeoExtension.h"
-#include "TGeoPatternFinder.h"
-
-/*
- * DD4hep namespace declaration
- */
-namespace DD4hep {
-
- /*
- * Geometry namespace declaration
- */
- namespace Geometry {
-
- // Forward declarations
- struct LCDD;
- struct Region;
- struct LimitSet;
- struct Material;
- struct VisAttr;
- struct Volume;
- struct PlacedVolume;
- struct SensitiveDetector;
-
- /** @class PlacedVolume Volume.h DD4hep/lcdd/Volume.h
- *
- * @author M.Frank
- * @version 1.0
- */
- struct PlacedVolume : Handle<TGeoNodeMatrix> {
- typedef std::pair<std::string,int> VolID;
- struct VolIDs : public std::vector<VolID> {
- typedef std::vector<VolID> Base;
- VolIDs() : Base() {}
- ~VolIDs () {}
- Base::const_iterator find(const std::string& name) const;
- std::pair<Base::iterator,bool> insert(const std::string& name, int value);
- };
- struct Object : public TGeoExtension {
- /// Reference count on object (used to implement Grab/Release)
- long refCount;
- /// Magic word
- unsigned long magic;
- /// ID container
- VolIDs volIDs;
- /// Default constructor
- Object();
- /// Copy constructor
- Object(const Object& c);
- /// Default destructor
- virtual ~Object();
- /// Assignment operator
- Object& operator=(const Object& c) {
- volIDs = c.volIDs;
- magic = c.magic;
- return *this;
- }
- /// TGeoExtension overload: Method called whenever requiring a pointer to the extension
- virtual TGeoExtension *Grab() const;
- /// TGeoExtension overload: Method called always when the pointer to the extension is not needed anymore
- virtual void Release() const;
- };
- /// Default constructor
- PlacedVolume() : Handle<TGeoNodeMatrix>() {}
- /// Constructor to be used when reading the already parsed DOM tree
- PlacedVolume(const TGeoNode* e) : Handle<TGeoNodeMatrix>(e) {}
- /// Copy assignment
- PlacedVolume(const PlacedVolume& e) : Handle<TGeoNodeMatrix>(e) {}
- /// Copy assignment from other handle type
- template <typename T> PlacedVolume(const Handle<T>& e) : Handle<TGeoNodeMatrix>(e) {}
- /// Assignment operator (must match copy constructor)
- PlacedVolume& operator=(const PlacedVolume& v) { m_element=v.m_element; return *this; }
-
- /// Accessor to user structure
- Object& data() const;
-
- /// Add identifier
- PlacedVolume& addPhysVolID(const std::string& name, int value);
- /// Volume material
- Material material() const;
- /// Logical volume of this placement
- Volume volume() const;
- /// Parent volume (envelope)
- Volume motherVol() const;
- /// Access to the volume IDs
- const VolIDs& volIDs() const;
- /// String dump
- std::string toString() const;
- };
-
- /** @class Volume Volume.h DD4hep/lcdd/Volume.h
- *
- * Handle describing a Volume
- *
- * @author M.Frank
- * @version 1.0
- */
- struct Volume : public Handle<TGeoVolume> {
-
- public:
- typedef Handle<TGeoVolume> Base;
- struct Object : public TGeoExtension {
- /// Reference count on object (used to implement Grab/Release)
- long refCount;
- /// Magic word
- unsigned long magic;
- Region region;
- LimitSet limits;
- VisAttr vis;
- Ref_t sens_det;
- /// Default constructor
- Object();
- /// Default destructor
- virtual ~Object();
- /// Object copy
- void copy(const Object& c) {
- magic = c.magic;
- region = c.region;
- limits = c.limits;
- vis = c.vis;
- sens_det = c.sens_det;
- }
- /// TGeoExtension overload: Method called whenever requiring a pointer to the extension
- virtual TGeoExtension *Grab() const;
- /// TGeoExtension overload: Method called always when the pointer to the extension is not needed anymore
- virtual void Release() const;
- };
-
- public:
- /// Default constructor
- Volume() : Base(0) {}
-
- /// Copy from handle
- Volume(const Volume& v) : Base(v) {}
-
- /// Copy from arbitrary Element
- template <typename T> Volume(const Handle<T>& v) : Base(v) {}
-
- /// Constructor to be used when creating a new geometry tree.
- Volume(const std::string& name);
-
- /// Constructor to be used when creating a new geometry tree. Also sets materuial and solid attributes
- Volume(const std::string& name, const Solid& s, const Material& m);
-
- /// Assignment operator (must match copy constructor)
- Volume& operator=(const Volume& a) { m_element=a.m_element; return *this; }
-
- /// Accessor to user structure
- Object& data() const;
-
- /// Place daughter volume. The position and rotation are the identity
- PlacedVolume placeVolume(const Volume& vol) const
- { return placeVolume(vol,IdentityPos()); }
- /// Place daughter volume according to generic Transform3D
- PlacedVolume placeVolume(const Volume& volume, const Transform3D& tr) const;
- /// Place un-rotated daughter volume at the given position.
- PlacedVolume placeVolume(const Volume& vol, const Position& pos) const;
- /// Place rotated daughter volume. The position is automatically the identity position
- PlacedVolume placeVolume(const Volume& vol, const Rotation& rot) const;
- /// Place rotated and then translated daughter volume
- PlacedVolume placeVolume(const Volume& vol, const Position& pos, const Rotation& rot) const;
- /// Place daughter volume in rotated and then translated mother coordinate system
- PlacedVolume placeVolume(const Volume& vol, const Rotation& rot, const Position& pos) const;
-
- /// Place daughter volume. The position and rotation are the identity
- PlacedVolume placeVolume(const Volume& vol, const IdentityPos& pos) const;
- /// Place daughter volume. The position and rotation are the identity
- PlacedVolume placeVolume(const Volume& vol, const IdentityRot& pos) const;
-
- /// Attach attributes to the volume
- void setAttributes(const LCDD& lcdd,
- const std::string& region,
- const std::string& limits,
- const std::string& vis) const;
-
- /// Set the regional attributes to the volume
- void setRegion(const Region& obj) const;
- /// Access to the handle to the region structure
- Region region() const;
-
- /// Set the limits to the volume
- void setLimitSet(const LimitSet& obj) const;
- /// Access to the limit set
- LimitSet limitSet() const;
-
- /// Set Visualization attributes to the volume
- void setVisAttributes(const VisAttr& obj) const;
- /// Set Visualization attributes to the volume
- void setVisAttributes(const LCDD& lcdd, const std::string& name) const;
- /// Access the visualisation attributes
- VisAttr visAttributes() const;
-
- /// Assign the sensitive detector structure
- void setSensitiveDetector(const SensitiveDetector& obj) const;
- /// Access to the handle to the sensitive detector
- Ref_t sensitiveDetector() const;
- /// Accessor if volume is sensitive (ie. is attached to a sensitive detector)
- bool isSensitive() const;
-
- /// Set the volume's solid shape
- void setSolid(const Solid& s) const;
- /// Access to Solid (Shape)
- Solid solid() const;
-
- /// Set the volume's material
- void setMaterial(const Material& m) const;
- /// Access to the Volume material
- Material material() const;
-
- /// Auto conversion to underlying ROOT object
- operator TGeoVolume*() const { return m_element; }
- };
-
- /** @class Assembly Volume.h DD4hep/lcdd/Volume.h
- *
- * Handle describing a volume assembly
- *
- * @author M.Frank
- * @version 1.0
- */
- struct Assembly : public Volume {
- /// Default constructor
- Assembly() : Volume() {}
-
- /// Copy from handle
- Assembly(const Assembly& v) : Volume(v) {}
-
- /// Copy from arbitrary Element
- template <typename T> Assembly(const Handle<T>& v) : Volume(v) {}
-
- /// Constructor to be used when creating a new geometry tree.
- Assembly(const std::string& name);
-
- /// Assignment operator (must match copy constructor)
- Assembly& operator=(const Assembly& a) { m_element=a.m_element; return *this; }
- };
-
- } /* End namespace Geometry */
-} /* End namespace DD4hep */
-#endif /* DD4hep_GEOMETRY_VOLUMES_H */
diff --git a/doc/update_doc.sh b/doc/update_doc.sh
new file mode 100755
index 0000000000000000000000000000000000000000..548b4839a2c37db547187b09167c1ff96a9ee72d
--- /dev/null
+++ b/doc/update_doc.sh
@@ -0,0 +1,21 @@
+#!/bin/bash
+DOC_SRC=/home/frankm/MyDocs/LCD/DD4hep;
+DOC_DD4HEP=./LaTex;
+
+if test ! -d ./LaTex;
+then
+ echo "";
+ echo "";
+ echo "$0 > The directory ${DOC_DD4HEP} does not exit! -- no action taken";
+ echo "";
+ echo "";
+else
+ echo "$0 > Copy images .....";
+ cp ${DOC_SRC}/*.png ${DOC_DD4HEP}/;
+ echo "$0 > Copy latex files .....";
+ cp ${DOC_SRC}/*.tex ${DOC_DD4HEP}/;
+ echo "$0 > Copy processed pdf files.....";
+ cp ${DOC_SRC}/*.pdf ${DOC_DD4HEP}/../;
+ echo "$0 > All done.";
+fi;
+