--- docs/pubs/0001-lcdd/lcdd-paper.tex	2014-06-10 18:04:04 UTC (rev 3153)
+++ docs/pubs/0001-lcdd/lcdd-paper.tex	2014-06-11 23:30:20 UTC (rev 3154)
@@ -116,7 +116,7 @@

 %% \[log in to unmask]
 
 \begin{abstract}

-Geant4 is a powerful framework for simulating the interactions of particles with matter and fields, but it is also large and complex. It is designed as a toolkit, rather than a pre-packaged executable.  End users must assemble an application based upon their requirements.  This requires a considerable amount of expertise both in the C++ language and the details of the framework.  Providing a flexible application framework based on Geant4 which can meet the needs of many different users can alleviate this technical hurdle.  This requires that many of the simulation parameters be defined at runtime, rather than embedded into source code.  Ideally, in an application of this type, the geometry should be defined by a data format, rather than via a set of compiled classes.  Some Geant4 applications using flexible input geometry formats do exist, but they tend to be specific to certain domains, such as medical physics simulations.  GDML provide!
 s an XML geometry description, but not the other [...]

+Geant4 is a powerful software framework for simulating the interactions of particles with matter and fields, but it is also large and complex. It is designed as a toolkit, rather than a pre-packaged executable.  End users must assemble an application based upon their requirements.  This requires a considerable amount of expertise both in the C++ language and the details of configuring the framework.  Providing a flexible application based on Geant4, which can meet the needs of many different users, can alleviate this technical hurdle.  This approach requires that many of the simulation parameters be defined at runtime, rather than embedded into source code.  Ideally, in an application of this type, the geometry should be defined by a data format, rather than a set of compiled classes.  Some Geant4 applications use flexible input geometry formats but tend to be specific to certain domains, such as medical physics simulations.  GDML provides!
  an XML geometry description, but not the compl[...]

 \end{abstract}
 
 %% \begin{keyword}

@@ -140,13 +140,13 @@

 %% still need to know the Geant4 physics, e.g physics lists, regions, step size...
 %%
 

-Geant4 is an application framework that has become the primary tool used in HEP for the simulation of particle interactions in matter and fields.  It is distributed as a set of source files and examples with compilation instructions.  Geant4 is an Object Oriented toolkit which is used to assemble a domain-specific application based on experimental requirements.  The most complex and lengthy requirement to fulfill is usually the geometry description, which for complex detector setups can comprise hundreds, or even thousands of lines of custom code.  Typically, the user must implement their own geometry setup and configure all the other necessary components for their particular simulation.  This task can be daunting, as it requires a considerable level of expertise not only in the toolkit itself, but in the details of C++ syntax and implementations, a skill set that is becoming rarer as more scientific programmers move towards higher level!
  languages like Java and Python.

+Geant4 is an application framework that has become the primary tool used in HEP for the simulation of particle interactions in matter and fields.  It is distributed as a set of source files and examples with compilation instructions.  Geant4 is an Object Oriented toolkit which is used to assemble a domain-specific application based on experimental requirements.  The most complex and lengthy requirement is usually modeling the geometry and detectors, which for complex detector setups, can comprise hundreds, or even thousands of lines of custom code.  Typically, the user must implement their own geometry structure and configure all the other necessary detector components for their particular simulation.  This task can be daunting, as it requires a considerable level of expertise not only in the toolkit itself, but in the details of C++ syntax and implementations.

-Some physics simulation programs have used their own custom-defined data input formats for detector description to alleviate some of this complexity.  The lack of standardization in this area of detector description has hindered data interchangeability between different tools.  When geometry is defined in an application by coding directly against an API such as Geant4's, the overall size of the simulation code base tends to increase greatly over time as more and more detector models and variations are added.  This can lead to severe maintenance issues in the application, including a great amount of code duplication, the treatment of specific geometries as a "black box" with no real external data description, and a confusion and lack of separation between the areas of procedural code and data.

