DD4hep The AIDA detector description toolkit for high energy physics experiments

DD4hep Project Information

The DD4hep Project Web

The project's welcome page can be found under the folling URL: http://aidasoft.web.cern.ch/DD4hep

Please note: To access the CERN intranet, to create new bugs in the DD4hep bug tracker etc, you require a CERN account, but you can create an external account very easily following these instructions.

The DD4hep Developers Mailing List

Mailing list to contact developers is: dd4hep-developers@cern.ch.

The mailing list archives can be consulted using the following URL.

The DD4hep Issue Tracker

Bug tracking and issue solving as well as feature requests may be addressed to the developers using the following web-portal.

Please note: Please stay calm if you do not receive a response within the next 25 nano-seconds. Most of the contributors also have other assignments!

License

DD4hep is made available under the GPL license. For full details see the file LICENSE in the DD4hep distribution or at the following URL.

Building and Installing DD4hep

The DD4hep software is distributed for each release in the form of

* Precompiled tar-balls, where users only untar the downloaded
  software.
* As source distribution, which may be downloaded from the 
  central repository at Desy.

Release Versioning

Currently DD4hep is released several times a year depending on the importance of new functionality. The versioning schema consists of two digits in the form:

vXX-YY,

where XX denotes the major release tag and YY the minor release tag. We currently do not support patches, since the project is still quite young and the binary compatibility is broken with each release.

Code changes, which require clients to modify existing code are getting rare, since the main package DD4hep is maturing.

Supported Platforms

List of supported platforms (operating system + compiler):

 - SLC 6
 - MacOS (with low priority though)

Declined operating systems:

  - Microsoft Windows.

In principle DD4hep does not depend dramatically on specific operating systems. In principle any compiler modern enough to support C++11 may should be capable of building DD4hep. There are some C++ABI issues, which may have to be sorted out for non-gcc platforms, but most of this work was done for MacOS and it should be feasible to solve these problems for other platforms as well.

README

First glance information may be taken from the readme file at the following location.

Prerequisites

DD4hep depends on a number of "external" packages. The user will need to install these in his/her system before building and running the examples. Depending on the usage of DD4hep and it's subpackages software of other projects is used. The configuration options are described later in this document.

• DD4hep uses the CMake build system. A recent version (version 2.8 or higher) of CMake must be installed.
• DD4hep itself depends on the ROOT geometry package Tgeo and in turn on the basic ROOT libraries. Version 5.30 or higher is required.
• DD4hep uses the Boost-Spirit implementation to interprete input and options.
• Optionally DD4hep can use Xerces-C as a parser for XML input. By default it uses TinyXML, which is included in the DD4hep release.
• The subpackages for alignment DDAlign, conditions data \DDC and event display DDEve do not require additional external libraries.
• The simulation extensions extension DDG4 in addition depends on a valid Geant4 installation. Version 9 and 10 of Geant4 is supported.

If DD4hep is not installed in the system name-space (/usr/bin, /usr/lib, etc.) any number of DD4hep versions can exist in parallel.

Package Contents

The DD4hep project consists of several packages. The idea has been to separate the common parts of the detector description toolkit from concrete detector examples.

DDCore: Contains the definition of the basic classes of the toolkit: Handle, DetElement, Volume, PlacedVolume, Shapes, Material, etc. Most of these classes are "handles" to ROOT TGeom classes. The package provides the basic mechanisms for constructing the "Generic Detector Description Model" in memory from XML compact detector definition files.

DDG4: Is the package that contains the conversion of DD4hep geometry into Geant4 geometry to be used for simulation.

DDAlign: The DDAlign toolkit implements a modular and flexible approach to introduce and access the alignment parameters in DD4hep geometry descruptions.

DDCond: Support for conditions data for DD4hep.

DDEve: DDEve provides an event display for detector geometries implemented using DD4hep. DDEve hereby takes advantage of the TEve toolkit naturally provided by the ROOT framework like the ROOT geometry toolkit TGeo.

