The Compact Description

The compact detector description is based on concepts of the linear collider detector simulation. The compact description is provided in XML format, has a minimalistic form and was designed with the aim for conceptual design studies. Since the parsers of DD4hep do not validate the schema of the XML it facilitates simple addition of new elements and attributes into the detector description. The information in the XML is per-se not enough for a comprehensive detector description. To achieve this, specialized code fragments are needed, the so called Detector Constructors, which interpret the XML.

<detector id="15" name="HCal" type="GenericCalBarrel_o1_v01" readout="HCalCollection">
  <envelope vis="HCALVis">
    <shape type="PolyhedraRegular" numsides="HCal_sym" rmin="HCal_rmin" rmax="HCal_rmax" dz="HCal_dz" material="Air"/>
    <rotation x="0*deg" y="0*deg" z="90*deg-180*deg/HCal_symmetry"/>
  <dimensions numsides="HCal_sym" rmin="HCal_rmin" z="HCal_dz*2"/>
  <layer repeat="(int) HCal_layers" vis="HCalLayerVis">
    <slice material="Steel235"    thickness="0.5*mm" vis="HCalAbsorberVis" radiator="yes"/>
    <slice material="Steel235"    thickness="19*mm"  vis="HCalAbsorberVis" radiator="yes"/>
    <slice material="Polystyrene" thickness="3*mm"   sensitive="yes"  limits="cal_limits"/>
    <slice material="Copper"      thickness="0.1*mm" vis="HCalCopperVis"/>
    <slice material="PCB"         thickness="0.7*mm" vis="HCalPCBVis"/>
    <slice material="Steel235"    thickness="0.5*mm" vis="HCalAbsorberVis" radiator="yes"/>
    <slice material="Air"         thickness="2.7*mm" vis="InvisibleNoDaughters"/>
An example compact description for a calorimeter.

Detector Constructors

Detector Constructors are short code pieces that contextualize the XML input and create a detector instance. Each code segment constructs a single sub-detector at a time, but the toolkit enables to combine several detector instances together and thus constructs a complex and large apparatus. Detector construction can be written either via C++ or Python. Whereas the C++ variant enables better detection of errors at compilation time, the Python interfaces are easier to use, but errors are usually only detected at execution time. With the combination of compact description and the detector constructors one is able to simulate and visualize the detector.