+Some physics simulation programs use their own custom-defined data input formats for detector description to alleviate some of this complexity.  The lack of standardization in this area of detector description has hindered data interchangeability between different tools.  When geometry is defined in an application by coding directly against an API, the overall size of the simulation code base tends to increase greatly over time, as more and more detector models and variants are added.  This can lead to severe maintenance issues in the application, including a great amount of code duplication between detector models; the treatment of specific geometries as a "black box" with no real external data description; and a confusion and lack of separation between the domains of procedural code and the data upon which it operates.

-Providing a comprehensive solution to these problems has been the goal of the Linear Collider Detector Description (LCDD) project.  This framework was first introduced as a solution for defining and simulating a myriad of detectors and their variants for the International Linear Collider (ILC) project, and it is now being used successfully by several other experiments.  By providing a clear and absolute separation between code and input data, researchers are freed from needing to now the complex details of geometry APIs and may instead focus on the defining the structure of their particular experiment.

+Providing a comprehensive solution to these problems has been the goal of the Linear Collider Detector Description (LCDD) project.  This framework was first introduced as a solution for defining and simulating a myriad of detectors and their variants for the International Linear Collider (ILC) project, and it is now being used successfully by several other experiments.  By providing a clear and absolute separation between code and detector input data, researchers are freed from needing to know the complex details of geometry APIs.  They may instead focus on the defining the simulation inputs for their particular experiment.

-This paper will start with an overview of the GDML XML language and framework, on which LCDD is based.  The LCDD extensions will be explained and described, with an XML example used to show the full document structure.  Each primary XML element type will be explained in detail, along with an XML example of its usage.  A solution will be given for authoring detector documents using another high-level format or "compact description."  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 GDML language and framework, upon which LCDD is based.  The LCDD extensions 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 anexample of its usage.  A solution will be given for authoring detector documents using another high-level format or "compact description."  Examples will be given of projects that have used LCDD to model their experiments.  Finally, future plans will be briefly discussed.

 
 \section{GDML}
 

@@ -155,19 +155,20 @@

 %% how does it answer question? import/export/exchange
 %% geometry is only a part of the project; still need regions, physics limits, fields, visualization, etc.
 

-Geometry Description Markup Language (GDML) is an XML language for geometry description.  This format allows users to define hierarchical geometry structures using a data language, rather than C++ source code that is customized for every detector variation.  GDML fully describes materials, mathematical variables and definitions, geometric solids such as boxes and tubes, and a hierarchical structure of volumes.  Materials are defined as either chemical elements or combinations thereof.  Simple constants can be defined, as well as equations that use trigonometric functions.  The support for different types of geometric solids is extensive, including Constructive Solid Geometry (CSG) solids defined algorithmically, and boundary representation (BREP) objects defined by planes forming a closed 3D surface.  A logical volume is defined by a solid and a material and may optionally contain a tree of "daughter" volumes.  A hierarchy of volumes def!
 ines the complete detector structure.

+Geometry Description Markup Language (GDML) is an XML language for geometry description.  This format allows users to define hierarchical geometry structures using a data language, rather than C++ source code that is customized for every detector variation.  GDML fully describes materials, mathematical variables and definitions, geometric solids such as boxes and tubes, and a hierarchical structure of logical and physical volumes.  Materials are defined as either chemical elements or combinations thereof.  Simple constants can be defined, as well as equations that use trigonometric functions
+and basic mathematical operators.  The support for different types of geometric solids is extensive, including simple shapes such as boxes and tubes or more complex tesselated volumes formed from an arbitrary number of surfacs.  A logical volume is defined by a solid and a material and may optionally contain a tree of "daughter" physical volumes.  A hierarchy of volumes then defines the complete detector structure.

 
 \section{LCDD}
 

-In addition to the basic geometric layout of the experiment, additional information is required for fully describing a detector at runtime.  This complete set of data is usually called "detector description”.  Frameworks that use a data language such as GDML for geometry description have generally still required additional, auxiliary information at runtime, for example, through macro commands that define readouts and assign them to volumes.  There are inherent problems and limitations to this approach.  The supplementary information to the geometry is not easily accessible, if it is embedded in relatively unstructured, procedural macro files.  Using ad hoc, runtime commands can also make it difficult to determine later which detector simulation parameters were used to produce a simulation data output file, or what readout parameters should be associated to a particular detector component.

