 |
 |
| Commit in docs/pubs/0001-lcdd on MAIN | |||
| lcdd-paper.tex | +200 | -99 | 3195 -> 3196 |
LCDD paper updates.
--- docs/pubs/0001-lcdd/lcdd-paper.tex 2014-07-18 08:45:26 UTC (rev 3195) +++ docs/pubs/0001-lcdd/lcdd-paper.tex 2014-07-18 23:21:17 UTC (rev 3196) @@ -35,6 +35,7 @@
\documentclass[preprint,12pt,3p]{elsarticle}
\usepackage{gensymb}
\usepackage{graphicx}
+\usepackage{amsmath}
\graphicspath{ {images/} }
%% Use the option review to obtain double line spacing
@@ -122,7 +123,7 @@
%% \[log in to unmask] \begin{abstract}
-Geant4 is a powerful software framework for simulating the interactions of particles with matter and fields. It has become the de facto standard for detector simulation in high energy physics (HEP) and is increasingly being applied in other disciplines, such as medical physics and applications in the aerospace industry. It is designed as a toolkit rather than a pre-packaged executable. An application must be assembled based upon the requirements of the project, requiring a considerable amount of expertise, both in the details of configuring the framework, and in the C++ language in which it is written. Providing a flexible application based on Geant4 which can meet the needs of many different users can alleviate these technical barriers. Ideally, the complete detector description is provided by a data format rather than a set of compiled classes. The Geometry Description Markup Language (GDML) provides an XML language with bindings to ! the core geometry classes of the Geant4 toolkit. [...]
+Geant4 is a software framework for simulating the interactions of particles with matter and fields. It has become the de facto standard for detector simulation in high energy physics and is increasingly being applied to other disciplines, such as medical physics and applications in the aerospace industry. Since Geant4 is designed as a toolkit, rather than a pre-packaged executable, an application must be assembled based upon the user's requirements, requiring a considerable amount of expertise, both in the details of configuring the framework, and in the C++ language. Providing a flexible application which can meet the needs of many different users can alleviate these technical barriers. Ideally, the complete detector description would be provided by a data format rather than a set of compiled classes. GDML provides an XML language for describing detector geometries, but completely describing an experimental apparatus requires much more ! than the just the geometry. We present here the[...]
\end{abstract}
%% \begin{keyword}
@@ -146,47 +147,111 @@
%% still need to know the Geant4 physics, e.g physics lists, regions, step size... %%
-Geant4 is a primary software framework in HEP, used to simulate the interaction of particles in matter and fields. Distributed as a set of source files and examples, the toolkit is used to assemble a domain-specific application based on experimental requirements. Typically, the most complex task is modeling the geometry and detectors, which for complex setups, may take hundreds, or even thousands of lines of code. This task can be daunting, as it requires a considerable level of expertise in the APIs and C++ language.
+Geant4 is a software framework developed for HEP, used to simulate the detailed interactions of particles in matter and fields. Distributed as a set of source files and examples, the toolkit is used to assemble a domain-specific application based upon experimental requirements. Typically, the most complex task is modeling the geometry and detectors, which for complex setups, may take hundreds, or even thousands of lines of code. This task can be daunting, as it requires a considerable level of expertise in the relevant APIs and the C++ language.
-When geometry is defined in code by directly programming against an API, the size of the code base tends to increase over time as more detectors are added. Each detector variant tends to require its own set of custom classes. The ``pure code'' approach can lead to severe maintenance issues: a great amount of code duplication between detector models; the treatment of specific geometries as a ``black box'' with no real accompanying data description; and a confusion and lack of separation between the procedural code and data.
+When geometries are defined by programming against an interface, the size of the code base will tend to increase greatly over time. Each major detector variant usually require its own set of classes. The ``pure code'' approach may lead to severe maintenance issues: a great amount of code duplication between different detector models; the treatment of specific geometries as a ``black boxes'' with no data description that is externally accessible; and a lack of separation between procedural code and data.
-Providing a comprehensive and flexible solution to these problems has been the goal of the Linear Collider Detector Description (LCDD) project. This framework was first introduced to simulate detector models for International Linear Collider (ILC) design studies and is now being used successfully by several other experiments. By providing a clear separation between code and detector description, researchers are freed from needing to know the complex details of the Geant4 APIs. They may instead focus on defining the detector setup for their particular experiment in a structured data language.
+Providing a comprehensive and flexible solution to these problems has been the goal of the Linear Collider Detector Description (LCDD) project. LCDD was introduced to simulate detector models for International Linear Collider (ILC) design studies. It is now being used successfully by several other groups to model their experiments. By providing a clear separation between the code and the detector description data, researchers are freed from needing to know the complex details of the Geant4 APIs. They may instead focus on defining the detector setup for their particular experiment using a structured data language.
-This paper will provide an overview of the LCDD language and framework. The LCDD extensions to GDML will be explained and described, with an example showing the full document structure. Each primary XML element type will be explained in detail along with an example of its usage. Examples will be given of projects that have used LCDD to model their experiments. Finally, future plans will be briefly discussed.
+This paper will provide an overview of the LCDD language and framework, with an example showing the full document structure. The extensions to GDML will be explained and described along with examples. Each primary XML element type will be explained in detail along with an example of its usage. Several projects will be briefly described that have used LCDD to model their experimental detectors. Finally, future plans will be discussed.
\section{GDML}
-The Geometry Description Markup Language (GDML) is an XML format for geometry description, allowing users to define hierarchical, geometric structures using a data language. GDML fully describes materials, mathematical variables and definitions, solids such as boxes and tubes, and a hierarchical structure of logical and physical volumes.
+The Geometry Description Markup Language (GDML) is an XML language for describing detector geometries using materials, mathematical variables and definitions, solids such as boxes and tubes, and a hierarchical structure of logical and physical volumes. Originally developed as a standalone application, GDML has become part of the Geant4 source distribution. Therefore, it serves as an ideal starting point for a complete detector description language.
-GDML's \textit{define} block contains expressions and definitions read into the CLHEP Expression Evaluator. These expressions may contain double precision numbers, simple arithmetic operators (* / + -), trigonometric functions, and units. The processor predefines a number of standard units for distance, weight, etc. Important primary constants such as the speed of light are also predefined. Rotations and positions that will be referenced later to create physical volumes may also be included in this section.
+GDML's \textit{define} block contains expressions and definitions that are composed of double precision numbers, simple arithmetic operators (* / + -), trigonometric functions, and units. The CLHEP expression evaluator is used to parse and evaluate these mathematical statements. The processor predefines a number of standard units for distance, weight, etc., as well as a set of constants such as the speed of light. Rotations and positions that will be referenced later to create physical volumes may also be included in this section.
-The \textit{materials} section has \textit{material} and \textit{element} elements that bind to the G4Material and G4Element classes for materials and atomic elements. Materials are defined by atomic or mass composition and density. Material parameter sheets may be attached to provide pre-computed values for dEdx calculations and optical properties.
+The \textit{materials} section has a list of \textit{material} and \textit{element} tags that bind to the G4Material and G4Element classes for materials and atomic elements. Materials are defined by atomic or mass composition and density. Material parameter sheets may be attached to provide pre-computed values for dEdx calculations and optical properties. Every logical volume in the geometry must have a material assigned to it.
-The \textit{solids} block contains a collection of shape definitions that are used in the geometry. Constructive Geometry Solids (CSG) are the most common type of shapes used in Geant4 geometries. (Boundary Represented Solids (BREPS) are also available but are not supported by the GDML system.) GDML has bindings to a large and nearly complete subset of the CSG solids defined by the Geant4 geometry subsystem, including tubes, boxes, trapezoids, tori, twisted tubes and boxes, polyhedra, and facetted shapes. Boolean subtraction and addition can be used with these primitives to define arbitrarily complex geometries.
+The \textit{solids} block contains a collection of shape definitions that are used within the geometry. GDML has bindings to a large and nearly complete subset of the Constructive Geometry Solids (CSG) solids defined by the Geant4 geometry module, including tubes, boxes, trapezoids, tori, twisted tubes and boxes, polyhedra, and facetted shapes. Boolean subtraction and addition can be used with these primitives to define arbitrarily complex geometries.
-The \textit{structure} block contains a nested hierarchy of geometric volumes. A volume is composed of a shape plus its material and may contain any number of sub-volumes, defined with the \textit{physvol} tag. The volumes in the \textit{physvol} elements are called "child" volumes of their "parent" volume. The child volumes must contain a reference to a logical volume, plus an in-lined or referenced position and rotation. The top-level volume or "world volume", typically a large box containing the detector envelope volume, is defined in the \textit{setup} block using the \textit{world} element.
+The \textit{structure} block contains a nested hierarchy of geometric volumes. A volume is composed of a shape plus its material and may contain any number of sub-volumes, each of which has its own \textit{physvol} tag. The volumes in the \textit{physvol} elements are called ``child'' volumes of their ``parent'' volume. The child volumes must contain a reference to a logical volume, plus an in-lined or referenced position and rotation. The top-level volume or ``world volume'', typically a large box containing the detector envelope volume, is defined in the \textit{setup} block using the \textit{world} element. This hierarchy of volumes thus defines the complete geometric structure for the detector simulation.
-A hierarchy of volumes thus defines the complete detector structure. Originally developed as a standalone application, GDML has become part of the Geant4 source distribution. It therefore serves as an ideal starting point for a complete detector description language. -
\section{LCDD}
-In addition to the geometric layout of an experiment, additional information is required to fully describe a valid detector setup at runtime. This complete set of data is usually called ``detector description.'' Frameworks that use a data language such as GDML for geometry description generally still require additional information. This might be provided by macro commands that define readouts and assign them to volumes. There are inherent problems and limitations to this approach. The supplementary information is not easily accessible, as it is embedded in relatively unstructured macro files. Using runtime commands to provide detector information can make it difficult to determine later from an external environment which detector simulation parameters were used to produce an output file, or what readout parameters should be associated to a particular detector component.
+In addition to the geometry of an experiment, additional information is required to describe a full detector setup at runtime. This complete set of data is usually called ``detector description.'' Frameworks that use a data language such as GDML for geometry description generally still require additional information about the detector. For instance, macro commands might be executed that define readouts and assign them to previously defined volumes. But there are inherent problems and limitations to this approach. The supplementary information is not easily accessible outside the application, as it is embedded in unstructured macro files, making it difficult to determine later from an external environment which detector simulation parameters were used to produce an output file, or what readout parameters should be associated to a particular detector component.
-A different approach is required to guarantee the consistency and integrity of the detector data. LCDD was designed to provide a complete description of complex experimental setups. Various types of detectors, ranging from simple test beams to complex HEP detectors, can be modeled to an arbitrary level of detail using an XML file rather than macros or detector-specific C++ code. LCDD is built upon the GDML data format and C++ parser. It extends GDML's data format by using built-in facilities of the XML Schema (XSD) language. The GDML infrastructure is reused by registering additional element handlers with its flexible parser class. The extended parser, without any alteration, can read in plain GDML files as well as LCDD.
+LCDD was designed to provide a complete description of complex experimental setups at runtime using an XML language. Various types of detectors, from simple test beams to full HEP detectors, can be modeled to an arbitrary level of detail using an XML file rather than macros or detector-specific C++ code. LCDD is built upon the GDML data format and its C++ parser, which is built using the Xerces \cite{xerces} XML framework. LCDD formally extends GDML by using built-in facilities of the XML Schema (XSD) language such as the \textit{xs:redefine} and \textit{xs:extension} elements. The GDML parsing infrastructure is reused by registering additional element handlers for LCDD types with its parser class. The extended parser is able to read in plain GDML, as well as LCDD.
-LCDD uses GDML to provide the geometric information for the simulation. The LCDD schema formally extends GDML using the \textit{extension} element of XSD, and the \textit{gdml} root node is embedded as part of the document. The GDML language is essentially left intact, with the main point of extension being the \textit{volume} element, which may contain optional references to additional LCDD elements defined outside of the GDML section. The volume can be associated with detector readouts, visualization parameters, a region, physics limits, and other supplementary information, to provide a complete description of the detector to the simulation engine.
+LCDD uses GDML to provide the complete geometry for the simulation. The \textit{gdml} root node is embedded as part of the LCDD document. The GDML language is essentially left intact with only minor additions, with the main point of extension being the \textit{volume} element, which may contain optional references to additional XML elements defined outside of the GDML section. Using this approach, a volume can be associated with a sensitive detector, visualization parameters, a region, physics limits, and other supplementary information.
+\subsection{Using LCDD in an Application}
+
+The LCDD framework implements G4VUserDetectorConstruction, which is a required class for user applications. This means that using LCDD is only a matter of registering this detector construction class with the Geant4 run manager.
+
+\begin{verbatim}
+theRunManager->SetUserInitialization(new LCDDDetectorConstruction());
+\end{verbatim}
+
+This will then allow the detector document to be specified using a macro command, such as the following, which will load a document from a remote URL.
+
+\begin{verbatim}
+/lcdd/url http://www.lcsim.org/detectors/sidloi3/sidloi3.lcdd
+\end{verbatim}
+
+Local files can also be read in by using the \textit{file://} protocol.
+
+\begin{verbatim}
+/lcdd/url file:///local/path/to/sidloi3.lcdd
+\end{verbatim}
+
+Arguments to this macro command without a protocol are interpreted as local files.
+
+\begin{verbatim}
+/lcdd/url /local/path/to/sidloi3.lcdd
+\end{verbatim}
+
+The detector document must be set in the pre-initialization phase, and then the geometry is setup when initialization occurs, either through calling the initialization method on the run manager directly or executing the \textit{/control/initialize} macro command.
+
+\subsection{Volume Element}
+
+LCDD extends GDML by adding additional, completely optional elements to the volume. (A plain GDML parser will simply ignore these unknown tags when processing the file or possibly emit warning messages.) Deriving valid GDML file from LCDD is therefore quite straightforward.
+
+The following example assigns to a volume a sensitive detector, set of physics limits, region, visualization attributes, and physics limits.
+
+\begin{verbatim}
+<volume name="EcalBarrel_layer0">
+ <materialref ref="Silicon"/>
+ <solidref ref="EcalBarrel_layer0_box"/>
+ <sdref ref="EcalBarrel"/>
+ <limitsetref ref="CalLimits"/>
+ <visref ref="CalVis"/>
+ <regionref ref="CalRegion"/>
+</volume>
+\end{verbatim}
+
+The LCDD objects referenced in this volume description are previously defined XML elements in the document. For example, the ``EcalBarrel'' sensitive detector is defined prior to the volume definition, and the parser will retrieve its object from an in-memory data structure and then assign the sensitive detector to the named volume. A similar strategy is used for the other objects referenced by the extended volume element. In this way, the supplementary information defined by LCDD can be assigned to the appropriate GDML \textit{volume} and \textit{physvol} elements.
+
+\subsection{Physical Volume IDs}
+
+Physical volumes in GDML are extended so that they may have one or more physical volume IDs. These values can be used in 64-bit identifiers that are attached to hits (described later).
+
+For instance, this is an example of assigning a layer number to a volume.
+
+\begin{verbatim}
+<volume name="DetectorEnvelope">
+ <materialref ref="Air"/>
+ solidref ref="DetectorEnvelopeBox"/>
+ <physvol>
+ <volumeref ref="LayerVolume"/>
+ <physvolid field_name="layer" value="1"/>
+ </phyvol>
+</volume>
+\end{verbatim}
+
+Any number of \textit{physvolid} elements can be assigned to a \textit{physvol}, so the assignment of these identifier values need not be limited by the hierarchical structure of the detector.
+
\subsection{Document Structure}
-The LCDD parser checks the input for correctness at runtime against an XML Schema, which is located at a standard URL and can be accessed over the internet via the \textit{http} protocol.
+The LCDD parser checks the input document for correctness against the XML Schema, which is located at a standard URL accessible over the internet via the \textit{http} protocol.
\begin{verbatim}
http://www.lcsim.org/schemas/lcdd/1.0/lcdd.xsd
\end{verbatim}
-Every LCDD file has the same basic structure. The top-level \textit{lcdd} element has a list of sections, one of which is an entire GDML geometry. Most of the other sections have a list of elements with a specific type for that container. The elements are referenced from the GDML in order to associate this additional detector description information to specific logical or physical volumes. This is achieved by an extension to the GDML volume element within LCDD's XML schema.
+Every LCDD file has the same basic structure that is enforced through XML schema checking at runtime against the document contents. The top-level \textit{lcdd} element has a list of sections, most of which contain a list of elements of a specific type such as sensitive detectors or regions. Each of these elements has a name assigned to it which is used as a unique ID within the document. There is a complete, embedded GDML geometry, and its volumes may reference previously defined LCDD elements such as sensitive detectors. In this way, the information in LCDD is linked by reference to volumes within GDML.
-The following snippet of pseudo-XML outlines the top-level structure of an LCDD file, including the embedded GDML element.
+The following snippet of pseudo-XML outlines the top-level structure of an LCDD file.
\begin{verbatim}
<lcdd>
@@ -207,11 +272,11 @@
</lcdd>
\end{verbatim}
-The header contains basic meta data about the document, such as a name that can be used an as external tag or ID of the detector. The \textit{iddict} is a collection of identifier dictionaries that provide encodings for packed, 64-bit IDs, that may contain information such as a layer number or a detector ID. The \textit{sensitive\_detectors} element defines Geant4 ``sensitive detectors'' that are assigned via reference to volumes, flagging them as readout components. This causes hits in that detector's volumes to be accumulated by event. The \textit{limits} are sets of physics limits which effect certain parameters in the physics engine, such as the maximum step size of a track. The \textit{display} element contains visualization settings that can be used to assign colors and visibility parameters to logical volumes. The \textit{gdml} tag is an entire, embedded GDML document, which must conform to that format's XML syntax. It may !
include additional elements that are defined in t[...]
+The header has basic meta data about the document, such as a name that can be used an as external tag or ID of the detector. (It is the only top-level element which has no significant level of sub-structure.) The \textit{iddict} is a collection of identifier dictionaries that provide encodings for packed, 64-bit IDs, which may contain encoded values such as a layer number or a detector ID. The \textit{sensitive\_detectors} element defines Geant4 sensitive detectors which are assigned to volumes, flagging them as readout components. Hits in that volume will be accumulated by event. The \textit{limits} are sets of physics limits that can be used to tune parameters in the physics engine, such as the maximum step size of a track. The \textit{display} element contains visualization settings that assign colors and other visibility parameters to logical volumes. The \textit{gdml} tag is an embedded GDML document, which must conform to that!
format's XML syntax. It may include the addit[...]
\section{Header Element}
-Every LCDD document begins with a header that provides basic meta data about the file and the detector.
+Every document begins with a header that provides basic meta data about the file and the detector.
\begin{verbatim}
<header>
@@ -223,15 +288,15 @@
</header>
\end{verbatim}
-The \textit{detector} XML element provides a name that can be used as an external ID. For instance, the name can be written into the run headers of output data files to identify which detector was used to generate it. An author tag gives the names of the people who created the file, as well as an optional email contact. The generator provides information about any external program that was used to generate the file, including a source file name, if applicable, a version of that program, and a checksum that could be created with an MD5 algorithm. Finally, there is a free-form comment block that may be used to provide a description and notes about the detector.
+The \textit{detector} tag provides a name attribute that can be used as an external ID. For instance, the name can be written into the run headers of output data files to identify which detector was used to generate those events. An \textit{author} element gives the names of the authors of the file, as well as an email contact. The generator provides information about an external program that was used to generate the file, if applicable, including a source file name, a version of that program, and a checksum that could be created with an MD5 algorithm. Finally, there is a comment block that may be used to provide additional descriptive text about the detector.
\section{Sensitive Detectors}
-A ``sensitive detector'', in Geant4 terminology, is assigned to a logical volume to indicate that it is a readout component which is capable of producing hits. When a particle deposits energy into that volume, hits are created that may later be written into an output file for analysis. (Providing these data formats is not one of LCDD's features.) The sensitive detectors typically accumulate position, time and energy measurements from particle interactions within the material of a volume. The hits are grouped into collections by their sensitive detector and are accumulated by event.
+A sensitive detector is assigned to a logical volume to designate it as a readout component that is capable of producing hits. When a particle deposits energy into that volume, hits are automatically created, which may later be written into an output file for analysis. (Providing these data formats is not one of LCDD's features.) The sensitive detectors accumulate position, time and energy measurements from particle interactions within the material. Hits are grouped into collections by their sensitive detector and are grouped by event.
-Two primary types of detectors are modeled by the framework. Trackers store output from the simulation that corresponds closely to individual steps within a volume. This information can be used later to reconstruct in detail the exact particle momentum at the hit location. Calorimeters are used to record the accumulation of energy within cellular volumes, and typically have much less granular position information. Their sensor volumes may be virtually segmented into cells using a child \textit{segmentation} element. There is also a third type of detector called a \textit{scorer} which is essentially a simplified tracker. It can be used to insert scoring planes to derive simple flux counts.
+Two primary types of detectors are modeled by the framework. Trackers store output from the simulation that corresponds closely to individual steps within a volume. This information can be used later to reconstruct in detail the exact particle momentum at the hit location. Calorimeters record the total accumulation of energy by event and typically have much less granular position information. Calorimeter volumes may be virtually segmented into cells using a \textit{segmentation} element. There is also a third type of detector called a \textit{scorer} which is essentially a simplified tracker. It can be used to insert scoring planes to derive simple flux counts.
-These types extend a common element which defines basic detector settings. The common settings for all \textit{sensitive\_detector} elements include the following.
+These sensitive detectors extend a common element which defines basic settings, including the following.
\begin{tabular}{ | l | l | }
\hline
@@ -243,15 +308,15 @@
\hline
\end{tabular}
-Each sensitive detector has a name that is used to uniquely identify it within the document. This is used to associate logical volumes with a particular sensitive detector using the \textit{sdref} element. There is a flag which indicates whether or not the detector is an end cap. (This is primarily a concept that is relevant for HEP collider-detectors.) An energy cut setting can be used to discard low-energy hits that do not reach a certain threshold. There is a verbosity setting to control print screen output from the detector while the simulation is running. The name of the detector is required, and the other settings are optional.
+Each sensitive detector has a name that is used to uniquely identify it within the document. The \textit{sdref} element uses this name in order to associate a volume with a sensitive detector. The name of the detector is required, and the other settings are optional. There is a flag which indicates whether or not the detector is an end cap. (This is primarily a concept that is relevant for HEP collider-detectors.) An energy cut can be used to discard low-energy hits that do not reach a certain threshold. There is a verbosity setting to control print screen output while the simulation is running e.g. for debugging.
-Each sensitive detector has an associated hits collection that contains objects which are implementations of Geant4's virtual hit class. There is no output data binding provided by LCDD itself to persist this information. It is assumed that applications which include LCDD as a dependency will translate from these hit objects into an output format such as LCIO \cite{lcio}.
+Each sensitive detector has one or more hits collection containing objects which are implementations of Geant4's virtual hit class, G4VHit. The \textit{CalorimeterHit} class is used to store hits in the calorimeters, and a list of \textit{HitContribution} objects keeps the information about each energy deposition made in a cell. The \textit{TrackerHit} class is used to store information from trackers. There is no output data binding provided by LCDD itself to persist this information. It is assumed that applications which include LCDD as a dependency would translate from the provided hit objects into an output format such as LCIO \cite{lcio}.
\subsection{Trackers}
-Trackers record information from each step of a simulated track as it propagates through a volume. The stored information includes the mid-point position, direction of the track at that point, length of the step, global time, and the energy deposited. A \textit{TrackerHit} object is created for each step and stored into a hit collection. The Tracker is most commonly used to model high-granularity readouts, such as pixels or silicon strips. Algorithms for digitizing the hits within the simulation are not provided, as it is assumed this would be done later in a reconstruction environment using the stored hit collections.
+Trackers record information from each step as a track propagates through the material of a volume. The stored information includes the mid-point position, direction of the track at that point, length of the step, global time, and the energy deposited. A \textit{TrackerHit} object is created and stored into a hit collection to persist this information. The Tracker is most commonly used to model high-granularity readout technologies, such as pixels or silicon strips. Algorithms for digitizing the hits within the simulation are not provided, as it is assumed this would be done later in a external analysis environment using the stored hit data.
-This is an example XML snippet for a simple tracking detector:
+This is an example of a simple tracking detector:
\begin{verbatim}
<tracker name="SiTrackerBarrel" hits_collection="SiTrackerBarrelHits">
@@ -259,17 +324,17 @@
</tracker>
\end{verbatim}
-Essentially the tracker is a relatively simple implementation of a sensitive detector that writes records of the individual steps. This information can then be used later outside the simulation as input to more sophisticated digitization algorithms.
+Essentially the tracker is a relatively simple implementation of a sensitive detector that records the information from individual steps. The persisted information can then be used later as input to more sophisticated digitization algorithms.
\subsection{Scorer}
-The Scorer type is the simplest of the three sensitive detector implementations. It records the passage of particles through a volume. The main difference between the Tracker and the Scorer is that the latter will only record one hit for each unique G4Track that passes through it, whereas the Tracker class records all separate steps as individual hits. The scorer simply provides a way to determine if a given track passed through the volume.
+The scorer type is the simplest of the sensitive detector implementations. It records the passage of particles through a volume. The main difference between the tracker and the scorer is that the latter will only record one hit for each unique G4Track that passes through it, whereas the tracker class records all separate steps as individual hits. The scorer simply provides a way to determine if a given track passed through the volume.
\subsection{Calorimeter}
-The calorimeter is used to record the energy depositions of particle showers in homogeneous or sampling detectors. Typically these showers are composed of many individual steps. The energy depositions from all of these steps are accumulated to determine the total energy deposited in the volume. The energy depositions may be summed for an entire volume, such as a physical crystal. Or the energy may be accumulated in an array of virtual cells, similar to entries in histogram bins. When the volumes are artificially segmented in this way, there is generally one calorimeter hit object created per virtual cell for the entire event. Hit contributions are saved for each
+The calorimeter is used to record the energy depositions of particle showers in homogeneous or sampling detectors. Typically these showers are composed of many individual steps. The energy depositions from all these steps are accumulated to determine the total energy deposited in the volume for that event. The energy depositions may be summed for an entire volume, such as a physical calorimeter crystal. Or the energy depositions in one volume may be binned into an array of virtual cells. When volumes are artificially segmented, there is one calorimeter hit object created per virtual cell for the entire event.
-The following XML defines a calorimeter with uniform sized cells created by a virtual segmentation class. The \textit{grid\_xyz} element will divide the detector's sensor layers into a grid of cells with size 3.5mm x 3.5mm.
+The following XML defines a calorimeter with uniform sized cells created by a virtual segmentation class. The \textit{grid\_xyz} element will divide the detector's sensor layers into a grid of 3.5mm x 3.5mm cells.
\begin{verbatim}
<calorimeter name="EcalBarrel" hits_collection="EcalBarrelHits">
@@ -278,19 +343,23 @@
</calorimeter>
\end{verbatim}
-The calorimeter hits have a list of individual energy contributions that correspond to single steps in the simulation, recording the PDG code of the particle and the positional information about that step, e.g. its endpoints. Depending on the application's requirements, this low-level information within the calorimeter hit may or may not be saved into the output data. It might be useful if the readout response depends on the distance of an energy deposition from the edge of the cell, etc.
+The calorimeter hits each have a list of individual energy contributions that correspond to single steps in the simulation, recording the PDG code of the particle and the positional information about that step, e.g. its endpoints. Depending on the user requirements, the low-level step data can be saved into the output data, as it might be useful if the readout response depends on the distance of an energy deposition from the edge of the cell, etc. The energy contributions may also be summed to obtain the total energy deposition in the cell for that event.
+\section{Hits Processors}
+
+Each sensitive detector has one or more \textit{hits\_processor} objects to process step information into hits, allowing flexibility in how different types of particles and physics are handled. For instance, an optical calorimeter may write out separate hits collections for the scintillation and Cherenkov energy depositions using two different hits processors. The tracker and calorimeter detectors each have a default hits processor that may use the segmentation, sensitive detector, and identifier classes to construct hits. It is anticipated that the hits processor could provide an extension point for future development of flexible digitization algorithms with complex requirements and input parameters.
+
\section{Segmentation}
%% TODO: Include images that show how each segmentation works, e.g. projective, grid, etc. This can include the specific numbering about the origin as in grid_xyz's scheme.
-Sensitive volumes in a calorimeter, such as planar layers, usually require virtual subdivision. The \textit{segmentation} XML element models this division of geometric volumes into cells. The algorithmic approach to segmented readout has some advantages over using purely geometric constructs. Simulating millions of individual cell volumes could be expensive in terms of memory usage. There are also certain cases in which it is simpler to describe a readout system with an algorithm rather than pure geometry. For instance, projective calorimeter towers have many different shapes and sizes of cells depending on the radial distance from the origin, and these would be complicated to construct using only solids and volumes.
+Sensitive volumes in a calorimeter, such as planar layers, usually require virtual subdivision. The \textit{segmentation} element models this division of geometric volumes into cells. The algorithmic approach has some advantages over using purely geometric constructs. Simulating millions of individual cell volumes could be expensive in terms of memory usage. There are also certain cases in which it is simpler to describe a readout system with an algorithm rather than pure geometry. For instance, projective calorimeter towers have many different shapes and sizes of cells depending on the radial distance of a layer from the origin, and this would be complicated to construct using only solids and volumes.
-Concrete segmentation types extend an abstract XML element. The parameters which define the dimensions of the cells are specific to a certain type. The \textit{segmentation} element occurs as a child of the calorimeter element. Each calorimeter may have only one of these associated objects. The values of the fields from the segmentation at a certain hit position can be written into the identifiers of the hits by referencing their names in the identifier specification.
+The \textit{segmentation} element occurs as a child of the calorimeter element, and each calorimeter may have only one of these associated objects. The specific segmentation types extend an abstract XML element. The parameters which define the dimensions of the cells are specific to a certain type. The values of the fields from the segmentation at a certain hit position can be written into the identifiers of the hits by referencing their names in the identifier specification.
\subsection{Grid XYZ Segmentation}
-The \textit{grid\_xyz} segmentation divides a volume along its X, Y, or Z axes, creating a regular grid of box-like cells. The indices are signed integer values, numbered about the natural origin of the volume's solid, which is generally its center. Only the position with respect to the origin is used to compute index value at a particular point in the segmentation grid, so no additional geometric information, such as the bounds of the current solid, is required by the algorithm.
+The \textit{grid\_xyz} segmentation divides a volume into cells along any combination of its X, Y, or Z axes, creating a regular grid of box-like virtual volumes. The indices are signed integer values, numbered about the natural origin of the volume's solid, which is its center point in local coordinates. Only the position with respect to this origin is used to compute an index value at a particular point in the grid, so no additional geometric information, such as the bounds of the current solid, is required by this algorithm to compute the bin values.
The following XML shows a \textit{grid\_xyz} segmentation that divides a volume along the X and Y axes.
@@ -298,7 +367,7 @@
<grid_xyz grid_size_x="1.0*cm" grid_size_y="1.0*cm" />
\end{verbatim}
-Any combination of X, Y and Z cell sizes may be provided. The default value of zero results in that axis being left unsegmented, so that the position is reported as zero, which translates to the center point of the volume along that axis. This segmentation is typically used to divide a plane into a rectilinear grid of cells in two dimensions, say X and Y, with the third dimension, e.g. Z, left unsegmented.
+The default grid size value of zero for an axis results in that dimension being left unsegmented, so that the position is reported as zero. This actually translates to the center point along that axis in local coordinates. Typically, this segmentation type divides a plane into a rectilinear grid of cells in two dimensions, say X and Y, with the third dimension, e.g. Z, left unsegmented.
\subsection{Projective Cylinder Segmentation}
@@ -310,7 +379,7 @@
<projective_cylinder ntheta="1000" nphi="2000" />
\end{verbatim}
-This segmentation is typically used in geometries where the calorimeter barrel is modeled using a series of nested tubes, rather than more realistic modules that contain planar layers.
+This segmentation is used in geometries where the calorimeter barrel is modeled using a series of nested tubes, rather than modules containing planar layers.
\subsection{Non-projective Cylinder Segmentation}
@@ -340,17 +409,13 @@
Unlike most other segmentations, this algorithm uses the origin of the world volume rather than the volume's center.
-\section{Hits Processors}
-
-Each sensitive detector may have one or more \textit{hits\_processor} objects to process step information into hit objects, allowing flexibility in how different types of particles and physics are handled. For instance, an optical calorimeter can write separate hit collections for the scintillation and Cherenkov energy depositions by using two different hits processors. The tracker and calorimeter detectors each have a default hits processor that uses the segmentation, sensitive detector, and identifier classes to construct hits. It is anticipated that the hits processor could provide an extension point for future development of flexible algorithms that have more complex requirements.
-
\section{Identifiers}
-Identifiers define the formats for bit-packed numbers that may be used outside the framework to associate hits with their geometric and detector information. The values from physical volume IDs or segmentation bins may be written into these IDs. Each sensitive detector may have one identifier specification, which is used to create a 64-bit integer. The user is ultimately responsible for making sure that the given combination of field values in this specification results in globally unique values for each hit.
+Identifiers define formats for bit-packed numbers used to associate hits with their geometric and detector information. The values from physical volume IDs or segmentation bins may be written into these IDs. Each sensitive detector may have one identifier specification, which is used to create this 64-bit integer from detector information within the simulation. The user is ultimately responsible for making sure that the given combination of field values in the ID specification results in globally unique values for each hit.
-All of the identifier specifications are contained in a dictionary called the \textit{iddict}. Each specification has a corresponding element called the \textit{idspec}. The \textit{idspec} contains a list of \textit{idfield} tags, each of which defines a single field of the identifier, such as a layer number or a single field from the segmentation. The individual fields can be from 1 to 32 bits and may be signed or unsigned.
+All of the identifier specifications are contained in the \textit{iddict}. Every ID dictionary has a corresponding element called the \textit{idspec} with a list of \textit{idfield} tags. Each \textit{idfield} defines a single field of the identifier, such as a layer number or a field from the segmentation. The individual fields can be from 1 to 32 bits long and may be signed or unsigned.
-Below is an example of an identifier definition for an ILC calorimeter.
+Below is an example of an identifier definition for a calorimeter.
\begin{verbatim}
<idspec name="EcalBarrelHits" length="64">
@@ -365,13 +430,13 @@
</idspec>
\end{verbatim}
-The first five fields of the above identifier derive from \textit{physvolid} values. The ``x'' and ``y'' fields are read from the segmentation bins at the hit position. Together, these values identify a unique cell and can be subsequently decoded within an external framework.
+The first five fields of the above identifier derive from the \textit{physvolid} values. The ``x'' and ``y'' fields are read from the segmentation bins at the hit position. Together, these values identify a unique cell and can be subsequently decoded within an external framework to find the detector information for a hit.
\section{Physics Limits}
-Physics limits can be assigned to volumes in order to tune certain parameters within the simulation engine. For example, the range cut which determines which secondary particles are produced can increased to limit the production of many low-energy secondary particles in divergent electromagnetic processes.
+Physics limits can be assigned to volumes in order to tune certain parameters within the simulation. For example, the range cut can be increased to limit the production of low-energy secondary particles in divergent electromagnetic processes.
-The following example will restrict the step lengths to 5 mm.
+The following example will restrict the step lengths of all particles to 5 mm.
\begin{verbatim}
<limits>
@@ -381,11 +446,22 @@
</limits>
\end{verbatim}
-The limits that can be set include the maximum step length, the maximum track length, the maximum particle lifetime, the minimum particle kinetic energy, and the minimum range (or "range cut" in Geant4 terminology).
+Each limit has a name that identifies the simulation parameter, a double value, a unit applied to that value, and a comma-delimited list of particles. The names of the particles in the list are defined within Geant4.
+\begin{tabular}{ | l | l | }
+\hline
+step\_length\_max & maximum length of a single step \\ \hline
+track\_length\_max & maximum length of a single track \\ \hline
+time\_max & maximum lifetime of a track \\ \hline
+ekin\_min & minimum track kinetic energy \\ \hline
+range\_min & range cut \\ \hline
+\end{tabular}
+
+The available limits include the maximum step length, the maximum track length, the maximum particle lifetime, the minimum particle kinetic energy, and the minimum range (or "range cut" in Geant4 terminology).
+
\section{Regions}
-Regions are assigned to geometric volumes using the \textit{region} element. These are collections of volumes that share similar characteristics. A flag specifies whether or not secondary particles produced in the simulation are stored into the output particle collections. The following example defines a region in which all secondary particles will be stored into the output. This is typically called a ``tracking region.''
+Regions are assigned to geometric volumes using the \textit{region} element. These are collections of volumes sharing similar characteristics. A flag specifies whether or not secondary particles produced in the simulation are stored into the output particle collections. The following example defines a region in which all secondary particles will be stored into the output. This is typically called a ``tracking region.''
\begin{verbatim}
<regions>
@@ -396,10 +472,19 @@
The above example also specifies that particles which would not travel more than 10 millimeters will not be produced, and it also establishes an energy cut of 1 MeV for storing particles to the output.
-\section{Magnetic Field}
+\section{Magnetic Fields}
-Realistic simulation of magnetic fields is typically an important part of the detector simulation. There are currently four types of fields available. When the field regions overlap, the B-field components are added to each other as an overlay. The solenoid element has an inner and outer field value. The following is an example of a solenoid with a 5 Tesla magnetic field oriented along the z axis.
+%% TODO: Section needs a lot of work! +%% TODO: Add information on dipole, RZ and Cartesian maps.
+Geant4 can simulate the interaction of particles with electromagnetic fields. \cite{geant4fields} LCDD provides a number of different field types for describing B-fields, ranging from simple approximations using fixed values to detailed grids of B-field component values. Fields are defined globally in a list. When their regions of validity overlap, the field components are added to make an overlay.
+
+\subsection{Solenoid}
+
+The \textit{solenoid} is a simplistic representation of solenoid magnet with Bz component. It has an inner and outer radius. One Bz value is applied within the inner radius and another between the inner and outer. This field can be used for collider-detectors where charged particles should bend in the XY plane.
+
+The following defines a solenoid with a 5 tesla field strength.
+
\begin{verbatim}
<fields>
<solenoid name="GlobalSolenoid" lunit="mm" funit="tesla"
@@ -408,84 +493,92 @@
</fields>
\end{verbatim}
-In addition to the solenoid, a dipole field is available that uses a simple polynomial fit with a variable number of coefficients. An RZ field map can be used to simulate a non-uniform field in the radial and Z directions with a uniform phi.
+\subsection{Dipole}
-\section{Visualization}
+The dipole models a Bx field that varies in the Z dimension given a list of coefficients, using the following formula. This is a simple polynomial fit with an arbitrary number of terms.
-Geant4 has a number of built-in mechanisms for visualizing detectors. These range from real-time visualization using OpenGL to the generation of file formats such as VRML. LCDD allows one to attach visualization attributes to geometric volumes with an XML element that binds to the G4VisAttributes class. The supported visualization attributes include line style (broken or unbroken), drawing style (wireframe or solid), whether or not daughter volumes should be visible, and whether the volume itself is visible. The color of volumes may also be assigned using individual RGB values from 0.0 to 1.0, as well as the transparency alpha. An alpha value of 0.0 would render the component invisible. The following is an example of visualization attributes.
+$B_x=\sum_{i=1}^{n} zc_i$
+Here is an example of a dipole field definition. +
\begin{verbatim}
-<display> - <vis name="CalVis" line_style="unbroken" drawing_style="wireframe" - show_daughters="true" visible="true"> - <color R="1.0" G="0.0" B="0.0" alpha="1.0"/> - </vis> -</display>
+<dipole name="ExamploeDipoleField" zmin="0.0" zmax="-10.0*mm" > + <dipole_coeff value="1.0" /> + <dipole_coeff value="0.1" /> + <dipole_coeff value="0.001" /> +</dipole>
\end{verbatim}
-\section{Volume Element}
+\subsection{Box Dipole}
-LCDD extends GDML by adding optional elements to the volume element. A proper GDML parser will simply ignore these unknown tags when processing the file. There are no other alterations to standard GDML made by LCDD, so the extension is relatively clean. Deriving a valid GDML file from LCDD is therefore quite straightforward. The following example assigns to an example volume a sensitive detector, a set of physics limits, a detector region, a set of visualization attributes, and a region.
+The \textit{box\_dipole} is used to define a set of fixed B component values in a box region.
\begin{verbatim}
-<volume name="EcalBarrel_layer0"> - <materialref ref="Silicon"/> - <solidref ref="EcalBarrel_layer0_box"/> - <sdref ref="EcalBarrel"/> - <limitsetref ref="CalLimits"/> - <visref ref="CalVis"/> - <regionref ref="CalRegion"/> -</volume>
+<box_dipole name="AnalyzingDipole" + x="2.117*cm" y="0*cm" z="45.72*cm" + dx="50.0*cm" dy="50.0*cm" dz="50.0*cm" + bx="0.0" by="-1.5" bz="0.0" />
\end{verbatim}
-The LCDD objects named in this volume description are actually references to previously defined elements. For example, the ``EcalBarrel'' sensitive detector is defined prior to the volume definition, and the parser will retrieve its definition from an in-memory data structure and assign the sensitive detector to the named volume. A similar strategy is used for the other objects referenced by the extended volume element.
+\subsection{RZ Field Map}
-\section{Physical Volume IDs}
+An RZ field map can be used to simulate a variable field in the radial and Z directions with a uniform phi.
-Physical volumes in GDML are extended so that they may have one or more physical volume IDs. These can be used in the output of 64-bit identifiers attached to hits. - -For instance, this can be used to assign layer numbers. -
\begin{verbatim}
-<volume name="DetectorEnvelope"> - <materialref ref="Air"/> - solidref ref="DetectorEnvelopeBox"/> - <physvol> - <volumeref ref="LayerVolume"/> - <physvolid field_name="layer" value="1"/> - </phyvol> -</volume>
+<rz_field_map name="RZFieldMapTest" lunit="cm" funit="kilogauss" + num_bins_r="67" num_bins_z="64" grid_size_z="10.0" grid_size_r="10.0"> + <rzB z="0.0" r="0.0" Bz="50.011" Br="0.0" /> + <rzB z="10.0" r="0.0" Bz="49.996" Br="0.0" /> + <rzB z="20.0" r="0.0" Bz="49.95" Br="0.0" /> + <rzB z="30.0" r="0.0" Bz="49.874" Br="0.0" /> + [etc.] +</rz_field_map>
\end{verbatim}
-\section{Using LCDD in an Application}
+The Z and R bins are computed from the global position, and a simple interpolation is performed to compute the B-field components at that point.
-LCDD implements the Geant4 class G4VUserDetectorConstruction so that using it in an application becomes very simple. It is simply a matter of registering the LCDD detector construction class with the Geant4 run manager.
+\subsection{Field Map 3D}
+The \textit{field\_map\_3d} represents a full 3D Cartesian field map as a grid of $B_x, B_y$ and $B_z$ values at 3D points.
+
+Here is an example.
+
\begin{verbatim}
-theRunManager->SetUserInitialization(new LCDDDetectorConstruction());
+<field_map_3d name="FieldMap3DTest" lunit="mm" funit="tesla" + filename="data/HPS_b18d36_unfolded.dat" + xoffset="2.117" yoffset="0.0" zoffset="45.72" />
\end{verbatim}
-This will then allow the detector document to be specified using a macro command such as the following command which will load a detector from a URL.
+The field values are defined in an external file with each line defining a point in the map.
\begin{verbatim}
-/lcdd/url http://www.lcsim.org/detectors/sidloi3/sidloi3.lcdd
+x, y, z, Bx, By, Bz
\end{verbatim}
-Local files can also be read in by using the correct protocol.
+A full 3D interpolation is performed to determine the B-field component at a given point in the grid.
+\section{Visualization}
+
+Geant4 has a number of built-in mechanisms for visualizing detectors. These range from real-time visualization using OpenGL to the generation of graphics file formats such as VRML. LCDD allows one to attach visualization attributes to geometric volumes with an XML element that binds to the G4VisAttributes class. The supported visualization attributes include line style (broken or unbroken), drawing style (wireframe or solid), whether or not daughter volumes should be visible, and whether the volume itself is visible. The color of volumes may also be assigned using individual RGB values from 0.0 to 1.0, as well as the transparency or alpha. An alpha value of 0.0 would render the component invisible.
+
+The following is an example of visualization attributes.
+
\begin{verbatim}
-/lcdd/url file:///local/path/to/sidloi3.lcdd
+<display> + <vis name="CalVis" line_style="unbroken" drawing_style="wireframe" + show_daughters="true" visible="true"> + <color R="1.0" G="0.0" B="0.0" alpha="1.0"/> + </vis> +</display>
\end{verbatim}
-The detector document must be set in the pre-initialization phase, and then the macro would typically execute \textit{/control/initialize} to initialization the application and setup the detector geometry.
-
\section{Examples}
\subsection{Linear Collider}
-Linear Collider detector research programs have simulated in detail the response of a number of different detector designs and subdetector technologies. The Silicon Detector (SiD) collaboration has optimized the design of its full detector concept through many different iterations. This required the simulation of widely varying geometric layouts and readout schemes and the development of software to support this flexibility. The current design for its Detector Baseline Document (DBD) is the sidloi3 detector, which is composed of vertex, tracking, and calorimeter sub-systems, as well as support, masks and dead material. LCDD was used to model and simulate these sub-detectors in a variety of physics scenarios. This includes an ECAL with several million readout cha!
nnels as well as a Silicon Vertex Tracker with thousands of tracking modules per sub-detector.
+Linear Collider detector research programs have simulated in detail the response of a number of different detector designs and subdetector technologies. The Silicon Detector (SiD) collaboration has optimized the design of its full detector concept through many different iterations. This required the simulation of widely varying geometric layouts and readout schemes and the development of software to support this flexibility. The current design for its Detector Baseline Document (DBD) is the sidloi3 detector, which is composed of vertex, tracking, and calorimeter sub-systems, as well as supports, masks and various types of dead material. This includes an ECAL with several million readout channels as well as a Silicon Vertex Tracker with thousands of tracking modules per&nbs!
p;sub-detector. LCDD was used to model and simulate these sub-detectors in a variety of physics scenarios.
-\begin{figure}[H]
+\begin{figure}[htpb]
\caption{The SiD Silicon Vertex Tracker Barrel.}
\includegraphics[width=0.5\textwidth]{sidloi3_tracker_barrel}
\end{figure}
@@ -494,19 +587,21 @@
The Heavy Photon Search (HPS) is a direct Dark Matter search. Its test run detector was simulated using LCDD, in a variety of configurations.
+%% TODO: Include more in this section. +
%% FIXME: This is a placeholder graphic only!
-\begin{figure}[H]
+\begin{figure}[htpb]
\caption{The HPS Experiment.}
\includegraphics[width=0.5\textwidth]{hps_detector}
\end{figure}
\section{Conclusion}
-LCDD is a robust and complete system for modeling detectors using the Geant4 simulation toolkit. It has been used by a variety of experimental physics collaborations to prototype various detector designs.
+LCDD is a robust and complete system for modeling detectors using the Geant4 simulation toolkit. It has been used by a variety of experimental physics collaborations to prototype various detector designs. In particular, LCDD has become part of the common set of tools used to simulate ILC detector designs for CLiC, SiD and ILD. The usage of GDML allows the framework to model geometries to an arbitrary level of detail while providing all the required, extra information for a complete detector description language.
\section{Future Plans}
-TODO
+The DD4HEP \cite{dd4hep} is a project from creating a new, common detector framework for HEP. LCDD will be integrated with this system by implementing XML bindings for some of its key concepts, including segmentation. This will allow LCDD to be used as part of a common simulation framework for that project.
%% \begin{verbatim}
%% \end{verbatim}
@@ -549,6 +644,12 @@
\bibitem{lcio} LCIO - A persistency framework for linear collider simulation studies, Computing in High Energy and Nuclear Physics, 24-28 March 200
+\bibitem{geant4fields} https://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/ch04s03.html
+
+\bibitem{dd4hep} http://aidasoft.web.cern.ch/DD4hep
+
+\bibitem{xerces} http://xerces.apache.org/xerces-c/
+
\end{thebibliography}
\end{document}
[Note: Some over-long lines of diff output only partialy shown]
Use REPLY-ALL to reply to list
To unsubscribe from the LCDET-SVN list, click the following link:
https://listserv.slac.stanford.edu/cgi-bin/wa?SUBED1=LCDET-SVN&A=1