--- docs/pubs/0001-lcdd/lcdd-paper.tex	2014-06-17 17:35:22 UTC (rev 3155)
+++ docs/pubs/0001-lcdd/lcdd-paper.tex	2014-06-26 05:37:34 UTC (rev 3156)
@@ -27,7 +27,7 @@

 
 %% target: full-length writeup, shorten as necessary for NIM, CPC, etc.
 \documentclass[preprint,12pt,3p]{elsarticle}

-

+\usepackage{gensymb}

 \usepackage{graphicx}
 \graphicspath{ {images/} }
 

@@ -116,7 +116,7 @@

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

-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 provid!
 es an XML geometry description, but not the compl[...]

+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 response simulations in high energy physics (HEP) and is increasingly being applied in other disciplines such as medical physics and applications in the aerospace industry. However, it is designed as a toolkit rather than a pre-packaged executable and is also large and complex.  End users must assemble an application based upon their individual requirements, requiring a considerable amount of expertise both in the details of configuring the framework and in the C++ language. Providing a flexible application based on Geant4 which can meet the needs of many different users can alleviate this technical hurdle and perhaps speed its adoption in other application domains. This approach requires that the simulation parameters be defined at runtime rather than embedded into custom source code!
 . Ideally, in an application of this type the c[...]

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

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

+Some physics simulation programs use their own custom-defined data input formats for detector descriptions 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 application programming interface (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 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.

+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 the Geant4 APIs.  They may instead focus on defining the simulation inputs for their particular experiment.

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

+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.  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,21 +155,21 @@

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

+The 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 surfaces.  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. GDML provides bindings to the core geometry classes of GEANT4, and 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 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.

+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 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.  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, a!
 s 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.  The 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 file!
 s, as well as LCDD.

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

+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 intact, 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, 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.
-

+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.
+Unlike some markup languages, such as HTML, where elements can be referenced regardless of order, GDML and LCDD support in-order references only.  An element must have already been defined to be referenced.  For this reason, the ordering of the top-level container elements in GDML and LCDD files is important and must conform to the order specified in their respective schemas.  For instance, a box solid must be defined before it can be used as the shape for a volume.  The primary benefit of this approach is reduction of memory consumption during the processing phase. The following snippet of pseudo-XML outlines the top-level structure of an LCDD file, including the embedded GDML element.

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

@@ -189,13 +189,13 @@

 </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 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 ca!
 n be assigned additional information.  Finally, t[...]

+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 ca!
 n be assigned additional information.  Finally,[...]

 
 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}
 

-Every LCDD document begins with a header that provides basic meta data about the file and the detector.

+Every LCDD document begins with a header that provides basic metadata about the file and the detector.

 
 \begin{verbatim}
 <header>

@@ -207,11 +207,11 @@

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

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

-A "sensitive detector" 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 the volume, hit objects may be created and can later be written into an output file for analysis.  The sensitive detectors typically accumulate position, time and energy measurements from particle interactions within the material of a volume.  Usually these hits are grouped into collections by event.

+A ''sensitive detector'' 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 the volume, hit objects may be created and can later be written into an output file for analysis.  The sensitive detectors typically accumulate position, time and energy measurements from particle interactions within the material of a volume.  Usually these hits are grouped into collections by event.

 
 Two primary types of detectors are modeled by the framework.  Trackers typically 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 for the accumulation of energy in cellular volumes, and typically have much less granular position information.  Calorimeters 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.
 

@@ -227,15 +227,15 @@

   \hline
 \end{tabular}
 

-Each detector has a name that is used to uniquely identify it within the document.  This is used to associate logical volumes with a sensitive detector using the \textit{sdref} element.  There is a a flag 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 for discard hits that do not reach a certain threshold energy.  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 rest of the settings are optional.

+Each detector has a name that is used to uniquely identify it within the document.  This is used to associate logical volumes with a 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 hits that do not reach a certain threshold energy.  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 rest of the settings are optional.

-The detectors have associated hits collections that contain objects which are implementations of the virtual hit class within Geant4.  There is no output data binding providing 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 a desired output format such as LCIO.

+The detectors have associated hits collections that contain objects which are implementations of the virtual hit class within Geant4.  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 a desired output format such as LCIO.

 
 \subsection{Trackers}
 
 Trackers record information from each step of a simulated track as it propagates through a sensitive volume.  The stored information includes the mid-point position, direction, length, global time in nanoseconds when the step occurred in the simulation, and the energy deposited along the step length.  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 detectors, such as those with pixels or silicon strips.  Advanced algorithms for digitizing the hits within the simulation are not provided, as it is assumed this would be done later in a reconstruction environment.
 