+In addition to the geometric layout of the experiment, additional information is required for fully describing 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 have generally still required additional, auxiliary information at runtime, for example, through macro commands that define readouts and assign them to volumes.  There are inherent problems and limitations to this approach.  The supplementary information to the geometry is not easily accessible, if it is embedded in relatively unstructured, procedural macro files.  Using ad hoc, runtime commands can also make it difficult to determine later which detector simulation parameters were used to produce an output file or what readout parameters should be associated to a particular detector component.

-A more complete approach is required to guarantee the consistency and integrity of the detector data.  The Linear Collider Detector Description (LCDD) language was designed to provide a complete description of complex experimental setups.  Various types of detectors, ranging from simple test beams to complex “4 PI” HEP detectors, can be modeled to an arbitrary level of detail, using an XML file rather than detector-specific C++ code.  LCDD is built upon the GDML data format and C++ parser.  It extends GDML’s XML data format by using built-in facilities of the XML Schema (XSD) language.  GDML code infrastructure is reused by registering additional element handlers with GDML’s flexible parser class.  One benefit of this approach is that the extended parser, without any alteration, can also read in plain GDML files, as well as LCDD.

+A more complete 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 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.  GDML code infrastructure is reused by registering additional element handlers with GDML’s flexible parser class.  The extended parser, without any alteration, can also read in plain GDML files, as well as LCDD.

-LCDD uses GDML to define the core geometric information.  The GDML schema is formally extended using the \textit{extension} element so that the textit{gdml} root node appears embedded as part of the LCDD document.  The GDML language is essentially left in tact, with an extension added to the schema so that the \textit{volume} element may contain optional references to data types defined in LCDD.  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 at runtime.

+LCDD uses GDML to define the core geometric information about the experiment.  The LCDD schema formally extends GDML using the \textit{extension} element, so the textit{gdml} root node is embedded as part of the document.  The GDML language is essentially left in tact, with a single point of extension added to the \textit{volume} element, which may then contain optional references to additional LCDD elements.  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 at runtime.

 
 \subsection{Document Structure}
 

-Every LCDD document has the same basic structure.  The top-level \textit{lcdd} element has a list of sections, one of which includes an entire GDML geometry.  Aside from the header, the other sections all contain list of elements with a specific type.  These elements can be referenced from the extended GDML language to associate the supplementary information with specific logical volumes defined by the geometry.

+Every LCDD document has the same basic structure.  The top-level \textit{lcdd} element has a list of sections, one of which includes an entire, embedded GDML document.  Aside from the header, which has no child elements, the other sections each contain a list of elements with a specific type.  The elements can be referenced from the GDML to associate the supplementary information with specific logical volumes defined by the geometry.  This is done by making a language extension to the GDML volume element.

 
 \begin{verbatim}
 <lcdd>

@@ -188,9 +189,9 @@

 </lcdd>
 \end{verbatim}
 

-The header has basic meta data about the document, such as who authored it.  The \textit{iddict} contains identifier dictionaries that provide encodings for information that can be written into hit objects at runtime, including layer numbers and subdetector IDs.  The \textit{sensitive\_detectors} element defines detectors that are assigned via reference to volumes.  This allows hits to be written to an output file, containing energy, position and time information.  The \textit{limits} are sets of physics limits that determine some behavior in the Geant4 physics engine.  The \textit{display} element contains visualization settings that can be used to set colors and visibility of individual geometric volumes.  The \textit{gdml} tag defines a GDML document, which must follow that format's syntax.  Finally, the \textit{fields} element contains definitions of magnetic field components for the world volume.  Each of these element types will be!
  explained in detail.[...]

+The header has basic meta data about the document, such as who authored it.  The \textit{iddict} contains identifier dictionaries that provide encodings for information that can be written into hit objects at runtime, including layer numbers and detector IDs.  The \textit{sensitive\_detectors} element defines Geant4 "sensitive detectors" that are assigned via reference to volumes.  This causes hits to be accumulated for that detector by event, containing energy, position and time information.  The \textit{limits} are sets of physics limits that determine some behavior in the Geant4 physics engine, such as the maximum step size of a track.  The \textit{display} element contains visualization information that can be used to assign colors and visibility settings to logical volumes.  The \textit{gdml} tag defines a GDML document, which must follow that format's syntax.  The LCDD schema extends GDML so that the logical and physical volumes can !
 be assigned additional information.  Finally, t[...]

