--- docs/pubs/0001-lcdd/lcdd-paper.tex	2014-10-21 16:06:05 UTC (rev 3378)
+++ docs/pubs/0001-lcdd/lcdd-paper.tex	2014-10-21 16:41:09 UTC (rev 3379)
@@ -40,8 +40,8 @@

 %%
 
 %% target: full-length writeup, shorten as necessary for NIM, CPC, etc.

-\documentclass[preprint,12pt,3p]{elsarticle}
-%\documentclass[final,3p,times,twocolumn]{elsarticle}

+%\documentclass[preprint,12pt,3p]{elsarticle}
+\documentclass[final,3p,times,twocolumn]{elsarticle}

 \usepackage{url}
 \usepackage{gensymb}
 \usepackage{graphicx}

@@ -190,10 +190,6 @@

 
 LCDD uses GDML to provide the complete physical geometry for the simulation.  The {\tt gdml} root node is embedded as part of the LCDD document.  The GDML language is essentially left intact with only minor additions.  The main point of extension is the {\tt volume} element, which is redefined so that it may contain additional references to LCDD elements.  The child volumes are also redefined so that they may have one or more physical volume identifiers attached to them.  Using this approach, a GDML volume can be associated with important supplementary information such as readout parameters.
 

-LCDD is built upon the GDML data format and code infrastructure.  GDML itself uses the Xerces C++ \cite{xerces} XML toolkit for parsing and schema validation.  LCDD extends GDML by using built-in facilities of the XML Schema (XSD) language such as the {\tt xs:redefine} and {\tt xs:extension} elements.  The GDML parser is also used by registering additional element handlers for LCDD types.  This extended parser is then able to read both plain GDML and LCDD documents.
-
-Every LCDD file has the same basic structure that is enforced through XML schema checking at runtime against the document contents.
-

 \begin{verbatim}
     <lcdd>
         <header/>

@@ -242,12 +238,14 @@

     </lcdd>
 \end{verbatim}
 

-The LCDD parser checks the input document for correctness against the XML Schema, which is located at a standard URL accessible via the {\tt http} protocol.

-\begin{verbatim}
-    http://www.lcsim.org/schemas/lcdd/1.0/lcdd.xsd
-\end{verbatim}

+LCDD is built upon the GDML data format and code infrastructure.  GDML itself uses the Xerces C++ \cite{xerces} XML toolkit for parsing and schema validation.  LCDD extends GDML by using built-in facilities of the XML Schema (XSD) language such as the {\tt xs:redefine} and {\tt xs:extension} elements.  The GDML parser is also used by registering additional element handlers for LCDD types.  This extended parser is then able to read both plain GDML and LCDD documents.