-This is the XML for a simple tracking detector, similar to what might be defined for an ILC full detector concept:

+This is an example XML snippet for a simple tracking detector, similar to what might be defined for an ILC full detector concept:

 
 \begin{verbatim}
 <tracker name=”SiTrackerBarrel” hits_collection=”SiTrackerBarrelHits”>

@@ -249,7 +249,7 @@

 
 \subsection{Calorimeter}
 

-The Calorimeter detector is used to model total energy deposition of showering particles in a volume.  These are generally either sampling calorimeters with alternating absorber and sensor layers, or homogeneous calorimeters such as arrays of Lead Tungstate crystals.  Energy depositions are accumulated from multiple steps to determine the total energy deposited in the volume for the event.  These energy depositions may be accumulated in an entire volume, such as a physical crystal, or the energy may be split across arrays of cells that are created through a virtual segmentation of the volume.  In general, when the volumes are segmented, there is one hit object created per cell for the entire event. Each calorimeter may have an associated \t!
 extit{segmentation} object that bins the energy depositions by position during the simulation.

+The Calorimeter detector is used to record the energy deposition of showering particles in a volume.  Since the details of each step of individual secondary particles generated in such a shower are usually not of interest, energy depositions are accumulated from multiple steps to determine the total energy deposited in the volume for the event.  These energy depositions may be accumulated in an entire volume, such as a physical crystal, or the energy may be split across arrays of cells that are created through a virtual segmentation of the volume.  In general, when the volumes are segmented, there is one hit object created per cell for the entire event. Each calorimeter may have an associated \textit{segmentation} object that bins the energy depositions by po!
 sition during the simulation.

 
 The following XML defines a calorimeter with uniform sized cells created by a virtual segmentation class.
 

@@ -264,7 +264,7 @@

 
 \section{Segmentation}
 

-Sensitive volumes in a calorimeter detector usually require virtual subdivision in order that energy depositions can be accumulated into cells.  This concept of dividing geometric volumes is modeled by specific concrete implements of the \textit{segmentation} element.  This algorithmic rather than geometric approach to segmented readout has other advantages.  Modeling millions of individual cell volumes could be prohibitive in terms of memory usage. There are also cases in which modeling a readout system with an algorithm rather than geometry is more simple, such as in projective towers where there are many different shapes and sizes of cells which would be complicated to model using only solids and volumes.

+Sensitive volumes in a calorimeter detector usually require virtual subdivision in order that energy depositions can be accumulated into cells.  This concept of dividing geometric volumes is modeled by specific concrete implementations of the \textit{segmentation} element.  This algorithmic, rather than geometric, approach to segmented readout has other advantages.  Modeling millions of individual cell volumes could be prohibitive in terms of memory usage. There are also cases in which modeling a readout system with an algorithm rather than geometry is more simple, such as in projective towers where there are many different shapes and sizes of cells which would be complicated to model using only solids and volumes.

 
 Concrete segmentation types extend a basic abstract element, which has no attributes.  The names of the parameters which define the dimensions of the cells are specific to a certain type of segmentation.  The segmentation element occurs as a child of the calorimeter sensitive detector.  Each calorimeter may have one of these associated objects.  The values of the fields from the segmentation at a certain hit position can be written in the identifiers of the hits by referencing their names.
 

@@ -282,7 +282,7 @@

 
 \subsection{Projective Cylinder Segmentation}
 

-The \textit{projective\_cylinder} segmentation divides cylinders into projective towers.  Unlike most other types of segmentations, this does not result in cells with uniform sizes.  The sizes of a given cell in a projective segmentation depends on its distance from the origin.  The \textit{nphi} parameters determines how many phi bins are created within the full 360 degrees.  Similarly, \textit{ntheta} specifies the number of theta bins, but uses 180 degrees.

+The \textit{projective\_cylinder} segmentation divides cylinders into projective towers.  Unlike most other types of segmentations, this does not result in cells with uniform sizes.  The sizes of a given cell in a projective segmentation depends on its distance from the origin.  The \textit{nphi} parameters determines how many phi bins are created within the full $360\degree$ in azimuth.  Similarly, \textit{ntheta} specifies the number of theta bins, covering the $180\degree$ in polar angle.

 
 This is an example of a projective cylinder segmentation that divides the theta and phi regions into 1000 and 2000 bins, respectively.
 

