# aidasoft/dd4hep architecture

> Architecture diagram of the GitHub repository aidasoft/dd4hep, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aidasoft/dd4hep
- Repository: https://github.com/aidasoft/dd4hep

## Overview

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`](https://github.com/aidasoft/dd4hep/tree/master/DDCore) (DDCore), [`examples`](https://github.com/aidasoft/dd4hep/tree/master/examples) (Examples), [`DDG4`](https://github.com/aidasoft/dd4hep/tree/master/DDG4) (DDG4), [`GaudiPluginService`](https://github.com/aidasoft/dd4hep/tree/master/GaudiPluginService) (Plugin Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_core["Core framework"]
  node_n_ddcore["DDCore<br/>framework core"]
  node_n_ddparsers["DDParsers<br/>expression parser"]
  node_n_pluginsvc["Plugin Service<br/>plugin runtime"]
end

subgraph group_grp_runtime["Runtime layers"]
  node_n_ddcond["DDCond<br/>conditions system"]
  node_n_ddalign["DDAlign<br/>alignment service"]
  node_n_ddg4["DDG4<br/>geant4 bridge"]
  node_n_diggi["DDDigi<br/>digitization pipeline"]
  node_n_ddrec["DDRec<br/>reco geometry"]
end

subgraph group_grp_content["Detector content"]
  node_n_dddet["DDDetectors<br/>reference detectors"]
  node_n_examples["Examples<br/>demo catalog"]
  node_n_ddtest["DDTest<br/>validation suite"]
end

subgraph group_grp_tools["Inspection tools"]
  node_n_ddeve["DDEve<br/>event display"]
  node_n_utils["Utility Apps<br/>cli tools"]
  node_n_ddcad["DDCAD<br/>cad bridge"]
end

node_n_ddparsers -->|"feeds objects"| node_n_ddcore
node_n_pluginsvc -->|"loads plugins"| node_n_ddcore
node_n_pluginsvc -->|"loads plugins"| node_n_ddcond
node_n_pluginsvc -->|"loads plugins"| node_n_ddg4
node_n_pluginsvc -->|"loads plugins"| node_n_diggi
node_n_ddcond -->|"backs alignment"| node_n_ddalign
node_n_ddcore -->|"consumes conditions"| node_n_ddcond
node_n_ddcore -->|"uses alignment"| node_n_ddalign
node_n_ddcore -->|"geometry source"| node_n_ddg4
node_n_ddg4 -->|"passes hits"| node_n_diggi
node_n_ddcore -->|"supplies geometry"| node_n_ddrec
node_n_ddcore -->|"renders model"| node_n_ddeve
node_n_ddcore -->|"inspected by"| node_n_utils
node_n_ddcore -->|"imports/exports"| node_n_ddcad
node_n_ddcore -->|"builds detectors"| node_n_dddet
node_n_ddcore -->|"exercised by"| node_n_examples
node_n_ddcore -->|"validated by"| node_n_ddtest
node_n_dddet -->|"simulation inputs"| node_n_ddg4
node_n_examples -->|"drives"| node_n_ddg4
node_n_examples -->|"demonstrates"| node_n_ddcond
node_n_examples -->|"demonstrates"| node_n_diggi
node_n_examples -->|"visualized by"| node_n_ddeve
node_n_examples -->|"imports assets"| node_n_ddcad

click node_n_ddcore "https://github.com/aidasoft/dd4hep/tree/master/DDCore"
click node_n_ddparsers "https://github.com/aidasoft/dd4hep/tree/master/DDParsers"
click node_n_pluginsvc "https://github.com/aidasoft/dd4hep/tree/master/GaudiPluginService"
click node_n_ddcond "https://github.com/aidasoft/dd4hep/tree/master/DDCond"
click node_n_ddalign "https://github.com/aidasoft/dd4hep/tree/master/DDAlign"
click node_n_ddg4 "https://github.com/aidasoft/dd4hep/tree/master/DDG4"
click node_n_diggi "https://github.com/aidasoft/dd4hep/tree/master/DDDigi"
click node_n_ddrec "https://github.com/aidasoft/dd4hep/tree/master/DDRec"
click node_n_ddeve "https://github.com/aidasoft/dd4hep/tree/master/DDEve"
click node_n_utils "https://github.com/aidasoft/dd4hep/tree/master/UtilityApps"
click node_n_ddcad "https://github.com/aidasoft/dd4hep/tree/master/DDCAD"
click node_n_dddet "https://github.com/aidasoft/dd4hep/tree/master/DDDetectors"
click node_n_examples "https://github.com/aidasoft/dd4hep/tree/master/examples"
click node_n_ddtest "https://github.com/aidasoft/dd4hep/tree/master/DDTest"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_ddcore,node_n_ddparsers,node_n_pluginsvc toneBlue
class node_n_ddcond,node_n_ddalign,node_n_ddg4,node_n_diggi,node_n_ddrec toneAmber
class node_n_dddet,node_n_examples,node_n_ddtest toneMint
class node_n_ddeve,node_n_utils,node_n_ddcad toneRose
```