+Every LCDD file has the same basic structure that is enforced through XML schema checking at runtime against the document contents.
+
+
+The LCDD parser checks the input document for correctness against the XML Schema, which is located at a standard URL accessible via the {\tt http} protocol, viz. {\tt www.lcsim.org/schemas/lcdd/1.0/lcdd.xsd}.
+

 The {\tt lcdd} root element has a number of sections, most of which contain a list of elements with a specific type.  Each of these elements has a name assigned to it, which can be used as a unique reference within the document.  The GDML volumes may reference these LCDD elements by their names.  In this way, the information in LCDD is linked to specific volumes defined by GDML.
 
 The {\tt 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 {\tt iddict} is a collection of identifier dictionaries that provide encodings for packed, 64-bit IDs, which contain encoded values such as a layer number or a detector ID.  The {\tt sensitive\_detectors} element defines sensitive detectors that can be assigned to volumes, flagging them as readout components capable of producing hits.  The {\tt 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 {\tt display} element contains visualization settings that assign colors and other visibility parameters to logical volumes.  The {\tt gdml} section contains an entire, embedded GDML document, which must conform to that format's XML syntax.  It may also include the additional el!
 ements defin[...]

@@ -257,13 +255,16 @@

 Every document begins with a {\tt header} that provides basic meta data about the file and the detector.
 
 \begin{verbatim}

-    <header>
-        <detector name="sidloi3"/>
-        <generator name="GeomConverter"¯ version="1.0"
-            file="./detectors/sidloi3/compact.xml" checksum="€¯2152839912"/>
-        <author name="Jeremy McCormick" email="[log in to unmask]">
-        <comment>The SiD detector</comment>
-    </header>

+<header>
+ <detector name="sidloi3"/>
+ <generator name="GeomConverter"¯ 
+            version="1.0"
+            file="./sidloi3/compact.xml" 
+            checksum="€¯2152839912"/>
+ <author name="Jeremy McCormick" 
+      email="[log in to unmask]">
+ <comment>The SiD detector</comment>
+</header>

 \end{verbatim}
 
 The {\tt 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 {\tt 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.

@@ -280,9 +281,9 @@

 \centering
 \begin{tabular}{ | l | l | }
 \hline

-{\tt name} & unique string identifying the sub-detector \\ \hline
-{\tt endcap\_flag} & indicates if volume is a barrel or endcap \\ \hline
-{\tt ecut} & a minimum energy cut for individual hits \\ \hline

+{\tt name} & unique sub-detector identifier \\ \hline
+{\tt endcap\_flag} & barrel or endcap flag\\ \hline
+{\tt ecut} & minimum energy cut for hits \\ \hline

 {\tt eunit} & energy unit for cut \\ \hline
 {\tt verbose} & verbosity setting \\
 \hline

@@ -305,9 +306,10 @@

 This is an example of a simple tracking detector:
 
 \begin{verbatim}

-    <tracker name="¯SiTrackerBarrel"¯ hits_collection="¯SiTrackerBarrelHits">
-        <idspecref ref="SiTrackerBarrelHits"/>
-    </tracker>

+<tracker name="¯BarrelTracker"¯ 
+   hits_collection="¯BarrelTrackerHits">
+  <idspecref ref="BarrelTrackerHits"/>
+</tracker>

 \end{verbatim}
 
 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.

@@ -319,10 +321,14 @@

 The following XML defines a calorimeter with uniform sized cells created by a virtual segmentation class.  The {\tt 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">
-        <idspecref ref="EcalBarrelHits"/>
-        <grid_xyz grid_size_x="3.5*mm"¯ grid_size_y="¯3.5*mm"¯ grid_size_z="0.0"/>
-    </calorimeter>

+<calorimeter name="EcalBarrel"¯ 
+  hits_collection="EcalBarrelHits">
+  <idspecref ref="EcalBarrelHits"/>
+  <grid_xyz 
+    grid_size_x="3.5*mm"¯ 
+    grid_size_y="¯3.5*mm"¯ 
+    grid_size_z="0.0"/>
+</calorimeter>

 \end{verbatim}
 
 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, this 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.

@@ -346,7 +352,9 @@

 The following XML shows a {\tt grid\_xyz} segmentation that divides a volume along the X and Y axes.
 
 \begin{verbatim}

-    <grid_xyz grid_size_x="1.0*cm" grid_size_y="1.0*cm" />

+    <grid_xyz 
+      grid_size_x="1.0*cm" 
+      grid_size_y="1.0*cm" />

 \end{verbatim}
 
 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, such as X and Y, with the third dimension, e.g. Z, left unsegmented.

@@ -358,7 +366,9 @@

 This is an example of a projective cylinder segmentation that divides the theta and phi regions into 32 and 32 bins, respectively.
 
 \begin{verbatim}

-    projective_cylinder ntheta="32" nphi="32" />

+    projective_cylinder 
+      ntheta="32" 
+      nphi="32" />

 \end{verbatim}
 
 This segmentation is used, for instance, in geometries where the calorimeter barrel is modeled using a series of nested tubes, rather than modules containing planar layers.

@@ -370,7 +380,9 @@

 A {\tt nonprojective\_cylinder} segmentation element will divide the surface of a cylinder into cells of equal size along its length.
 %% TODO is the segmentation in phi really in r*phi?
 \begin{verbatim}

-    <nonprojective_cylinder grid_size_phi="10.0*mm" grid_size_z="¯10.0*mm"¯ />

+    <nonprojective_cylinder 
+      grid_size_phi="10.0*mm" 
+      grid_size_z="¯10.0*mm"¯ />

 \end{verbatim}
 
 The above segmentation will divide the surface of a cylinder into 10 x 10 mm cells.

@@ -404,7 +416,7 @@

 
     % side view
     %shifting coordinate

-    \coordinate (shift) at (2*\zLength+2cm, 0);

+    \coordinate (shift) at (2*\zLength+.2cm, 0);

     \begin{scope}[shift=(shift)]
      %projective z segmentation
      % The 'spokes'

@@ -449,7 +461,9 @@

 The {\tt projective\_zplane} segmentation divides an endcap zplane into projective angular segments specified by the number of phi and theta bins, much as a {\tt projective\_cylinder} is used for a barrel.
 
 \begin{verbatim}

-    <projective_zplane ntheta="¯500" nphi="¯500" />

+    <projective_zplane 
+    ntheta="¯500" 
+    nphi="¯500" />

 \end{verbatim}
 
 %\subsection{Global Grid XYZ Segmentation}

@@ -473,16 +487,22 @@

 Below is an example of an identifier definition for a calorimeter.
 
 \begin{verbatim}

-    <idspec name="EcalBarrelHits" length="64">
-        <idfield signed="false" label="system" length="6" start="0"/>
-        <idfield signed="false" label="barrel" length="3" start="6"/>
-        <idfield signed="false" label="module" length="4" start="9"/>
-        <idfield signed="false" label="layer" length="6" start="13"/>
-        <idfield signed="false" label="slice" length="5" start="19"/>
-        <idfield signed="true" label="x" length="16" start="32"/>
-        <idfield signed="true" label="y" length="16" start="48"/>
-        </idfield>
-    </idspec>

+<idspec name="EcalBarrelHits" length="64">
+<idfield signed="false" 
+    label="system" length="6" start="0"/>
+<idfield signed="false" 
+    label="barrel" length="3" start="6"/>
+<idfield signed="false" 
+    label="module" length="4" start="9"/>
+<idfield signed="false" 
+    label="layer" length="6" start="13"/>
+<idfield signed="false" 
+    label="slice" length="5" start="19"/>
+<idfield signed="true" 
+    label="x" length="16" start="32"/>
+<idfield signed="true" 
+    label="y" length="16" start="48"/>
+</idspec>

 \end{verbatim}
 
 The first five fields of the above identifier derive from the {\tt physvolid} values.  The ``x''¯ and ``y''¯ values are read from the segmentation bins at the hit position.  The concatenation of these values identifies a unique readout channel in the detector.  The packed values can be subsequently decoded within an external framework to retrieve the associated detector information for a specific hit.

@@ -494,11 +514,14 @@

 The following example will restrict the step lengths of all particles to 5 mm.
 
 \begin{verbatim}

-    <limits>
-        <limitset name="cal_limits">
-            <limit name="step_length_max" unit="mm" particles="*" value="5.0" />
-        </limitset>
-    </limits>

+<limits>
+  <limitset name="cal_limits">
+  <limit name="step_length_max" 
+         unit="mm" 
+         particles="*" 
+         value="5.0" />
+ </limitset>
+</limits>

 \end{verbatim}
 
 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.

@@ -524,10 +547,13 @@

 Regions are assigned to geometric volumes using the {\tt region} element, defining 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.''
 
 \begin{verbatim}

-    <regions>
-        <region name="TrackingRegion" store_secondaries="true"
-            cut="10.0" lunit="mm" threshold="1.0" eunit="MeV" />
-    </regions>

+<regions>
+  <region name="TrackingRegion" 
+          store_secondaries="true"
+          cut="10.0" lunit="mm" 
+          threshold="1.0" 
+          eunit="MeV" />
+</regions>

 \end{verbatim}
 
 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.

@@ -537,14 +563,14 @@

 LCDD extends GDML by adding additional, optional elements to volumes.  The following example assigns to a volume a sensitive detector, a 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>

+<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 referenced LCDD objects are previously defined in the document.  For instance, 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 {\tt volume} elements.

@@ -554,14 +580,15 @@

 Physical volumes in GDML are also extended so that they may have one or more physical volume IDs associated with them.  These values can be used in 64-bit identifiers that are attached to hits.  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>

+<volume name="DetectorEnvelope">
+  <materialref ref="Air"/>
+  <solidref ref="DetectorEnvelopeBox"/>
+  <physvol>
+  <volumeref ref="LayerVolume"/>
+  <physvolid field_name="layer" 
+             value="1"/>
+  </physvol>
+</volume>

 \end{verbatim}
 
 Any number of {\tt physvolid} elements can be added to a single {\tt physvol}, so the assignment of these identifier values need not be limited by the hierarchical structure of the detector.

@@ -578,11 +605,17 @@

 The following defines a solenoid with a constant 5 Tesla field strength within the inner radius and a return field strength of -0.6 Tesla outside of that.
 
 \begin{verbatim}

-    <fields>
-        <solenoid name="GlobalSolenoid" lunit="mm" funit="tesla"
-            outer_radius="world_side" inner_field="5.0" outer_field="-0.6"
-            zmax="1000.0" zmin="-1000.0" inner_radius="2923.0" />
-    </fields>

+<fields>
+  <solenoid name="GlobalSolenoid" 
+            lunit="mm" 
+            funit="tesla"
+            outer_radius="world_side" 
+            inner_field="5.0" 
+            outer_field="-0.6"
+            zmax="1000.0" 
+            zmin="-1000.0" 
+            inner_radius="2923.0" />
+</fields>

 \end{verbatim}
 
 \subsubsection{Dipole}

@@ -594,11 +627,13 @@

 Here is an example of a dipole field definition.
 
 \begin{verbatim}

-    <dipole name="ExampleDipoleField" zmin="0.0" zmax="-10.0*mm" >
-        <dipole_coeff value="1.0" />
-        <dipole_coeff value="0.1" />
-        <dipole_coeff value="0.001" />
-    </dipole>

+<dipole name="ExampleDipoleField" 
+        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}
 
 \subsubsection{Box Dipole}

@@ -606,10 +641,10 @@

 The {\tt box\_dipole} is used to define a set of fixed component values in a box-like region.
 
 \begin{verbatim}

-    <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" />

+<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}
 
 \subsubsection{RZ Field Map}

@@ -617,14 +652,19 @@

 An RZ field map can be used to simulate a cylindrically symmetric field variable in the radial and Z directions.
 The field is input as a map of $B_z$ and $B_r$ on a regular grid of radius and z positions.
 \begin{verbatim}

-    <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>

+<rz_field_map name="RZFieldMap" 
+              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." r="0." Bz="50.0" Br="0." />
+<rzB z="10." r="0." Bz="49.9" Br="0." />
+<rzB z="20." r="0." Bz="49.9" Br="0." />
+<rzB z="30." r="0." Bz="49.8" Br="0." />
+  [etc.]
+</rz_field_map>

 \end{verbatim}
 
 The Z and R bins are computed from the global position.  Then the B-field ($B_z$, $B_r$) is calculated by linear interpolation in 2 dimensions (Z, R) between these points.

@@ -645,9 +685,13 @@

 Here is an example that references an external data file.
 
 \begin{verbatim}

-    <field_map_3d name="FieldMap3DTest" lunit="mm" funit="tesla"
-        filename="data/HPS_b18d36_unfolded.dat"
-        xoffset="2.117" yoffset="0.0" zoffset="45.72" />

+<field_map_3d name="FieldMap3D" 
+              lunit="mm" 
+              funit="tesla"
+  filename="data/3DFieldMap.dat"
+  xoffset="2.117" 
+  yoffset="0.0" 
+  zoffset="45.72" />

 \end{verbatim}
 
 \subsection{Visualization}

@@ -657,45 +701,28 @@

 The following is an example of visualization attributes.
 
 \begin{verbatim}

-    <display>
-        <vis name="¯CalVis"¯ line_style="¯unbroken"¯ drawing_style="solid"
-            show_daughters="true"¯ visible="¯true"€>
-            <color R="1.0" G="¯0.0" B="0.0"¯ alpha="¯1.0"/>
-        </vis>
-    </display>

+<display>
+  <vis name="¯CalVis"¯ 
+       line_style="¯unbroken"¯ 
+       drawing_style="solid"
+       show_daughters="true"¯ 
+       visible="¯true">
+       <color R="1.0" 
+              G="¯0.0" 
+              B="0.0"¯ 
+              alpha="¯1.0"/>
+  </vis>
+</display>

 \end{verbatim}
 
 \section{Using LCDD in an Application}
 

-The LCDD framework implements G4VUserDetectorConstruction, which is a required class for Geant4 user applications.  Using LCDD is simply a matter of registering its detector construction class with the Geant4 run manager.

+The LCDD framework implements G4VUserDetectorConstruction, which is a required class for Geant4 user applications.  Using LCDD is simply a matter of registering its detector construction class with the Geant4 run manager, viz. {\tt theRunManager->SetUserInitialization(new LCDDDetectorConstruction());}.
+This allows the detector document to be specified using a macro command, such as the following, which will load a document from a remote URL {\tt /lcdd/url http://www.lcsim.org/detectors/sidloi3/sidloi3.lcdd}.
+Local files can also be read in by using the {\tt file://} protocol: {\tt /lcdd/url file:///local/path/to/sidloi3.lcdd}. Arguments to this macro command without a protocol are interpreted as local files, {\tt /lcdd/url /local/path/to/sidloi3.lcdd}. The detector document must be specified 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 {\tt /run/initialize} macro command.

-\begin{verbatim}
-    theRunManager->SetUserInitialization(new LCDDDetectorConstruction());
-\end{verbatim}

+%\pagebreak

-This allows 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 {\tt 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 specified 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 {\tt /run/initialize} macro command.
-
-
-\pagebreak
-

 \section{Examples}
 
 \subsection{Linear Collider}