Warning, /tutorial-geometry-development-using-dd4hep/episodes/01-defining-geometry.md is written in an unsupported language. File is not indexed.
0001 ---
0002 title: "Geometry Definition"
0003 teaching: 15
0004 exercises: 10
0005 ---
0006
0007 ::::::::::::::::::::::::::::::::::::::::::::: questions
0008
0009 - How do we define geometry using DD4hep?
0010
0011 :::::::::::::::::::::::::::::::::::::::::::::
0012
0013 ::::::::::::::::::::::::::::::::::::::::::::: objectives
0014
0015 - Know where standard geometries are stored in `eic-shell`.
0016 - Understand the structure of a geometry description file.
0017
0018 :::::::::::::::::::::::::::::::::::::::::::::
0019
0020 ## Introduction
0021
0022 The [ePIC geometry](https://github.com/eic/epic) is described using the [DD4hep toolkit](https://dd4hep.web.cern.ch/dd4hep/).
0023
0024 DD4hep (Detector Description for High Energy Physics) is a toolkit which acts as a single, central source of detector information for simulation and reconstruction of simulated and experimental data. The core DD4hep geometry description is built around the [ROOT geometry package](https://root.cern/manual/geometry/) while providing automatic conversions to other geometrical representaions, such as exporting CAD models, surfaces for acts reconstruction, material maps but most importany, [Geant4](https://geant4.web.cern.ch/docs/) for carrying out simulations.
0025
0026 DD4hep additionally provides a much simplified wrapper around running Geant4 simulations, providing standardized output from sensitive detectors. In the case of the ePIC simulation, simulated particles and tracker/calorimeter hits are saved as collections in [EDM4hep format](https://github.com/key4hep/EDM4hep) (Event Data Model for High Energy Physics) built on [podio](https://github.com/AIDASoft/podio/blob/master/doc/doc.md) (plain-old-data I/O).
0027
0028 ## Lesson
0029
0030 We start the discussion of the geometry definition with an overview of the locations of geometry files, and what is included in these files.
0031
0032 ## Location of standard geometries in `eic-shell`
0033
0034 Several standard geometry versions are included in `eic-shell` under the `/opt/detector/` location. This includes (currently) at least the following:
0035
0036 ```bash
0037 $ ls -1 /opt/detector/
0038 epic-25.08.0
0039 epic-25.09.0
0040 epic-25.10.0
0041 epic-25.10.1
0042 epic-25.10.2
0043 epic-25.10.3
0044 epic-25.11.0
0045 epic-git.b9028c3401ee650c703e9634ed41d8d19558bc68_main
0046 epic-main
0047 ```
0048
0049 ::::::::::::::::::::::::::::::::::::::::::::: callout
0050
0051 Note: `ls -1` lists the files with 1 file per line, i.e. in 1 column.
0052
0053 :::::::::::::::::::::::::::::::::::::::::::::
0054
0055 The versions avaliable in eic-shell are updated when tagged releases for the geometry are made each month or an update to dependancies installed in eic-shell removes back compatibility with older versions. We aim to back support the last 6 months of releases in the container.
0056
0057 The `epic-main` directory contains the current 'nightly build' of the ePIC geometry, built from the [epic repositories main branch](https://github.com/eic/epic/) every day.
0058
0059 ```bash
0060 $ ls -1 /opt/detector/epic-main/
0061 bin
0062 lib
0063 setup.sh
0064 share
0065 $ ls -1 /opt/detector/epic-main/bin
0066 g4MaterialScan_to_csv
0067 thisepic.sh
0068 ```
0069
0070 You can load a geometry by 'sourcing' the `bin/thisepic.sh` file.
0071
0072 ```bash
0073 $ source /opt/detector/epic-main/bin/thisepic.sh
0074 ```
0075
0076 The comman should have the same effect:
0077
0078 - your shell environment will have the necessary variables loaded to work with the `epic-main` geometry.
0079
0080 You can verify the latter by investigating the values of several environment variables:
0081
0082 ```bash
0083 $ env | grep DETECTOR
0084 ```
0085
0086 - `DETECTOR` is the name of the detector geometry that is loaded (`epic`),
0087 - `DETECTOR_VERSION` is the version (i.e. GitHub branch or tag) that is loaded (`main`),
0088 - `DETECTOR_CONFIG` is the detector configuration to use (i.e. whether to include MRICH or PFRICH, SciGlass or imaging ECAL),
0089 - `DETECTOR_PATH` is the location that points to the geometry resources (`/opt/detector/epic-main/share/epic`).
0090
0091 ::::::::::::::::::::::::::::::::::::::::::::: callout
0092
0093 Note: When working on the geometry in your own git branch you will need to source the setup.sh present in the local install directory.
0094
0095 :::::::::::::::::::::::::::::::::::::::::::::
0096
0097 ::::::::::::::::::::::::::::::::::::::::::::: challenge
0098
0099 ## Exercise: loading a geometry
0100
0101 - Load the standard ePIC geometry and verify (with e.g. `echo $DETECTOR_PATH`) that the environment variables are set.
0102 - Load another geometry and verify that the environment variables are indeed different.
0103
0104 ::::::::::::::: solution
0105
0106 Sourcing `/opt/detector/epic-main/bin/thisepic.sh` sets `DETECTOR`, `DETECTOR_VERSION`,
0107 `DETECTOR_CONFIG`, and `DETECTOR_PATH`; `echo $DETECTOR_PATH` prints
0108 `/opt/detector/epic-main/share/epic`. Sourcing the `thisepic.sh` from a different version directory
0109 (e.g. `/opt/detector/epic-25.08.0/bin/thisepic.sh`) changes `DETECTOR_VERSION` and `DETECTOR_PATH`
0110 accordingly.
0111
0112 :::::::::::::::
0113
0114 :::::::::::::::::::::::::::::::::::::::::::::
0115
0116 ## What is stored at those locations?
0117
0118 We will now take a look in the directory pointed to with the environment variable `$DETECTOR_PATH`, the location of the geometry resources:
0119
0120 ```bash
0121 $ ls $DETECTOR_PATH
0122 calibrations epic_craterlake_5x100.xml epic_forward_calorimeters.xml
0123 compact epic_craterlake_5x41_He3.xml epic_forward_detectors_with_inserts.xml
0124 epic_backward_hcal_only_sampF.xml epic_craterlake_5x41.xml epic_forward_detectors.xml
0125 epic_backward_hcal_only.xml epic_craterlake_bic_6layers.xml epic_full.xml
0126 epic_bhcal.xml epic_craterlake_bic_layer1_only.xml epic_imaging_only.xml
0127 epic_calorimeters.xml epic_craterlake_material_map_25_07_0.xml epic_inner_detector.xml
0128 epic_craterlake_10x100_Au197.xml epic_craterlake_material_map.xml epic_ip6_extended.xml
0129 epic_craterlake_10x100.xml epic_craterlake_no_bhcal.xml epic_ip6.xml
0130 epic_craterlake_10x110_He3.xml epic_craterlake_no_zdc_lyso.xml epic_lfhcal_only.xml
0131 epic_craterlake_10x115_Cu63.xml epic_craterlake_tracking_only.xml epic_pfrich_only.xml
0132 epic_craterlake_10x115_Ru96.xml epic_craterlake_without_zdc_10x100_Au197.xml epic_pid_only.xml
0133 epic_craterlake_10x130_H2.xml epic_craterlake_without_zdc_5x41_Au197.xml epic_tof_endcap_only.xml
0134 epic_craterlake_10x130.xml epic_craterlake.xml epic_tof_only.xml
0135 epic_craterlake_10x166_He3.xml epic_dirc_only.xml epic_vertex_only.xml
0136 epic_craterlake_10x250.xml epic_drich_only.xml epic.xml
0137 epic_craterlake_10x275.xml epic_eeemcal_only.xml epic_zdc_lyso_sipm.xml
0138 epic_craterlake_18x110_Au.xml epic_femcal_averaged_homogeneous.xml epic_zdc_sipm_on_tile_only.xml
0139 epic_craterlake_18x110_He3.xml epic_femcal_scfi.xml fieldmaps
0140 epic_craterlake_18x275.xml epic_fhcal.xml gdml
0141 ```
0142
0143 You will see many xml files, all of which are entry points to the geometry in certain configurations. For example, `epic_drich_only.xml` includes the geometry that has only the dual RICH or dRICH. `epic_ip6.xml` includes the beampipe geometry and the auxillary far-forward and backward detectors but no components of the central detector. The default configuration, `epic.xml`, is typically the configuration you will want to use, this is the value that `DETECTOR_CONFIG` will be set to by default.
0144
0145 Let's take a look in *the default entry point file*, pointed at by the `DETECTOR_CONFIG` environment variable. This is the file `epic.xml`:
0146
0147 ```bash
0148 $ less $DETECTOR_PATH/$DETECTOR_CONFIG.xml
0149 ```
0150
0151 (Note: Use `q` to exit `less`, or use any editor you prefer.)
0152
0153 The xml file includes several blocks, but look in particular for the following lines:
0154
0155 - `<include ref="${DETECTOR_PATH}/compact/definitions.xml"/>`: This line includes the overall detector parametrization file (think of this as a detector parameter table similar to what the EIC Menagerie provides).
0156 - `<include ref="${DETECTOR_PATH}/compact/tracking/vertex_barrel.xml"/>`: This line includes one of the tracker subsystems; there are other include lines that load other tracking subsystems, or even other types of subsystems.
0157 - `<include ref="${DETECTOR_PATH}/compact/far_forward/default.xml"/>`: This line includes the far forward subsystems.
0158
0159 These included files (e.g. `far_forward/default.xml`) can include further nested inclusion of even more files (e.g. `far_forward/ZDC.xml`).
0160
0161 ::::::::::::::::::::::::::::::::::::::::::::: callout
0162
0163 Note: The xml files are parsed in order, so the `definitions.xml` file needs to be included before any file which needs to access the defined parameters.
0164
0165 :::::::::::::::::::::::::::::::::::::::::::::
0166
0167 Let's now take a look at *a particular detector subsystem end point file* (which does not include any more files), namely `tracking/vertex_barrel.xml`.
0168
0169 ```bash
0170 $ less $DETECTOR_PATH/compact/tracking/vertex_barrel.xml
0171 ```
0172
0173 You will notice that the detector is described by parameters in a `define` block, such as (abridged):
0174
0175 ```xml
0176 <define>
0177 <constant name="SiVertexSensor_thickness" value="40*um" />
0178
0179 <comment>
0180 1 RSU = 2x6 tiles with inactive areas == 2x2 sections
0181 1 section (module) = 3-tiles along z
0182 1 "stave" = 1 row of 12 RSU
0183 </comment>
0184
0185 <constant name="RSU_width" value="19.564*mm" />
0186 <constant name="RSU_length" value="21.666*mm" />
0187 <constant name="Periphery_width" value="0.398*mm"/>
0188 <constant name="bias_width" value="0.06*mm"/>
0189 <constant name="backbone_width" value="0.09*mm"/>
0190 <constant name="Section_width" value="RSU_width/2-bias_width-Periphery_width"
0191 />
0192 <constant name="Section_length" value="RSU_length/2-backbone_width"/>
0193 </define>
0194 ```
0195
0196 which can either use another parameter defined previously in the included files, or which can be defined in this file itself. A best practices is to define detailed parameters of each subsystem in the end point file, but to defer to the central definitions in the `definitions.xml` for quantities such as the overal size and location of the subsystem, or interfaces with other subsystems. Comments can also be left throughout the xml description to help document the values.
0197
0198 The parameters are then used in the `detector` block to define the detector itself (much abridged):
0199
0200 ```xml
0201 <detectors>
0202 <detector
0203 id="VertexBarrel_0_ID"
0204 name="VertexBarrel"
0205 type="epic_CylinderSVTBarrel"
0206 readout="VertexBarrelHits"
0207 insideTrackingVolume="true">
0208
0209 <module name="Module0_upper" rmin="VertexBarrelModL0_rmin" width="VertexBarrelStaveL0_width"
0210 length="VertexBarrelMod_length">
0211 <module_component name="RSU" type="upper"
0212 material="Silicon"
0213 sensitive="true"
0214 thickness="SiVertexSensor_thickness"
0215 width="Section_width"
0216 length="Section_length"
0217 vis="VertexLayerVis" />
0218 </module>
0219
0220 </detector>
0221 </detectors>
0222 ```
0223
0224 The parametrization of the entire detector, down to the subsystems, is defined in these xml files. But where are the volumes created? The key here is the `type` field, which points to the detector type *plugin* that interprets the parametrization (here the type is `epic_VertexBarrel`). A well-written detector plugin can support many different detector configurations and parametrizations without the need to ever touch a line of code.
0225
0226 ::::::::::::::::::::::::::::::::::::::::::::: challenge
0227
0228 ## Exercise: locating a subsystem
0229
0230 - Identify which subsystem or detector you are interested in.
0231 - Take a look in the `epic.xml` file and locate where this detector is included.
0232 - Locate the end point file that defines the parameters that describe this file.
0233 - Identify the detector plugin that is used for this detector.
0234
0235 ::::::::::::::: solution
0236
0237 For a chosen subsystem you should find an `<include ref="${DETECTOR_PATH}/compact/.../<subsystem>.xml"/>`
0238 line in `epic.xml`, the corresponding end point file under `compact/` defining its `<constant>`
0239 parameters and `<detector>` block, and the plugin named in that block's `type` attribute (for the
0240 vertex barrel this is `epic_VertexBarrel`).
0241
0242 :::::::::::::::
0243
0244 :::::::::::::::::::::::::::::::::::::::::::::
0245
0246 ::::::::::::::::::::::::::::::::::::::::::::: keypoints
0247
0248 - Compact XML files are used to store parameters which are used by compiled plugins.
0249
0250 :::::::::::::::::::::::::::::::::::::::::::::