static Ref_t create_detector(LCDD& lcdd, xml_h e, SensitiveDetector sens) {

  xml_det_t x_det = e;
  Layering layering(x_det);
  xml_comp_t staves = x_det.staves();
  xml_dim_t dim = x_det.dimensions();
  DetElement sdet(det_name, x_det.id());
  Volume motherVol = lcdd.pickMotherVolume(sdet);

  PolyhedraRegular polyhedra(numSides, rmin, rmax, detZ);
  Volume envelopeVol(det_name, polyhedra, air);

  for (xml_coll_t c(x_det, _U(layer)); c; ++c) {
    xml_comp_t x_layer = c;
    int n_repeat = x_layer.repeat();
    const Layer* lay = layering.layer(layer_num - 1);
    for (int j = 0; j < n_repeat; j++) {
      string layer_name = _toString(layer_num, "layer%d");
      double layer_thickness = lay->thickness();
      DetElement layer(stave, layer_name, layer_num);
Code snippet to create a calorimeter.

Visualization based on the compact description and a detector constructor.

Visualization based on the compact description and a detector constructor.

Generic Detector Description Model

The aim of the GDDM is to build an in-memory model of the detector that can provide geometrical as well as functional facets. It is based on the TGeo geometry package from ROOT with certain extensions. The TGeo geometry classes are used directly without isolation interfaces, with the exception of detector constructors, where users can write easy, compact and readable code for custom detector constructors. The in-memory object is structured as a tree of DetectorElement objects. These elements provide an easy entry point to any given detector part of the apparatus and represent a complete sub-detector (e.g. tracker or calorimeter), a part of a sub-detector (e.g. tracker-disk or tracker-barrel), a module or any other arbitrary sub-detector part.

The tree structure of DetectorElement objects that constitute the GDDM.

The main purpose is to provide an easy access to a desired sub-detector information. If a tracking program wants access to the tracker DetectorElement, DD4hep will allow the program access to all the geometry properties, alignment and calibration constants and other slow varying conditions such as temperatures. The DetectorElement acts as a data container. DD4hep provides a singleton object called Detector, through which access to the whole geometry is possible, and which provides at the same time ownership, bookkeeping and management properties to the instances of the detector model.

As shown in the figure below, an application might require special functionality. This can be achieved with specialized classes that extend the DetectorElement. Such extensions are usually needed in addressing issues connected to reconstruction algorithms, such as pattern recognition, tracking, vertexing and particle identification. One example could be surfaces that aid in track fitting. A generic detector description toolkit cannot address all cases, there are far too many of them, but it can provide a flexible extension mechanism via code fragments to develop the necessary functionality which is needed for a given case. Depending on the case, the extensions can store additional specialized data, expose additional behavior or both. The user can easily add additional behavior by overloading the DetectorElement class and extending its internal data. Since the internal data is public and addressed by reference, an arbitrary number of extensions can be created with minimal overhead. In addition to this, more data can be incorporated at any time by the user into this scheme by using a simple aggregation mechanism. The only constraint is that these data extensions have to be of different types. It is thus possible to optimize the attachment depending on the particular use case. DD4hep utilities this functionality in the reconstructions extension called DDRec.

Simulation support - DDG4

Since the DD4hep geometry is based on ROOT/TGeo, it has to be translated to the Geant4 specific geometry representation to enable simulation. Using the Geant4 user interface G4VUserDetectorConstruction, a generic mechanism has been implemented that converts on the fly all geometry entities like shapes, materials, volumes and volume placements to a Geant4 geometry. The mechanism is implemented to traverse the geometry tree from the top level element and recursively collect all entities. A special treatment was needed for certain objects, where the implementation paradigm differ between the Geant4 and the ROOT geometry, e.g. shape assemblies.

To simplify the usage and implementation of plugin functionality, all components use a common base class. The base class is designed to provide simple access to all objects needed to perform simulation tasks. It is implemented to handle all common functionalities, e.g. external configuration of component properties, data access via Geant4 or the detector description toolkit. Since all components inherit from the Geant4Action, a sequence of actions can be created e.g. to merge and simulate two different data types. The typical action sequence is:

  • Initialization step: properties related to the event and its context are prepared.
  • Acces to input data type 1: reading or generation of events of type 1 (e.g. simulated electron positron events). The primary vertices from the input data and resulting tracks are then boosted and the primary vertices are smeared in subsequent modules according to the assumed beam profiles and beam conditions.
  • Acces to input data type 2: reading or generation of events of type 2 (e.g. beam induced background events). The primary vertices from the input data are treated in the same manner as in the previous step.
  • Merging: merge to one single record combining the primary vertices and outgoing primary tracks of both types of data (with possibility to add an arbitrary number of input data).
  • Geant4: the entire record containing all primary vertices and all primary tracks is given to Geant4, and the simulation can start.

Monte Carlo Truth Handling

A basic functionality that DDG4 offers, is the assignment of generated energy deposits to the tracks which created the deposit. There are several ways to address this issue, e.g:

  • Complete history record: the entire history is stored containing all energy deposits and the full record of created tracks. The drawback of this is that the record becomes quite big due to a large amount of secondary particles and the information associated to them. Such a record is usually only used for detailed studies and not for mass production.
  • Reduced history record: Only relevant energy deposits and tracks are kept. Low energetic tracks are reassigned to the parent tracks, whereas the energy deposits in calorimeters are handled differently.

DDG4 can handle the propagation of Monte Carlo truth information between hits and tracks for both cases. It utilizes a truth handler which uses an internal track object model, that can be tuned by the user at the output stage to the desired user track model. This gives the user a high degree of flexibility to construct an arbitrary output record based on the complete simulation information. This reduces the user effort needed to evaluate performance and efficiency of detector models.

Components and handling

DD4hep/DDG4 provides a ready-to-use pallet of components, which include standard input and output format support such as LCIO, StdHEP or HepMC modules to manipulate primary interactions, e.g. smearing or boosting, and also generic components collecting the detector response of tracking detectors or calorimeters. All these features enable users interested in fast detector prototyping to perform all necessary simulation activities of detector designs. DDG4 comes with a default palette of modules that are generic enough to be applicable to a wide variety of designs. The users can also provide specific detailed modules via the plugin mechanism.

Since the Geant4 physics setup is contained in a set of factories, the subsequent instantiations to particle constructors, physics processes, physics constructors or predefined physics lists are implemented in DDG4 by means of factory bindings. The configuration of a DDG4 application is possible via the following ways: data in a XML file, a C++ or a Python script. Due to the fact that C++ is the native language of the framework, one can configure the simulation via the same language, however a change of configuration requires a recompilation of the software which might be cumbersome. The most flexible way to configure DDG4 is via Python. The ROOT interface PyROOT is the most flexible and still robust way to bootstrap a DDG4 simulation application. The Python interfaces are provided automatically at the time of the generation of ROOT dictionaries. The dictionary mechanism exports the same classes to Python that reside in C++, which leads to a fairly similar configuration. Furthermore this approach does not need any recompilation. An example showing how easy it is to configure the input file in Python can be seen in below.

gen = DDG4.GeneratorAction( kernel , "LCIOInputAction/LCIO1" )
gen.Input = "LCIOFileReader|" + inputFile
Example showing how to configure a DDG4 input file in Python.

part = DDG4.GeneratorAction(kernel, "Geant4ParticleHandler/ParticleHandler")
part.SaveProcesses = ['Decay']
part.MinimalKineticEnergy = 1*MeV
part.KeepAllParticles = False
user = DDG4.GeneratorAction(kernel,"Geant4TCUserParticleHandler/UserParticleHandler")
user.TrackingVolume_Zmax = DDG4.tracker_region_zmax
user.TrackingVolume_Rmax = DDG4.tracker_region_rmax
Example for configuring actions, filters, sequences and cuts in Python.