examples: Contains different detector examples (CLICSiD, AlignDet, ClientTests) together with example applications to illustrate the their usage for simulation, reconstruction and visualization with an emphasis to minimize software dependencies. For instance, the simulation application example will require to compiler and link against Geant4 but not the reconstruction application.

Installing DD4hep from Precompiled Binaries

The binaries are available for downloading from afs under the following location: to be done, currently not available.....

Once downloaded you need to unzip and de-tar the file. For example, if you have downloaded the debug version of DD4hep v00-13 for Linux-SLC6: % gunzip dd4hep-v00-13-slc6-gcc4.8-dbg.tar.gz % tar xvf dd4hep-v00-13-slc6-gcc4.8-dbg.tar.gz

This will create the directory root. Before getting started read the file ReadMe.txt. Also, read the Introduction chapter for an explanation of the directory structure.

TO BE DONE !!!

Access and Build DD4hep from the Repository

The following sections explain how to obtain a usable binary build of the DD4hep software.

Downloading the Code from the Repository

You can use the Subversion (svn) source code version control system and check out the most recent source. The compressed file is a one time only choice; every time you would like to upgrade you will need to download the entire new version.

The DD4hep code is accessible in anonymous read-only mode by anybody from the svn repository at Desy: % svn co https://svnsrv.desy.de/basic/aidasoft/DD4hep/trunk % mv trunk DD4hep_src

Installing the Source from Subversion

This paragraph describes how to checkout and build DD4hep from a checkout using subversion for Unix-like systems: % mkdir DD4hep_install % mkdir DD4hep_build % export DD4hepINSTALL=pwd/DD4hep_install % cd DD4hep_build % cmake -DCMAKE_BUILD_TYPE=Debug \ -DCMAKE_INSTALL_PREFIX=\${DD4hepINSTALL} \ [option [option]] ... % make install Possible additional options for the cmake build system are described in the following section.

Note: You might have to update your environment beforehand to have all needed libraries in the shared lib search path (this will vary with OS, shell, etc.) e.g: % . /data/ilcsoft/geant4/9.5/bin/geant4.sh % export CLHEP_BASE_DIR="/data/ilcsoft/HEAD/CLHEP/2.1.0.1" % export LD_LIBRARY_PATH="$CLHEP_BASE_DIR/lib:$LD_LIBRARY_PATH"

CMake Configuration Options

We describe in the following only options, which are unique to the build of DD4hep. Boolean values are either ON or OFF to enable or disable a feature.

Run-time Environment

During the build a shell script is generated and copied to the installation area called "thisdd4hep.(c)sh". To setup the runtime and build environment for layered software using DD4hep this script musty be source'd.

Using DD4hep in Layered Software as a Client

It is necessary to setup the DD4hep runtime environment before the configuration of the client software. In the installation directory the cmake build instructions DD4hepConfig.cmake are generated, to be used for the cmake configuration of the client software. Cmake should pick-up the build instructions automatically.

Relocation of the Installation directory

Once build, DD4hep can be tar'ed and/or moved to any other directory. The instructions for the usage by layered client software stay intact.

TO BE DONE !!!!!

Example Build Script

The following commands may be used to build DD4hep from the script in the svn repository.

#!/bin/bash
#
# ====  User configuration =========================================
# Set here the proper installation directories of the pre-requisites
# ==================================================================
SW=~/SW
MY_ROOT=${SW}/root_v5.34.25_dbg
MY_GEANT4=${SW}/g4_10.01.p02_dbg
MY_LCIO=${SW}/lcio/v02-04-03
MY_XERCES=${SW}/xerces-c-3.1.1
MY_DD4HEP=`pwd`/DD4hep_tmp2
# ==================================================================
# From here on all should be box-standard
# ==================================================================
. ${MY_ROOT}/bin/thisroot.sh
. ${MY_GEANT4}/bin/geant4.sh          # Remove line if no DDG4

mkdir -p ${MY_DD4HEP}/build
mkdir -p ${MY_DD4HEP}/install
cd ${MY_DD4HEP}
svn co https://svnsrv.desy.de/basic/aidasoft/DD4hep/trunk

