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 questions:
0006 - "How do we define geometry using DD4hep?"
0007 objectives:
0008 - "Know where standard geometries as stored in `eic-shell`."
0009 - "Understand the structure of a geometry description file."
0010 keypoints:
0011 - "Compact XML files are used to store parameters which are used by compiled plugins."
0012 ---
0013
0014 ## Introduction
0015
0016 The [ePIC geometry](https://github.com/eic/epic) is described using the [DD4hep toolkit](https://dd4hep.web.cern.ch/dd4hep/).
0017
0018 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.
0019
0020 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).
0021
0022 # Lesson
0023
0024 We start the discussion of the geometry definition with an overview of the locations of geometry files, and what is included in these files.
0025
0026 ## Location of standard geometries in `eic-shell`
0027
0028 Several standard geometry versions are included in `eic-shell` under the `/opt/detector/` location. This includes (currently) at least the following:
0029 ```console
0030 $ ls -1 /opt/detector/
0031 epic-25.08.0
0032 epic-25.09.0
0033 epic-25.10.0
0034 epic-25.10.1
0035 epic-25.10.2
0036 epic-25.10.3
0037 epic-25.11.0
0038 epic-git.b9028c3401ee650c703e9634ed41d8d19558bc68_main
0039 epic-main
0040 ```
0041
0042 > Note: `ls -1` lists the files with 1 file per line, i.e. in 1 column.
0043 {: .callout}
0044
0045 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.
0046
0047 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.
0048 ```console
0049 $ ls -1 /opt/detector/epic-main/
0050 bin
0051 lib
0052 setup.sh
0053 share
0054 $ ls -1 /opt/detector/epic-main/bin
0055 g4MaterialScan_to_csv
0056 thisepic.sh
0057 ```
0058
0059 You can load a geometry by 'sourcing' the `bin/thisepic.sh` file.
0060 ```console
0061 $ source /opt/detector/epic-main/bin/thisepic.sh
0062 ```
0063 The comman should have the same effect:
0064 - your shell environment will have the necessary variables loaded to work with the `epic-main` geometry.
0065
0066 You can verify the latter by investigating the values of several environment variables:
0067 ```console
0068 $ env | grep DETECTOR
0069 ```
0070 - `DETECTOR` is the name of the detector geometry that is loaded (`epic`),
0071 - `DETECTOR_VERSION` is the version (i.e. GitHub branch or tag) that is loaded (`main`),
0072 - `DETECTOR_CONFIG` is the detector configuration to use (i.e. whether to include MRICH or PFRICH, SciGlass or imaging ECAL),
0073 - `DETECTOR_PATH` is the location that points to the geometry resources (`/opt/detector/epic-main/share/epic`).
0074
0075 > 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.
0076 {: .callout}
0077
0078 > Exercise:
0079 > - Load the standard ePIC geometry and verify (with e.g. `echo $DETECTOR_PATH`) that the environment variables are set.
0080 > - Load another geometry and verify that the environment variables are indeed different.
0081 {: .challenge}
0082
0083 ## What is stored at those locations?
0084
0085 We will now take a look in the directory pointed to with the environment variable `$DETECTOR_PATH`, the location of the geometry resources:
0086 ```console
0087 $ ls $DETECTOR_PATH
0088 calibrations epic_craterlake_5x100.xml epic_forward_calorimeters.xml
0089 compact epic_craterlake_5x41_He3.xml epic_forward_detectors_with_inserts.xml
0090 epic_backward_hcal_only_sampF.xml epic_craterlake_5x41.xml epic_forward_detectors.xml
0091 epic_backward_hcal_only.xml epic_craterlake_bic_6layers.xml epic_full.xml
0092 epic_bhcal.xml epic_craterlake_bic_layer1_only.xml epic_imaging_only.xml
0093 epic_calorimeters.xml epic_craterlake_material_map_25_07_0.xml epic_inner_detector.xml
0094 epic_craterlake_10x100_Au197.xml epic_craterlake_material_map.xml epic_ip6_extended.xml
0095 epic_craterlake_10x100.xml epic_craterlake_no_bhcal.xml epic_ip6.xml
0096 epic_craterlake_10x110_He3.xml epic_craterlake_no_zdc_lyso.xml epic_lfhcal_only.xml
0097 epic_craterlake_10x115_Cu63.xml epic_craterlake_tracking_only.xml epic_pfrich_only.xml
0098 epic_craterlake_10x115_Ru96.xml epic_craterlake_without_zdc_10x100_Au197.xml epic_pid_only.xml
0099 epic_craterlake_10x130_H2.xml epic_craterlake_without_zdc_5x41_Au197.xml epic_tof_endcap_only.xml
0100 epic_craterlake_10x130.xml epic_craterlake.xml epic_tof_only.xml
0101 epic_craterlake_10x166_He3.xml epic_dirc_only.xml epic_vertex_only.xml
0102 epic_craterlake_10x250.xml epic_drich_only.xml epic.xml
0103 epic_craterlake_10x275.xml epic_eeemcal_only.xml epic_zdc_lyso_sipm.xml
0104 epic_craterlake_18x110_Au.xml epic_femcal_averaged_homogeneous.xml epic_zdc_sipm_on_tile_only.xml
0105 epic_craterlake_18x110_He3.xml epic_femcal_scfi.xml fieldmaps
0106 epic_craterlake_18x275.xml epic_fhcal.xml gdml
0107 ```
0108 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.
0109
0110
0111 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`:
0112 ```console
0113 $ less $DETECTOR_PATH/$DETECTOR_CONFIG.xml
0114 ```
0115 (Note: Use `q` to exit `less`, or use any editor you prefer.)
0116
0117 The xml file includes several blocks, but look in particular for the following lines:
0118 - `<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).
0119 - `<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.
0120 - `<include ref="${DETECTOR_PATH}/compact/far_forward/default.xml"/>`: This line includes the far forward subsystems.
0121
0122 These included files (e.g. `far_forward/default.xml`) can include further nested inclusion of even more files (e.g. `far_forward/ZDC.xml`).
0123
0124 > 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.
0125 {: .callout}
0126
0127 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`.
0128 ```console
0129 $ less $DETECTOR_PATH/compact/tracking/vertex_barrel.xml
0130 ```
0131 You will notice that the detector is described by parameters in a `define` block, such as (abridged):
0132 ```xml
0133 <define>
0134 <constant name="SiVertexSensor_thickness" value="40*um" />
0135
0136 <comment>
0137 1 RSU = 2x6 tiles with inactive areas == 2x2 sections
0138 1 section (module) = 3-tiles along z
0139 1 "stave" = 1 row of 12 RSU
0140 </comment>
0141
0142 <constant name="RSU_width" value="19.564*mm" />
0143 <constant name="RSU_length" value="21.666*mm" />
0144 <constant name="Periphery_width" value="0.398*mm"/>
0145 <constant name="bias_width" value="0.06*mm"/>
0146 <constant name="backbone_width" value="0.09*mm"/>
0147 <constant name="Section_width" value="RSU_width/2-bias_width-Periphery_width"
0148 />
0149 <constant name="Section_length" value="RSU_length/2-backbone_width"/>
0150 </define>
0151 ```
0152 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.
0153
0154 The parameters are then used in the `detector` block to define the detector itself (much abridged):
0155 ```xml
0156 <detectors>
0157 <detector
0158 id="VertexBarrel_0_ID"
0159 name="VertexBarrel"
0160 type="epic_CylinderSVTBarrel"
0161 readout="VertexBarrelHits"
0162 insideTrackingVolume="true">
0163
0164 <module name="Module0_upper" rmin="VertexBarrelModL0_rmin" width="VertexBar
0165 relStaveL0_width"
0166 length="VertexBarrelMod_length">
0167 <module_component name="RSU" type="upper"
0168 material="Silicon"
0169 sensitive="true"
0170 thickness="SiVertexSensor_thickness"
0171 width="Section_width"
0172 length="Section_length"
0173 vis="VertexLayerVis" />
0174 </module>
0175
0176 </detector>
0177 </detectors>
0178 ```
0179
0180 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.
0181
0182 > Exercise:
0183 > - Identify which subsystem or detector you are interested in.
0184 > - Take a look in the `epic.xml` file and locate where this detector is included.
0185 > - Locate the end point file that defines the parameters that describe this file.
0186 > - Identify the detector plugin that is used for this detector.
0187 {: .challenge}