@@ -292,8 +292,8 @@

 
 \subsection{Non-projective Cylinder Segmentation}
 

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

+A \textit{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” grid_size_z=”10.0” />
 \end{verbatim}

@@ -302,7 +302,7 @@

 
 \subsection{Projective ZPlane Segmentation}
 

-The projective\_zplane segmentation divides an endcap zplane into projective segments.

+The \textit{projective\_zplane} segmentation divides an endcap zplane into projective segments.

 
 \begin{verbatim}
 <projective_zplane ntheta=”500” nphi=”500” />

@@ -310,7 +310,7 @@

 
 \subsection{Global Grid XYZ Segmentation}
 

-The global\_grid\_xyz segmentation divides a global space into regular sized rectalinear cells.

+The \textit{global\_grid\_xyz} segmentation divides a global space into regular sized rectilinear cells.

 
 \begin{verbatim}
 <global_grid_xyz grid_size_x=”50.0” grid_size_y=”50.0” />

@@ -318,13 +318,13 @@

 
 \section{Hits Processors}
 

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

+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 could write separate hit collections for the scintillation and Cherenkov energy depositions by using two different hits processors.

 
 \section{Identifiers}
 

-Identifiers associate hits from sensitive detectors to their geometric components, as well as cell indices from the segmentation grid, in the case of calorimeters.  Each sensitive detector may have an identifier specification associated with it.  This is used to construct a unique 64-bit ID from physical volume numbers, such as layer number, and segmentation values, like X and Y cell indices.  The user is ultimately responsible for making sure this combination of values uniquely identifies a hit.

+Identifiers associate hits from sensitive detectors to their geometric components, as well as cell indices from the segmentation grid in the case of calorimeters.  Each sensitive detector may have an identifier specification associated with it.  This is used to construct a unique 64-bit ID from physical volume numbers, such as layer number, and segmentation values, like X and Y cell indices.  The user is ultimately responsible for making sure this combination of values uniquely identifies a hit.

-All of the identifier specifications are contained in an ID dictionary called the iddict.  Each specification has a corresponding element called the idspec.  The idspec elements contain idfield tags that define a single field within the identifier.  These fields can be from 1 to 32 bits and may be signed or unsigned.

+All of the identifier specifications are contained in an ID dictionary called the \textit{iddict}.  Each specification has a corresponding element called the \textit{idspec}.  The \textit{idspec} elements contain \textit{idfield} tags that define a single field within the identifier.  These fields can be from 1 to 32 bits and may be signed or unsigned.

 
 Below is an example of an identifier for an ILC ECal detector.
 

@@ -345,7 +345,7 @@

 
 \section{Physics Limits}
 

-Physics limits can be assigned to volumes in order to control the low level behavior of the simulation.  For instance, for performance purposes, the range cut can be increased to control the simulation time of electromagnetic showers.

+Physics limits can be assigned to volumes in order to control the low-level behavior of the simulation.  For instance, for performance purposes, the range cut can be increased to control the simulation time of electromagnetic showers.

 
 The following example will restrict the step lengths to 5 mm.
 

@@ -361,7 +361,7 @@

 
 \section{Regions}
 

-Regions are assigned to geometric volumes using the 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 tracking region in which all secondary particles will be stored into the output.

+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 tracking region in which all secondary particles will be stored into the output.

 
 \begin{verbatim}
 <regions>

@@ -370,11 +370,11 @@

 </regions>
 \end{verbatim}
 

-The above example also specifies that particles which would not travel more than 10 millimeters will not be produce, and it also establishes an energy cut of 1 MeV for storing particles to the output.

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

-Realistic simulation of magnetic fields is typically an important part of the detector simulation.  There are currently three 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 in Bz.

+Realistic simulation of magnetic fields is typically an important part of the detector simulation.  There are currently three 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.

 
 \begin{verbatim}
 <fields>

@@ -388,7 +388,7 @@

 
 \section{Visualization}
 

-Geant4 has a number of built-in mechanisms for visualizing detectors.  These range from real-time visualization using OpenGL to 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 alpha.  A 0.0 alpha value would render the component invisible.  The following is an example of visualization attributes.

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

 
 \begin{verbatim}
 <display>

@@ -421,10 +421,10 @@

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

-

+%% TODO Flesh this out more

 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.

+A 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"