--- docs/pubs/0001-lcdd/lcdd-paper.tex	2014-05-14 15:27:42 UTC (rev 3127)
+++ docs/pubs/0001-lcdd/lcdd-paper.tex	2014-05-19 22:29:09 UTC (rev 3128)
@@ -114,7 +114,19 @@

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

+%% geant4 powerful but complex, large and steep learning curve
+%% requires expertise.
+%% want to have a program, not a toolkit
+%% gdml solved some of the problem (e.g. geom) but much remains
+%% e.g. fields, etc.
+%% some applications exist, but are very domain-spcific (e.g. medical) library work and get references.

 Linear Collider Detector Description (LCDD) is an XML format for fully describing complex High Energy Physics experimental detector setups at runtime for the Geant4 simulation engine.

+%% fully defined runtime simulation, not HEP-specific.
+%% parser and data format to replace C++ classes
+%% free the end user from the need to know c++ coding or Geant4 architecture/class specifics
+%% still need to know the Geant4 physics, e.g physics lists, regions, step size...
+%%
+%% target full-length writeup, shorten as necessary for NIM, CPC...

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

@@ -134,17 +146,27 @@

 %% main text
 \section{Introduction}
 

-\par

+%% the following should be an implementation example
+
+Geant4 encapsulates the best knowledge of the interaction of particles with material and fields.  It is distributed as a set of source files with compilation instructions, e.g. a toolkit that the user must assemble into a working application based on provided examples and tutorials.  However, this can be a daunting task, as it requires expertise not only in the toolkit but in the details of C++ implementations.  Typically, the end user must implement their own geometry setup using C++ code and instantiate and configure all the necessary components for the simulation, including physics list, user actions, fields, etc.  Freeing the end user from such requirements has been the goal of the LCDD project, in order that they may focus on the physics questions they wish to explore.
+
+%% FIXME: some duplication with prior paragraph
+In experimental physics, Geant4 has become the de facto software package for modeling complicated geometries and readouts.  It defines a complete set of APIs in the geometry and detector description area.  But this has still required that end users create a C++ implementation for their specific geometry, which requires an expert to code.  There are problems with a code-centric approach to defining geometries for end users, as opposed to a data oriented system that binds to a standard API.  The latter has a number of advantages over the former.
+
+
+

 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.
 

-\par

 Individual Monte Carlo programs have typically used custom data formats and APIs for detector description, with complex interfaces that define shapes and readouts.  User applications based on these frameworks implement their detectors using the programmatic interfaces.  Some packages define their own runtime data formats for geometry description.  Historically, the lack of standardization in this area of detector description has hindered data interchangeability between different tools.  When geometry is defined by computer code, usually along with a set of associated run-time parameters, the user’s simulation package tends to greatly increase in size as the number of detector components grows, leading to maintenance issues and code bloat.
 

-\par
-In experimental physics, Geant4 has become the de facto software package for modeling complicated geometries and readouts.  It defines a complete set of APIs in the geometry and detector description area.  But this has still required that end users create a C++ implementation for their specific geometry, which requires an expert to code.  There are problems with a code-centric approach to defining geometries for end users, as opposed to a data oriented system that binds to a standard API.  The latter has a number of advantages over the former.
-

 \section{GDML}
 

+% topic: GDML/geometry
+%% geometry major part of the simulation setup
+%% solved some time ago with GDML data binding (references/history here)
+%% how does it answer question? import/export/exchange
+%% geometry is only a part of the project; still need regions, physics limits, fields, visualization, etc.
+

 \par
 GDML, or Geometry Description Markup Language, is an XML binding to the Geant4 geometry API, based upon work originally done for the LHCb project.  That collaboration’s XML tools were used as the basis for a more generic geometry data format.  In addition to Geant4, there is a GDML binding to the ROOT framework.  This allows users to define their geometries using a data-driven approach rather than having to write C++ source code.  Both frameworks provide services such as locating volumes given 3D points and traversing the geometry hierarchy.
 