cd    build
cmake -DCMAKE_BUILD_TYPE=Debug                                 \
      -DCMAKE_INSTALL_PREFIX=${MY_DD4HEP}/install              \
      -DCMAKE_MODULE_PATH=${MY_DD4HEP}/install                 \
      -DDD4HEP_USE_XERCESC=ON -DXERCESC_ROOT_DIR=${MY_XERCES}  \
      -DDD4HEP_USE_BOOST=ON                                    \
      -DDD4HEP_USE_GEANT4=ON -DGeant4_ROOT=${MY_GEANT4}        \
      -DDD4HEP_USE_LCIO=ON -DLCIO_DIR=${MY_LCIO}               \
      ../trunk

# Build and install
make -j 6 install

# Move to installation and setup runtime environment
cd ${MY_DD4HEP}/install
. bin/thisdd4hep.sh

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${MY_LCIO}/lib

# Run Examples....
python examples/DDG4/examples/CLICSidSimu.py

Notes:

• If Geant4 is not available or undesired remove lines 8 and 28.
• If you want to use TinyXML instead of Xerces-C remove lines 10, and 27.
• If LCIO I/O is not available or undesired remove lines 9, 29 and 39.

DD4hep Documentation

General build information is provided by this document: In addition all sub-packages of the DD4hep toolkit provide documentation in the form of manuals.

Suggestions (or better improvements) of user documentation of packages being validated are highly welcome. Please contact the developers using the DD4hep mailing list. If a package is under development and not offered to the public, please ignore the package and it's errors unless you are eager to contribute.

DD4hep User's Guide

The DD4hep guide is part of the distribution and the svn repository.
Author: M.Frank

DDAlign User's Guide

The DDAlign guide is part of the distribution and the svn repository.
Author: M.Frank

Note: This package is under development. The guide is very rudimentary.

DDCond User's Guide

The DDCond guide is part of the distribution and the svn repository.

Note: This package is under development. The guide is very rudimentary.

DDEve User's Guide

The DDEve guide is part of the distribution and the svn repository.

Note: This package is not officially part of DD4hep and in addition under development. The guide is very rudimentary.

DDG4 User's Guide

The DDG4 guide is part of the distribution and the svn repository.
Author: M.Frank

DDRec User's Guide

The DDRec guide is part of the distribution and the svn repository.
Author: F.Gaede

Reference Manual

An up to date build of the code documentation compiled using Doxygen can be found at the following URL.

Testing and Nightly builds

A CDash installation provides daily information about the the current status of the software in the svn trunk.

How to contribute

DD4hep was started by me in the year 2012 in response of the needs of the linear collider community (ILD, CLIC) for a flexible detector geometry usable to develop tracking code. This development relatively quickly emerged into desire to actually obtain a complete description of the entire detector spanning not only the geometrical part, but "everything" required to process the data from particle collisions including provision to support all sorts of conditions data and alignment data. Obviously the simulation of particle collisions should more or less come with it for free and - of course - once simulated, the results want to be visualized.

These initial requirement led to a substantial development, which however is not complete and always wants to be improved - and if only to be adapted to new compiler versions. For this reason additional effort from the emerging user community is highly welcome. If you are convinced by the concept, but lack some functionality and are willing to add this as a contribution you are more then welcome. If your changes affect the basic design I would appreciate to be contacted in advance for a brief discussion of your plans.

DD4hep is supposed to quickly enable users to develop test and simulate the physics response of new detector models and concepts. Although a certain palette of such subdetectors concepts is provided in the DDDetectors package, the palette is not complete. I would like to encourage users to contribute missing subdetector designs such e.g. RICH detectors provided the design is modular and flexible so it can be picked up by the community.

The same argument obvious applies to the development of new or more detailed sensitive detector concepts for the DDG4 package.

Contributors

In the CREDITS file the most important contributors to the DD4hep project and a short description of their work can be found. If you think you should be part of this list, but somehow got forgotten, please contact us.

Conclusions

No a lot to be said: Good luck! ... and have fun!.

References