Overview

Teaching: 15 min
Exercises: 10 min

Questions

• How do we define geometry using DD4hep?

Objectives

• Know where standard geometries as stored in eic-shell.

• Understand the structure of a geometry description file.

Introduction

The ePIC geometry is described using the DD4hep toolkit.

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 while providing automatic conversions to other geometrical representaions, such as exporting CAD models, surfaces for acts reconstruction, material maps but most importany, Geant4 for carrying out simulations.

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 (Event Data Model for High Energy Physics) built on podio (plain-old-data I/O).

Lesson

We start the discussion of the geometry definition with an overview of the locations of geometry files, and what is included in these files.

Location of standard geometries in eic-shell

Several standard geometry versions are included in eic-shell under the /opt/detector/ location. This includes (currently) at least the following:

$ ls -1 /opt/detector/
epic-25.08.0
epic-25.09.0
epic-25.10.0
epic-25.10.1
epic-25.10.2
epic-25.10.3
epic-25.11.0
epic-git.b9028c3401ee650c703e9634ed41d8d19558bc68_main
epic-main

Note: ls -1 lists the files with 1 file per line, i.e. in 1 column.

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.

The epic-main directory contains the current ‘nightly build’ of the ePIC geometry, built from the epic repositories main branch every day.

$ ls -1 /opt/detector/epic-main/
bin
lib
setup.sh
share
$ ls -1 /opt/detector/epic-main/bin
g4MaterialScan_to_csv
thisepic.sh

You can load a geometry by ‘sourcing’ the bin/thisepic.sh file.

$ source /opt/detector/epic-main/bin/thisepic.sh

The comman should have the same effect:

• your shell environment will have the necessary variables loaded to work with the epic-main geometry.

You can verify the latter by investigating the values of several environment variables:

$ env | grep DETECTOR

• DETECTOR is the name of the detector geometry that is loaded (epic),
• DETECTOR_VERSION is the version (i.e. GitHub branch or tag) that is loaded (main),
• DETECTOR_CONFIG is the detector configuration to use (i.e. whether to include MRICH or PFRICH, SciGlass or imaging ECAL),
• DETECTOR_PATH is the location that points to the geometry resources (/opt/detector/epic-main/share/epic).

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.

Exercise:

• Load the standard ePIC geometry and verify (with e.g. echo $DETECTOR_PATH) that the environment variables are set.
• Load another geometry and verify that the environment variables are indeed different.

What is stored at those locations?

We will now take a look in the directory pointed to with the environment variable $DETECTOR_PATH, the location of the geometry resources:

$ ls $DETECTOR_PATH
calibrations                       epic_craterlake_5x100.xml                     epic_forward_calorimeters.xml
compact                            epic_craterlake_5x41_He3.xml                  epic_forward_detectors_with_inserts.xml
epic_backward_hcal_only_sampF.xml  epic_craterlake_5x41.xml                      epic_forward_detectors.xml
epic_backward_hcal_only.xml        epic_craterlake_bic_6layers.xml               epic_full.xml
epic_bhcal.xml                     epic_craterlake_bic_layer1_only.xml           epic_imaging_only.xml
epic_calorimeters.xml              epic_craterlake_material_map_25_07_0.xml      epic_inner_detector.xml
epic_craterlake_10x100_Au197.xml   epic_craterlake_material_map.xml              epic_ip6_extended.xml
epic_craterlake_10x100.xml         epic_craterlake_no_bhcal.xml                  epic_ip6.xml
epic_craterlake_10x110_He3.xml     epic_craterlake_no_zdc_lyso.xml               epic_lfhcal_only.xml
epic_craterlake_10x115_Cu63.xml    epic_craterlake_tracking_only.xml             epic_pfrich_only.xml
epic_craterlake_10x115_Ru96.xml    epic_craterlake_without_zdc_10x100_Au197.xml  epic_pid_only.xml
epic_craterlake_10x130_H2.xml      epic_craterlake_without_zdc_5x41_Au197.xml    epic_tof_endcap_only.xml
epic_craterlake_10x130.xml         epic_craterlake.xml                           epic_tof_only.xml
epic_craterlake_10x166_He3.xml     epic_dirc_only.xml                            epic_vertex_only.xml
epic_craterlake_10x250.xml         epic_drich_only.xml                           epic.xml
epic_craterlake_10x275.xml         epic_eeemcal_only.xml                         epic_zdc_lyso_sipm.xml
epic_craterlake_18x110_Au.xml      epic_femcal_averaged_homogeneous.xml          epic_zdc_sipm_on_tile_only.xml
epic_craterlake_18x110_He3.xml     epic_femcal_scfi.xml                          fieldmaps
epic_craterlake_18x275.xml         epic_fhcal.xml                                gdml

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.

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:

$ less $DETECTOR_PATH/$DETECTOR_CONFIG.xml

(Note: Use q to exit less, or use any editor you prefer.)

The xml file includes several blocks, but look in particular for the following lines:

• <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).
• <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.
• <include ref="${DETECTOR_PATH}/compact/far_forward/default.xml"/>: This line includes the far forward subsystems.

These included files (e.g. far_forward/default.xml) can include further nested inclusion of even more files (e.g. far_forward/ZDC.xml).

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.

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.

$ less $DETECTOR_PATH/compact/tracking/vertex_barrel.xml

You will notice that the detector is described by parameters in a define block, such as (abridged):

  <define>
    <constant name="SiVertexSensor_thickness" value="40*um" />

    <comment>
      1 RSU              = 2x6 tiles with inactive areas == 2x2 sections
      1 section (module) = 3-tiles along z
      1 "stave"          = 1 row of 12 RSU
    </comment>

    <constant name="RSU_width"   value="19.564*mm" />
    <constant name="RSU_length"  value="21.666*mm" />
    <constant name="Periphery_width" value="0.398*mm"/>
    <constant name="bias_width" value="0.06*mm"/>
    <constant name="backbone_width" value="0.09*mm"/>
    <constant name="Section_width"  value="RSU_width/2-bias_width-Periphery_width"
/>
    <constant name="Section_length" value="RSU_length/2-backbone_width"/>
  </define>

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.

The parameters are then used in the detector block to define the detector itself (much abridged):

  <detectors>
    <detector
      id="VertexBarrel_0_ID"
      name="VertexBarrel"
      type="epic_CylinderSVTBarrel"
      readout="VertexBarrelHits"
      insideTrackingVolume="true">

      <module name="Module0_upper" rmin="VertexBarrelModL0_rmin"  width="VertexBar
relStaveL0_width"
      length="VertexBarrelMod_length">
        <module_component name="RSU" type="upper"
          material="Silicon"
          sensitive="true"
          thickness="SiVertexSensor_thickness"
          width="Section_width"
          length="Section_length"
          vis="VertexLayerVis" />
      </module>

    </detector>
  </detectors>

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.

Exercise:

• Identify which subsystem or detector you are interested in.
• Take a look in the epic.xml file and locate where this detector is included.
• Locate the end point file that defines the parameters that describe this file.
• Identify the detector plugin that is used for this detector.

Key Points

• Compact XML files are used to store parameters which are used by compiled plugins.