How aidasoft/dd4hep works
DD4hep is a modular detector-description framework, not a single app. The repository is organized around a shared geometry/conditions core, then a set of domain-specific layers that consume that core for simulation, digitization, reconstruction, visualization, and detector-specific content.
1. Overall architecture
- The central idea is “single source of detector truth”: detector geometry, materials, readout, segmentation, alignments, and conditions are described once and then reused by downstream subsystems.
- Most code is C++ libraries with plugin-heavy extension points, plus Python steering/configuration and many XML compact descriptions.
2. Core foundation: DDCore
- DDCore is the main framework library. It provides the detector object model, geometry abstractions, shapes/volumes, segmentation, readout, conditions hooks, alignment data structures, and plugin interfaces.
- It also contains the XML and JSON parsing layers, ROOT persistency helpers, and Python bindings.
- This is the layer most other packages depend on.
3. Parsing and expression evaluation: DDParsers
- DDParsers supplies the grammar/evaluator infrastructure used by compact detector descriptions and configuration files.
- It supports typed parameter parsing, unit-aware expressions, and object conversions that feed geometry/configuration into the core model.
- Architecturally, this is the “front door” from human-authored XML/compact files into runtime objects.
4. Plugin runtime and factory boundary
- The repo uses a plugin architecture throughout. GaudiPluginService provides shared plugin-loading infrastructure, while DDCore, DDCond, DDG4, DDDigi, and others each expose their own plugin registries.
- Many src/plugins directories implement runtime-discovered geometry builders, parsers, scanners, writers, or action modules.
- This boundary is important: static framework code stays generic, while detector-specific behavior is injected through plugins.
5. Detector conditions and time dependence: DDCond
- DDCond manages conditions data, repositories, pools, IOV handling, dependency tracking, selectors, and persistency.
- It includes loaders/writers for text, XML, ROOT, and tree-based snapshots, so conditions can be sourced from files or structured repositories.
- The data flow is from external conditions payloads into a managed cache/pool, then into consumers in geometry, alignment, and simulation.
6. Alignment as a specialized conditions domain: DDAlign
- DDAlign builds on the conditions infrastructure to manage global detector alignment objects, caches, stacks, writers, and parsers.
- It represents alignment constants and transforms as a first-class runtime service rather than hard-coded geometry.
- In diagrams, this is best shown as a conditions-backed service feeding the detector model and reconstruction.
7. **Concrete detector content: DDDetectors and examples/***
- DDDetectors contains reusable detector constructors, helper headers, and compact XML for a reference detector family (notably SiD).
- The examples/ tree is large and acts as a catalog of detector models, configuration snippets, and demo applications for many detector concepts.
- These packages are where generic framework primitives become real geometries, readouts, and detector assemblies.
8. Simulation bridge: DDG4
- DDG4 is the Geant4 integration layer. It converts DD4hep geometry into Geant4 detector construction, physics, actions, stepping, hit handling, and run management.
- It includes readers and outputs for HEPMC, LCIO, ROOT, and EDM4hep, plus Python steering under DDG4/python/DDSim.
- Data flow is: DD4hep geometry/conditions → Geant4 setup → particle generation/transport → hits/tracks/output formats.
9. Digitization pipeline: DDDigi
- DDDigi models detector response after simulation. It defines a kernel, action sequences, processors, noise models, segmentation tools, and input/output adapters.
- It supports container-level processing, signal shaping, smearing, suppression, and parallel worker execution.
- The main flow is simulated deposits/hits → digitization actions/noise/segmentation → digitized output, often with EDM4hep or ROOT I/O.
10. Reconstruction support: DDRec
- DDRec provides reconstruction-side geometry services such as surfaces, materials, material scans, detector data, and cell-ID to position conversion.
- It is the bridge from detector description to track fitting, surface-based extrapolation, and geometry-aware reconstruction.
- This layer consumes the geometry/readout model produced by DDCore and enriches it with reconstruction-specific abstractions.
11. Visualization and event display: DDEve and utility apps
- DDEve integrates with ROOT EVE and also includes a web-display path, providing detector and event visualization.
- UtilityApps contains command-line tools for geometry dumps, material scans, plugin execution, field inspection, and display helpers.
- These are consumers of the same detector model, but they sit at the presentation/inspection boundary rather than the simulation boundary.
12. CAD import/export: DDCAD
- DDCAD handles exchange with external CAD formats through ASSIMP, including readers, writers, and helper utilities.
- Its role is to bring mechanical/CAD assets into the DD4hep detector-description ecosystem or export DD4hep-compatible representations.
- This is a separate ingestion/output boundary from the compact XML and Geant4 flows.
13. Test and validation surface
- DDTest, many examples/*, and UtilityApps provide regression tests, geometry checks, shape tests, parser tests, and runtime demonstrations.
- CI and build scripts in .github, cmake/, and etc/ support cross-platform builds, test execution, linting, and documentation generation.
- These are important because the framework’s correctness depends heavily on geometry consistency and plugin loading behavior.
14. Primary architectural flow to capture in a diagram
- Authoring inputs: compact XML, conditions files, CAD assets, and Python steering.
- Core processing: parse/evaluate into DDCore objects; attach conditions/alignment through DDCond/DDAlign.
- Downstream consumers: DDG4 for simulation, DDDigi for response modeling, DDRec for reconstruction geometry, and DDEve/utilities for inspection.
- Extension mechanism: plugins and factory registries are the main mechanism that connect detector-specific content to the generic framework.
Main entry points: DDCore DDCore · examples Examples · DDG4 DDG4 · GaudiPluginService Plugin Service
Components 14
Core framework
Shared detector description, parsing, and plugin infrastructure.
- DDCore · Detector object model, geometry, readout, segmentation, XML/JSON parsing, persistency, and plugin APIs.
DDCore - DDParsers · Grammar and evaluator layer for compact descriptions, parameters, and unit-aware expressions.
DDParsers - Plugin Service · Shared plugin-loading and factory infrastructure used across DD4hep packages.
GaudiPluginService
Runtime layers
Time-dependent conditions, simulation, digitization, and reconstruction consumers.
- DDCond · Conditions repository, IOV pools, loaders, selectors, dependency tracking, and persistency.
DDCond - DDAlign · Alignment data structures and writers layered on top of the conditions system.
DDAlign - DDG4 · Geant4 integration for detector construction, actions, physics, event handling, and output conversion.
DDG4 - DDDigi · Kernel, action sequences, noise/response models, segmentation tools, and I/O for detector response modeling.
DDDigi - DDRec · Reconstruction-side surfaces, materials, material scans, and cell-ID to position conversion.
DDRec
Detector content
Reference detector definitions, examples, and validation material.
- DDDetectors · Reusable detector constructors, helpers, and compact XML for reference detector families.
DDDetectors - Examples · Large set of detector models, scripts, and sample applications exercising the framework.
examples - DDTest · Regression tests and sample inputs covering geometry, parsers, segmentation, surfaces, and integration.
DDTest
Inspection tools
Visualization, utility apps, and external format bridges.
- DDEve · ROOT EVE and web-based visualization for detector geometry and events.
DDEve - Utility Apps · Command-line inspection and analysis tools for geometry, fields, materials, plugins, and displays.
UtilityApps - DDCAD · ASSIMP-based import/export boundary for exchanging detector content with external CAD formats.
DDCAD
Connections 23
- DDParsers → DDCore: feeds objects · Parsed expressions and parameters are turned into runtime detector objects.
- Plugin Service → DDCore: loads plugins · Shared plugin service underpins DDCore factory and extension loading.
- Plugin Service → DDCond: loads plugins · Conditions loaders, writers, and repository adapters are plugin-based.
- Plugin Service → DDG4: loads plugins · Geant4 actions, physics constructors, and I/O adapters are discovered through plugins.
- Plugin Service → DDDigi: loads plugins · Digitization actions and processors are exposed through plugin registries.
- DDCond → DDAlign: backs alignment · Alignment state is managed as a specialized conditions domain.
- DDCore → DDCond: consumes conditions · Detector model consumers access conditions data through the core framework.
- DDCore → DDAlign: uses alignment · Alignment transforms extend the core detector description.
- DDCore → DDG4: geometry source · DD4hep geometry is translated into Geant4 detector construction and sensitive detectors.
- DDG4 → DDDigi: passes hits · Simulation output becomes input for digitization workflows.
- DDCore → DDRec: supplies geometry · Reconstruction surfaces and material descriptions derive from the core model.
- DDCore → DDEve: renders model · Visualization tools inspect the same detector description used elsewhere.
- DDCore → Utility Apps: inspected by · Utility applications query and dump geometry, materials, and fields from the core model.
- DDCore → DDCAD: imports/exports · CAD exchange maps external shapes into the detector-description ecosystem.
- DDCore → DDDetectors: builds detectors · Reference detector constructors instantiate concrete detector content using core primitives.
- DDCore → Examples: exercised by · Examples demonstrate framework usage patterns and detector-specific assemblies.
- DDCore → DDTest: validated by · Regression tests exercise core parsing, geometry, surfaces, and segmentation behavior.
- DDDetectors → DDG4: simulation inputs · Reference detector models feed Geant4-based simulation examples.
- Examples → DDG4: drives · Simulation examples steer Geant4 setup and event processing.
- Examples → DDCond: demonstrates · Conditions examples show loading, updates, and persistency workflows.
- Examples → DDDigi: demonstrates · Digitization examples configure response and I/O pipelines.
- Examples → DDEve: visualized by · Example geometries are used in ROOT EVE and web display demos.
- Examples → DDCAD: imports assets · CAD examples demonstrate format conversion and detector import paths.