@@ -162,8 +184,15 @@

 \par
 LCDD is built upon the GDML data format and C++ parser.  It extends GDML’s XML data format by using facilities of the XML Schema (XSD) language.  It reuses the GDML code infrastructure by registering additional element handlers with GDML’s parser.  The extension point is the volume element, which may contain references to LCDD objects, such as sensitive detectors.  One benefit of this approach is that the parser, without any alteration, can also read in plain GDML files.
 

+%% put here a skeleton XML document showing the overall LCDD structure
+%% then work through the example linearly through rest of paper!!!
+
+%% mention existence of schema that is checked at runtime with location reference (subsection?)
+

 \section{Volume Extension}
 

+%% FIXME: too much technical detail here (appendix?)
+

 \par
 The volume element in GDML is the only part of the format that is changed in order to connect it to associated LCDD objects.  This is the portion of the XML schema definition that extends this part of GDML.
 

@@ -187,6 +216,8 @@

 
 \section{Volume Element}
 

+%% FIXME: move to end after all elements have been described
+

 \par
 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.
 

@@ -233,6 +264,9 @@

 \par
 All extend a common XML element within the schema, which defines basic settings for every sensitive detector.  Each detector has a name, used to uniquely identify it within the document.  The name is used to connect individual logical volumes with their sensitive detectors.  A sensitive detector also has an associated hits collection where the hits in the sensitive detector will be stored.  Different detectors may write into the same hits collection.  There is a a flag indicates whether or not the detector is an end cap.  An energy cut setting can be used to discard hits that do not reach certain threshold.  There is a verbosity setting to control print screen output from the detector while the simulation is running.  Except for the name of the detector and its corresponding hit collection, which are required, these settings are all optional.  There is also an optional child element on each detector, pointing to the identifier specification that will be used to assign uniqu!
 e identifier[...]
 

+%% describe abstractly concept of detectors
+%% use calorimeters and trackers as example solutions of a problem
+

 \subsection{Trackers}
 
 \par

@@ -277,7 +311,7 @@

 \section{Segmentation}
 
 \par

-Sensitive volumes in a calorimeter detector usually require virtual subdivision in order that energy depositions can be summed and saved to hits with the proper granularity of identifier and position.  In LCDD, the concept of artifically dividing these volumes is called “segmentation.”  For highly segmented calorimeters, such as those found in ILC detector concepts, it would require literally millions of individual cell volumes to model the readouts as built, which could be prohibitive in terms of memory usage, as well as highly complicated to implement in the XML.  There are also cases where simulating a complex readout is more straightforward when performed by an algorithm rather than modeling it geometrically, such as with projective readouts that have many different shapes and sizes of cells.

+Sensitive volumes in a calorimeter detector usually require virtual subdivision in order that energy depositions can be summed and saved to hits with the proper granularity of identifier and position.  In LCDD, the concept of artificially dividing these volumes is called “segmentation.”  For highly segmented calorimeters, such as those found in ILC detector concepts, it would require literally millions of individual cell volumes to model the readouts as built, which could be prohibitive in terms of memory usage, as well as highly complicated to implement in the XML.  There are also cases where simulating a complex readout is more straightforward when performed by an algorithm rather than modeling it geometrically, such as with projective readouts that have many different shapes and sizes of cells.

 
 \par
 All segmentation elements extend a basic type that has no attributes.  The parameters defining the size of the cells are specific to the sub-type of segmentation.  This element is a child of the calorimeter that will use it, and each calorimeter detector is allowed to have one of these.  The implementation classes define names that can be referenced in identifier descriptions for writing the cell field values at a certain position into the output identifiers of the hits.  These are called bin values because they are similar to histogram bins.

@@ -433,6 +467,10 @@

 </display>
 \end{verbatim}
 

+
+%% example N04 in Geant4 (N04.lcdd)
+%% mention compact XML description as way to intermediate between low level description and the user
+

 \section{Examples}
 
 \par