diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..c8942cb377ab91a866229eb5cebdc59baaeec4b2 --- /dev/null +++ b/README.md @@ -0,0 +1,152 @@ +# DD4hep (Detector Description for High Energy Physics) + + +DD4hep is a software framework for providing a complete solution for full detector description +(geometry, materials, visualization, readout, alignment, calibration, etc.) for the full experiment life cycle (detector concept development, detector optimization, construction, operation). It offers a consistent description through a single source of detector information for simulation, reconstruction, analysis, etc. It distributed under the [GPLv3 License](http://www.gnu.org/licenses/gpl-3.0.en.html) + + + + +## 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 鈥榟andles鈥� to ROOT TGeom classes. The package provides the basic mechanisms for constructing the 鈥楪eneric Detector Description Model鈥� in memory from XML compact detector definition files. Two methods are currently supported: one based on the C++ XercesC parser, and another one based on Python and using the PyROOT bindings to ROOT. + + Two configuration options selects the desired method: + `DD4HEP_USE_PYROOT:BOOL` + `DD4HEP_USE_XERCESC:BOOL` + +- **DDG4** + + Is the package that contains the conversion of DD4hep geometry into Geant4 geometry to be used for simulation. The conversion is currently based on the Virtual Geometry Modeler (VGM) package that is build internally when required. The option DD4HEP_USE_GEANT4:BOOL controls the building or not of this package that has the dependency to Geant4. The Geant4 installation needs to be located using the variable `-DGeant4_DIR=<path to Geant4Config.cmake>` + +- **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. + + For each detector example the directory 鈥榗ompact鈥� contains the XML compact detector description, the +directory 鈥榙rivers鈥� contains the Python functions to construct the detector from the XML, the 鈥榠nclude鈥� +and 鈥榮rc鈥� contain the equivalent drivers for the XercesC parser. + +## Pre-requisites + + DD4hep depends on a number of 鈥榚xternal鈥� packages. The user will need to install these in his/her +system before building and running the examples + +- **Mandatory** + + CMake (version 2.8 or higher), ROOT (version 5.30 or higher) and Boost installations are mandatory. + +- **Optional** + + If the XercesC is used to parse compact descriptions and installation of XercesC will be required. To build and run the simulation examples Geant4 will be required. There is also an available interface to LCIO + +## How to build DD4hep +### Checkout code +`svn co https://svnsrv.desy.de/public/aidasoft/DD4hep/trunk DD4hep` + +### Set the environment +at least ROOT and BOOST needs to be initialized, e.g. +`. /afs/cern.ch/sw/lcg/app/releases/ROOT/6.06.02/x86_64-slc6-gcc48-opt/root/bin/thisroot.sh` +and +`export BOOST_ROOT=/afs/cern.ch/sw/lcg/releases/LCG_84/Boost/1.59.0_python2.7/x86_64-slc6-gcc48-opt` + +### Configure and build + + `cd DD4hep` + + `mkdir build; cd build` + + `cmake -DBoost_NO_BOOST_CMAKE=ON ..` + + `make -j4 install` + +### Additional useful build options: + + * build Doxygen documentation ( after 'install' open ./doc/html/index.html) + + `-D INSTALL_DOC=on ` + + * build with geant4 support: + + `-D DD4HEP_USE_GEANT4=on -D Geant4_DIR=__path_to_Geant4Config.cmake__` + + 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. `. __path_to_Geant4__/bin/geant4.sh` + `export CLHEP_BASE_DIR="__path_to_CLHEP__"` + `export LD_LIBRARY_PATH="$CLHEP_BASE_DIR/lib:$LD_LIBRARY_PATH"` + + + * use XercesC instead of TinyXml + `-D DD4HEP_USE_XERCESC=ON -D XERCESC_ROOT_DIR=__path_to_xercesc__` + + + * use pyroot to write python geometry drivers + `-D DD4HEP_USE_PYROOT=ON` + +### Setup the environment for running + + `. ./bin/thisdd4hep.sh` + +or + + `source ./bin/thisdd4hep.csh` + + +## Testing + + + DD4hep has a testing mechanism built on CMake/CTest. If configured with `-DBUILD_TESTING=ON`, some make targets are + created automatically. + + - running the tests: + + `cd build` + + `make install` + + `make test` + + - running the build + + For each commit all tests are run through **gitlab CI**. DD4hep is tested against gcc 4.8 and 4.9 on SLC6 and with gcc 4.9 on CC7. Build results can be observed [here](https://gitlab.cern.ch/CLICdp/DD4hep/builds) and the status is indicated by the badge  + + + - running individual tests with output (e.g. in case of failed tests): + + `cd build` + + `ctest -V -R units` + # runs only test_units + + - running nightly builds and tests with cdash: + + `make NightlyStart` + + `make NightlyConfigure` + + `make NightlyBuild` + + `make install` + + `make NightlyTest` + + `make NightlySubmit` + +## Documentation + +Doxygen documentation is build nightly and can be found [here](http://test-dd4hep.web.cern.ch/test-dd4hep/doxygen/html/index.html) + + +## Extending + +Users may extend the models by changing the compact description or adding new drivers + + +## Release notes + +If things do not work please also consult the release notes. It may happen that it was forgotten to update the information here. + + diff --git a/ReadMe.txt b/ReadMe.txt deleted file mode 100644 index aa96c47e7a8307c5861c7aeef428efdd4fe2ef9b..0000000000000000000000000000000000000000 --- a/ReadMe.txt +++ /dev/null @@ -1,216 +0,0 @@ -Detector Description for HEP Package -------------------------------------- - -1) 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 鈥榟andles鈥� to ROOT TGeom classes. -The package provides the basic mechanisms for constructing the 鈥楪eneric Detector Description Model鈥� -in memory from XML compact detector definition files. Two methods are currently supported: one based -on the C++ XercesC parser, and another one based on Python and using the PyROOT bindings to ROOT. - - Two configuration options selects the desired method: - - DD4HEP_USE_PYROOT:BOOL - DD4HEP_USE_XERCESC:BOOL - -- DDGeant4 - - Is the package that contains the conversion of DD4hep geometry into Geant4 geometry to be used for -simulation. The conversion is currently based on the Virtual Geometry Modeler (VGM) package that is -build internally when required. - The option DD4HEP_USE_GEANT4:BOOL controls the building or not of this package that has the dependency -to Geant4. The Geant4 installation needs to be located using the variable -DGeant4_DIR=<path to Geant4Config.cmake> - -- 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. - - For each detector example the directory 鈥榗ompact鈥� contains the XML compact detector description, the -directory 鈥榙rivers鈥� contains the Python functions to construct the detector from the XML, the 鈥榠nclude鈥� -and 鈥榮rc鈥� contain the equivalent drivers for the XercesC parser. - - -3) Pre-requisites ------------------ - - DD4hep depends on a number of 鈥榚xternal鈥� packages. The user will need to install these in his/her -system before building and running the examples - -- Mandatory - CMake (version 2.8 or higher) and ROOT (version 5.30 or higher) installations are mandatory. - -- Optional - If the XercesC is used to parse compact descriptions and installation of XercesC will be required. -To build and run the simulation examples Geant4 will be required. - - -4.1) How to build DD4hep ------------------------ - -- Checkout code - - svn co https://svnsrv.desy.de/public/aidasoft/DD4hep/trunk DD4hep - -- set the environment, at least ROOT needs to be initialized, e.g. - - source /data/ilcsoft/root/5.34.03/bin/thisroot.sh - - ( minimum is: export ROOTSYS=/data/ilcsoft/root/5.34.03 ) - - -- configure and build - - cd DD4hep - mkdir build; cd build - cmake .. - make -j install - - -- some useful build options: - - * build doxygen documentation ( after 'install' open ./doc/html/index.html) - -D INSTALL_DOC=on - - * build with geant4 support: - -D DD4HEP_USE_GEANT4=on -D Geant4_DIR=__path_to_Geant4Config.cmake__ - - [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" - ] - - * use xerces instead of tinyxml - -DDD4HEP_USE_XERCESC=ON -DXERCESC_ROOT_DIR=<xercesc> - - - * use pyroot to write python geometry drivers ( currently broken !?) - -DDD4HEP_USE_PYROOT=ON - - - examples for building a 'complete' DD4hep: - cmake -D DD4HEP_USE_GEANT4=1 -DDD4HEP_USE_BOOST=ON -DDD4HEP_USE_LCIO=ON -DBOOST_ROOT=/data/ilcsoft/boost/1.55.0 -DBUILD_TESTING=On .. - (if geant4 was built with external CLHEP, add: -D CLHEP_DIR=_path_to_CLHEP ) - - cmake -D DD4HEP_USE_GEANT4=1 -DGeant4_DIR=/data/ilcsoft/geant4/10.01.p01/lib/Geant4-10.1.1 -DDD4HEP_USE_BOOST=ON -DDD4HEP_USE_LCIO=ON -DBOOST_ROOT=/data/ilcsoft/boost/1.55.0 -DBUILD_TESTING=On -D CLHEP_DIR=/data/ilcsoft/HEAD/CLHEP/2.2.0.4 .. - -- Setup the environment for running - - . ./bin/thisdd4hep.sh - or - source ./bin/thisdd4hep.csh - - - -5) Testing ------------ - - DD4hep has a testing mechanism built on CMake/CTest. If configured with -DBUILD_TESTING=On, some make targets are - created automatically. - - running the tests: - - cd build - make install - make test - - - running the build - after an update (to the trunk) and then the tests with finally submitting the results to the Dasboard - ( http://aidasoft.desy.de/CDash/index.php?project=DD4hep ) - - cd build - make -j4 ExperimentalStart ExperimentalUpdate ExperimentalBuild ExperimentalSubmit - make install ExperimentalTest ExperimentalSubmit - - - running individual tests with output (e.g. in case of failed tests): - - cd build - ctest -V -R units - # runs only test_units - - - running nightly builds and tests with cdash: - - make NightlyStart - make NightlyConfigure - make NightlyBuild - make install - make NightlyTest - make NightlySubmit - - -6) Extending ------------- - - Users may extend the models by changing the compact description or adding new drivers - - -7) Release notes ----------------- - If things do not work please also consult the release notes. It may happen that it was - forgotten to update the information here. - - -8) Building the examples ------------------------ - -Before any of the (new) examples in the ./examples directory can be build, -one needs to set the environment: - - source __path_where_DD4hep_is_installed_/bin/thisdd4hep.sh - source __path_to_ilcsoft_installation/init_ilcsoft.sh - -or, optionally one can initialize ROOT only, and then specify all dependencies -on the cmake command line - replace 'cmake ..' below with, e.g: - - source /space/ilcsoft/root/5.34.05/bin/thisroot.sh - cmake -DDD4hep_DIR=~/DD4Hep/trunk/ -DGeant4_DIR=/space/ilcsoft/geant4/9.6.p01/lib/Geant4-9.6.1 \ - -D LCIO_DIR=/space/ilcsoft/v01-17-04/lcio/v02-04-03 -D GEAR_DIR=/space/ilcsoft/v01-17-04/gear/v01-03-01 .. - -(change pathes according to your environment) - - -- then building the examples should be very straight forward. e.g: - (check for additional instructions in example subdirectory) - - cd ./examples/SimpleDetector/ - mkdir build ; cd build - cmake .. - make -j install - -or build all examples in one go: - - cd ./examples - mkdir build ; cd build - cmake .. - make -j install - - -- before running the example, initialize the environment: - . ./bin/thisSimpleDetector.sh - - -- then you can for example display the ILD detector (toy model): - - geoDisplay ../compact/Simple_ILD.xml - -- or convert the compact to an lcdd file: - - geoConverter -compact2lcdd -input file:../compact/Simple_ILD.xml -output Simple_ILD.lcdd - - -- running example tests: - ----------------------- - - make install ; make test - - ... - -