## Components

### Core framework

Shared detector description, parsing, and plugin infrastructure.

- [DDCore](https://github.com/aidasoft/dd4hep/tree/master/DDCore): framework core · Detector object model, geometry, readout, segmentation, XML/JSON parsing, persistency, and plugin APIs. · `DDCore`
- [DDParsers](https://github.com/aidasoft/dd4hep/tree/master/DDParsers): expression parser · Grammar and evaluator layer for compact descriptions, parameters, and unit-aware expressions. · `DDParsers`
- [Plugin Service](https://github.com/aidasoft/dd4hep/tree/master/GaudiPluginService): plugin runtime · Shared plugin-loading and factory infrastructure used across DD4hep packages. · `GaudiPluginService`

### Runtime layers

Time-dependent conditions, simulation, digitization, and reconstruction consumers.

- [DDCond](https://github.com/aidasoft/dd4hep/tree/master/DDCond): conditions system · Conditions repository, IOV pools, loaders, selectors, dependency tracking, and persistency. · `DDCond`
- [DDAlign](https://github.com/aidasoft/dd4hep/tree/master/DDAlign): alignment service · Alignment data structures and writers layered on top of the conditions system. · `DDAlign`
- [DDG4](https://github.com/aidasoft/dd4hep/tree/master/DDG4): geant4 bridge · Geant4 integration for detector construction, actions, physics, event handling, and output conversion. · `DDG4`
- [DDDigi](https://github.com/aidasoft/dd4hep/tree/master/DDDigi): digitization pipeline · Kernel, action sequences, noise/response models, segmentation tools, and I/O for detector response modeling. · `DDDigi`
- [DDRec](https://github.com/aidasoft/dd4hep/tree/master/DDRec): reco geometry · Reconstruction-side surfaces, materials, material scans, and cell-ID to position conversion. · `DDRec`

### Detector content

Reference detector definitions, examples, and validation material.

- [DDDetectors](https://github.com/aidasoft/dd4hep/tree/master/DDDetectors): reference detectors · Reusable detector constructors, helpers, and compact XML for reference detector families. · `DDDetectors`
- [Examples](https://github.com/aidasoft/dd4hep/tree/master/examples): demo catalog · Large set of detector models, scripts, and sample applications exercising the framework. · `examples`
- [DDTest](https://github.com/aidasoft/dd4hep/tree/master/DDTest): validation suite · Regression tests and sample inputs covering geometry, parsers, segmentation, surfaces, and integration. · `DDTest`

### Inspection tools

Visualization, utility apps, and external format bridges.

- [DDEve](https://github.com/aidasoft/dd4hep/tree/master/DDEve): event display · ROOT EVE and web-based visualization for detector geometry and events. · `DDEve`
- [Utility Apps](https://github.com/aidasoft/dd4hep/tree/master/UtilityApps): cli tools · Command-line inspection and analysis tools for geometry, fields, materials, plugins, and displays. · `UtilityApps`
- [DDCAD](https://github.com/aidasoft/dd4hep/tree/master/DDCAD): cad bridge · ASSIMP-based import/export boundary for exchanging detector content with external CAD formats. · `DDCAD`

## Connections

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