persistency/P01/README.md

0001 \page ExampleP01 Example P01
0002
0003
0004 ## General description
0005
0006 This example shows how to store produced hits in a file using
0007 the 'reflection' technique for persistency provided by the Reflex tool
0008 included in ROOT. The Reflex tool allows to create a dictionary
0009 for the hit class, making then possible to save hit objects in a .root
0010 file. The general simulation setup (geometry, physics list, user
0011 actions, etc...) is taken from ExampleN02.
0012
0013 The provided makefile produces two executables: 'exampleP01' and
0014 'readHits'. The first one is the actual Geant4 simulation application
0015 with hits persistency. The second one, is just a simple 'reader' for
0016 the produced .root file (you need to specify the name of the .root
0017 file as argument).
0018
0019
0020 ## Building and running the example
0021
0022 This examples requires the ROOT toolkit of version 6 to be installed. The
0023 provided CMake file checks for the existence of the package and its version.
0024 Once the CMake configuration has been succesfully done, the two executables
0025 for this example (exampleP01, readHits) should be built using make
0026 (in your CMake build directory):
0027 ```
0028 make
0029 ```
0030
0031 When the example is run (using the provided run.mac macro file) the
0032 events are generated and the produced hits will be stored in
0033 the hits.root file. In addition, the hits will be printed out on the
0034 screen so one can then compare them with the 'reader' output.
0035
0036 In order to read the persistified hits, a small 'reader' application
0037 has been implemented. It can be run in the following way:
0038
0039 ```
0040 ./readHits hits.root
0041 ```
0042
0043 where the argument is the name of the file to be read. All the hits
0044 saved in that file will be then read and printed on the screen.
0045
0046 In addition to that the readHits.C ROOT macro file is provided, which
0047 illustrates how one can read the hits file directly from the ROOT
0048 prompt.
0049
0050 ## Remark on dictionary generation
0051
0052 The dictionary is generated by ${ROOTSYS}/bin/genreflex
0053 tool. The arguments that will be used by this tool are configured
0054 in CMakeLists.txt using the CMake function REFLEX_GENERATE_DICTIONARY
0055 provided by ROOT. They include the header file including headers for
0056 all the classes we want to generate the dictionary, and additionally,
0057 a so called selection file (xml). The role of this file is to
0058 specify which classes we want to generate the dictionary for. The
0059 selection file for our dictionary is in xml/ directory. Please refer
0060 to genreflex manual for more details concerning the usage of that
0061 tool.
0062
0063 Concerning generating dictionary for the Geant4 objects, there are
0064 also two technical remarks that need to be made here.
0065 The Reflex tool requires all the templated classes to be
0066 explicitely used somewhere in the included header files in order for
0067 the generation of the dictionary to be possible. For those templated
0068 classes for which it is not the case, the problem can be very easily
0069 solved by instaciating them in the headerfile which is given to
0070 genreflex (see ExP01Classes.hh) as argument.
0071 The second remark is that there is an unfortunate clash of names as
0072 far as G4String class is concerned. The header of G4String class
0073 defines __G4String which happens to be the name of a variable used
0074 within the generated dictionary code. The solution for that is to do
0075 ```cpp
0076 #undef __G4String
0077 ```
0078 in include/ExP01Classes.hh file.