# Features

## 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"/>
</envelope>
<dimensions numsides="HCal_sym" rmin="HCal_rmin" z="HCal_dz*2"/>
<layer repeat="(int) HCal_layers" vis="HCalLayerVis">
<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="Air"         thickness="2.7*mm" vis="InvisibleNoDaughters"/>
</layer>
</detector>

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.

## 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.

## 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" )
#...

Example showing how to configure a DDG4 input file in Python.

#...
part = DDG4.GeneratorAction(kernel, "Geant4ParticleHandler/ParticleHandler")