-The input document is checked by the parser 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 parser is fault tolerant, in that minor errors, such as mis-ordering of child elements, may only result in warning messages.  Other, more severe errors within a document, such as references to non-existent elements, will result in fatal exceptions that cause the application to exit.

+The input document is checked by the parser 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 parser is fault tolerant, in that minor errors, such as mis-ordering of child elements, may only result in warning messages.  Other, more severe errors within a document, such as references to non-existent element IDs, will result in fatal exceptions that cause the application to exit.

 
 \section{Header Element}
 

@@ -206,7 +207,7 @@

 </header>
 \end{verbatim}
 

-An author tag gives the names of the people who created the file, as well as an optional email contact.  The detector tag provides a name that can be used as a "tag" of the document.  The generator tag gives information about an external program that was used to generate the file, including a source file name, if applicable, a version of the generator, and a checksum that could be generated by an MD5 algorithm.  There is a comment block that can contain a description and notes about the detector.

+An author tag gives the names of the people who created the file, as well as an optional email contact.  The detector element provides a name that can be used as a "tag" of the document to uniquely identify it.  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.  There is a free-form comment block that can contain a description and notes about the detector.

 
 \section{Sensitive Detectors}
 

@@ -291,7 +292,7 @@

 
 \subsection{Non-projective Cylinder Segmentation}
 

-A nonprojective\_cylinder segmentation element will divide the surface of a cylinder into cells of equal size.  

+A nonprojective\_cylinder segmentation element will divide the surface of a cylinder into cells of equal size.

 
 \begin{verbatim}
 <nonprojective_cylinder grid_size_phi=”10.0” grid_size_z=”10.0” />

@@ -317,7 +318,7 @@

 
 \section{Hits Processors}
 

-%% TODO

+Each detector has one or more \textit{hits_processor} objects that process steps in the simulation and turn them into hits.  This allows a detector to handle different types of particles and physics processes differently.  For instance, an optical calorimeter writes separate hit collections for the optical and Cherenkov energy depositions by using two different hits processors.

 
 \section{Identifiers}
 

@@ -415,14 +416,34 @@

 
 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.
 

-\section{Macro Command Interface}

+\section{Command Interface}

 
 %% TODO: example of loading an LCDD file using Geant4 macro commands
 
 \section{Compact Detector Description}
 

-%% TODO: information about compact description and why it can help solve issues with manually defining LCDD documents

+Though LCDD solves a certain problem, certain complexities are introduced.  The format, especially the embedded GDML document, is highly verbose, and complex structures can be tedious to hand-code.  For this reason, an intermediate format that translates from high level concepts and parameters to the low-level representation of LCDD can be helpful and time-saving.

+The compact detector description has been used for ILC work and in the HPS experiment to represent many different detector variations.
+
+\begin{verbatim}
+<detector id="7" name="HcalBarrel"
+          type="PolyhedraBarrelCalorimeter2" readout="HcalBarrelHits"
+          vis="HcalBarrelVis" calorimeterType="HAD_BARREL">
+    <dimensions numsides="12" rmin="1419.0" z="3018.0 * 2"/>
+    <layer repeat="40">
+        <slice material = "Steel235" thickness = "1.89*cm" />
+        <slice material = "PyrexGlass" thickness = "0.11*cm" />
+        <slice material = "RPCGasDefault" thickness = "0.12*cm" sensitive = "yes" limits="cal_limits" />
+        <slice material = "PyrexGlass" thickness = "0.11*cm" />
+        <slice material = "G10" thickness = "0.3*cm" />
+        <slice material = "Air" thickness = "0.16*cm" />
+    </layer>
+</detector>
+\end{verbatim}
+
+A Java library of converters is able to translate from the terse description into the hierarchical volume structure defined by LCDD.
+

 \section{Examples}
 
 %% TODO: reference DD4Hep's N04.lcdd as implementation matching Geant4's N04 example