docs/pubs/0001-lcdd
--- docs/pubs/0001-lcdd/lcdd-paper.tex 2014-08-14 18:12:53 UTC (rev 3262)
+++ docs/pubs/0001-lcdd/lcdd-paper.tex 2014-08-14 18:57:20 UTC (rev 3263)
@@ -97,7 +97,7 @@
% \biboptions{}
-\journal{Nuclear Physics B}
+%\journal{Nuclear Physics B}
\begin{document}
@@ -144,8 +144,25 @@
\subsection{GDML}
-The Geometry Description Markup Language (GDML) is an XML language for describing detector geometries using materials, mathematical variables and definitions, solids such as boxes and tubes, and a hierarchical structure of logical and physical volumes. Originally developed as a standalone application, GDML has become part of the Geant4 source distribution. Therefore, it serves as an ideal starting point for a complete detector description language. The syntax and usage of GDML is fully described in the \textit{GDML User's Guide}. \cite{gdmlguide}
+The Geometry Description Markup Language (GDML) is an XML language for describing detector geometries using materials, mathematical variables and definitions, solids such as boxes and tubes, and a hierarchical structure of logical and physical volumes. Originally developed as a standalone application, GDML has become part of the Geant4 source distribution. Therefore, it serves as an ideal starting point for a complete detector description language. The syntax and usage of GDML is fully described in the \textit{GDML User's Guide}~\cite{gdmlguide} but a brief overview is provided here for completeness. Every valid GDML file has the following basic structure.
+\begin{verbatim}
+ <gdml>
+ <define/>
+ <materials/>
+ <solids/>
+ <structure>
+ <volume>
+ <materialref/>
+ <physvol>
+ <volumref/>
+ </physvol>
+ </volume>
+ </structure>
+ <setup/>
+ </gdml>
+\end{verbatim}
+
GDML's \textit{define} block contains expressions and definitions that are composed of double precision numbers, simple arithmetic operators (* / + -), trigonometric functions, and units. The CLHEP expression evaluator is used to parse and evaluate these mathematical statements. The processor predefines standard units for distance, weight, etc., as well as a set of constants such as the speed of light. Rotations and positions that will be referenced later to create physical volumes may also be included in this section.
The \textit{materials} section has a list of \textit{material} and \textit{element} tags that bind to the G4Material and G4Element classes for materials and atomic elements. Materials are defined by atomic or mass composition and density. Material parameter sheets may be attached to provide pre-computed values for dEdx calculations and optical properties.
@@ -165,51 +182,51 @@
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/>
- <iddict>
- <idspec>
- <idfield/>
- </idspec
- </iddict>
- <sensitive_detectors>
- <calorimeter/>
- <tracker/>
- <scorer/>
- </sensitive_detectors>
- <limits>
- <limitset>
- </limit>
- </limitset>
- </limits>
- <regions>
- <region/>
- </regions>
- <display>
- <vis/>
- </display>
- <gdml>
- <define/>
- <materials/>
- <solids/>
- <structure>
- <volume>
- <sdref/>
- <limitsetref/>
- <regionref/>
- <visref/>
- </volume>
- </structure>
- <setup/>
- </gdml>
- <fields>
- <solenoid/>
- <dipole/>
- <box_dipole/>
- <rz_field_map/>
- <field_map_3d/>
- </fields>
-</lcdd>
+ <lcdd>
+ <header/>
+ <iddict>
+ <idspec>
+ <idfield/>
+ </idspec
+ </iddict>
+ <sensitive_detectors>
+ <calorimeter/>
+ <tracker/>
+ <scorer/>
+ </sensitive_detectors>
+ <limits>
+ <limitset>
+ </limit>
+ </limitset>
+ </limits>
+ <regions>
+ <region/>
+ </regions>
+ <display>
+ <vis/>
+ </display>
+ <gdml>
+ <define/>
+ <materials/>
+ <solids/>
+ <structure>
+ <volume>
+ <sdref/>
+ <limitsetref/>
+ <regionref/>
+ <visref/>
+ </volume>
+ </structure>
+ <setup/>
+ </gdml>
+ <fields>
+ <solenoid/>
+ <dipole/>
+ <box_dipole/>
+ <rz_field_map/>
+ <field_map_3d/>
+ </fields>
+ </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 \textit{http} protocol.
@@ -227,13 +244,13 @@
Every document begins with a 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="./detectors/sidloi3/compact.xml" checksum="€¯2152839912"/>
+ <author name="Jeremy McCormick" email="[log in to unmask]">
+ <comment>The SiD detector</comment>
+ </header>
\end{verbatim}
The \textit{detector} tag provides a name attribute that can be used as an external ID. For instance, the name can be written into the run headers of output data files to identify which detector was used to generate those events. An \textit{author} element gives the names of the authors of the file, as well as an email contact. The generator provides information about an external program that was used to generate the file, if applicable, including a source file name, a version of that program, and a checksum that could be created with an MD5 algorithm. Finally, there is a comment block that may be used to provide additional descriptive text about the detector.
@@ -267,9 +284,9 @@
This is an example of a simple tracking detector:
\begin{verbatim}
-<tracker name="¯SiTrackerBarrel"¯ hits_collection="¯SiTrackerBarrelHits">
- <idspecref ref="SiTrackerBarrelHits"/>
-</tracker>
+ <tracker name="¯SiTrackerBarrel"¯ hits_collection="¯SiTrackerBarrelHits">
+ <idspecref ref="SiTrackerBarrelHits"/>
+ </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.
@@ -285,10 +302,10 @@
The following XML defines a calorimeter with uniform sized cells created by a virtual segmentation class. The \textit{grid\_xyz} element will divide the detector's sensor layers into a grid of 3.5mm x 3.5mm cells.
\begin{verbatim}
-<calorimeter name="EcalBarrel"¯ hits_collection="EcalBarrelHits">
- <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.
@@ -312,7 +329,7 @@
The following XML shows a \textit{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.
@@ -324,7 +341,7 @@
This is an example of a projective cylinder segmentation that divides the theta and phi regions into 1000 and 2000 bins, respectively.
\begin{verbatim}
-<projective_cylinder ntheta="1000"€¯ nphi="2000" />
+ projective_cylinder ntheta="1000"€¯ nphi="2000" />
\end{verbatim}
This segmentation is used in geometries where the calorimeter barrel is modeled using a series of nested tubes, rather than modules containing planar layers.
@@ -336,7 +353,7 @@
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*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.
@@ -348,7 +365,7 @@
The \textit{projective\_zplane} segmentation divides an endcap zplane into projective segments, much as a \textit{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}
@@ -372,16 +389,16 @@
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"/>
+ </idfield>
+ </idspec>
\end{verbatim}
The first five fields of the above identifier derive from the \textit{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.
@@ -393,11 +410,11 @@
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.
@@ -418,10 +435,10 @@
Regions are assigned to geometric volumes using the \textit{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.
@@ -437,11 +454,11 @@
The following defines a solenoid with a 5 tesla field strength.
\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}
@@ -453,11 +470,11 @@
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}
@@ -465,10 +482,10 @@
The \textit{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}
@@ -476,14 +493,14 @@
An RZ field map can be used to simulate a variable field in the radial and Z directions with a uniform phi.
\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="RZFieldMapTest" lunit="cm" funit="kilogauss"
+ num_bins_r="67" num_bins_z="64" grid_size_z="10.0" grid_size_r="10.0">
+ <rzB z="0.0" r="0.0" Bz="50.011" Br="0.0" />
+ <rzB z="10.0" r="0.0" Bz="49.996" Br="0.0" />
+ <rzB z="20.0" r="0.0" Bz="49.95" Br="0.0" />
+ <rzB z="30.0" r="0.0" Bz="49.874" Br="0.0" />
+ [etc.]
+ </rz_field_map>
\end{verbatim}
The Z and R bins are computed from the global position. Then the B-field (Bz, Br) is calculated by linear interpolation in 2 dimensions (Z, R) between these points.
@@ -495,15 +512,15 @@
Here is an example that references a 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="FieldMap3DTest" lunit="mm" funit="tesla"
+ filename="data/HPS_b18d36_unfolded.dat"
+ xoffset="2.117" yoffset="0.0" zoffset="45.72" />
\end{verbatim}
The field values are contained in an external file with each line defining a point in the map.
\begin{verbatim}
-x, y, z, Bx, By, Bz
+ x, y, z, Bx, By, Bz
\end{verbatim}
A 3D interpolation is performed to determine the B-field (Bx, By, Bz) at a given point (x, y, z) in the grid, based on an algorithm developed from the PurgMagTabulatedField3D Geant4 code example. \cite{purgemag}
@@ -515,12 +532,12 @@
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}
\subsection{Using LCDD in an Application}
@@ -528,25 +545,25 @@
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.
\begin{verbatim}
-theRunManager->SetUserInitialization(new LCDDDetectorConstruction());
+ theRunManager->SetUserInitialization(new LCDDDetectorConstruction());
\end{verbatim}
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
+ /lcdd/url http://www.lcsim.org/detectors/sidloi3/sidloi3.lcdd
\end{verbatim}
Local files can also be read in by using the \textit{file://} protocol.
\begin{verbatim}
-/lcdd/url file:///local/path/to/sidloi3.lcdd
+ /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
+ /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 \textit{/run/initialize} macro command.
@@ -556,14 +573,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 \textit{volume} elements.
@@ -573,14 +590,14 @@
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"/>
+ </phyvol>
+ </volume>
\end{verbatim}
Any number of \textit{physvolid} elements can be added to a single \textit{physvol}, so the assignment of these identifier values need not be limited by the hierarchical structure of the detector.