Warning, /EICrecon/docs/howto/full_chain_simulation.md is written in an unsupported language. File is not indexed.
0001 Full simulation and reco
0002 ========================
0003
0004 Quick tutorials
0005 ---------------
0006
0007 This is quick tutorial with the steps of how to run sim&recon from
0008 scratch. This work both on BNL and JLab farms as well as personal PCs.
0009
0010 ### 0. Install eic-shell
0011
0012 ``` {.bash}
0013 > curl https://eicweb.phy.anl.gov/containers/eic_container/-/raw/master/install.sh | bash
0014
0015 # to run eic environment in singularity container
0016 > ./eic-shell
0017 ```
0018
0019 More on installing and using singularity here: [Use
0020 singularity](use_singularity.html)
0021
0022 ### 1. Convert MCEG to HepMC
0023
0024 The input format should be in HepMC format. If the conversion is needed:
0025 [Convert MCEG](mceg.html)
0026
0027 ### 2. Run DD4HEP simulation
0028
0029 Select a detector
0030
0031 ``` {.bash}
0032 # Detectors live in /opt/detector
0033 # One can select particular configuration as
0034 # source /opt/detector/epic-main/bin/thisepic.sh
0035 #
0036 source /opt/detector/epic-main/bin/thisepic.sh
0037
0038 # Run simulation
0039 npsim --compactFile=$DETECTOR_PATH/athena.xml --runType=run -N=2 --outputFile=sim_output.edm4hep.root --inputFiles mceg.hepmc
0040 ```
0041
0042 ### 3. Run Juggler/Gaudi reconstruction
0043
0044 ``` {.bash}
0045 #set the same detector as in the simulations
0046 source /opt/detector/epic-main/bin/thisepic.sh
0047
0048 export JUGGLER_SIM_FILE=sim_output.edm4hep.root JUGGLER_REC_FILE=rec_output.edm4hep.root JUGGLER_N_EVENTS=10
0049 gaudirun.py /opt/benchmarks/physics_benchmarks/options/reconstruction.py
0050 ```
0051
0052 ### Particle gun
0053
0054 There are at least 2 ways of running a particle gun out of the box:
0055
0056 - using npsim command line
0057 - using geant macro file and invoke GPS
0058
0059 Using npsim (wrapper around ddsim) command line:
0060
0061 ``` {.bash}
0062 # Assumed to run from the root of Athena detector repo
0063 # no spread
0064 npsim --compactFile=athena.xml --runType=run -G -N=2 --outputFile=test_gun.root --gun.position "0.0 0.0 1.0*cm" --gun.direction "1.0 0.0 1.0" --gun.energy 100*GeV --part.userParticleHandler=''
0065
0066 # uniform spread inside an angle:
0067 npsim --compactFile=athena.xml -N=2 --random.seed 1 --enableGun --gun.energy 2*GeV --gun.thetaMin 0*deg --gun.thetaMax 90*deg --gun.distribution uniform --outputFile test.root
0068 ```
0069
0070 Using GPS
0071
0072 [General Particle Source
0073 tutorial](https://geant4-userdoc.web.cern.ch/UsersGuides/ForApplicationDeveloper/html/GettingStarted/generalParticleSource.html)
0074
0075 GPS is configured in Geant4 macro files. An example of such file [may be
0076 found
0077 here](https://eicweb.phy.anl.gov/EIC/detectors/athena/-/blob/master/macro/gps.mac)
0078
0079 To run npsim with GPS you have to add [\--enableG4GPS]{.title-ref} flag
0080 and specify Geant4 macro file:
0081
0082 ``` {.bash}
0083 npsim --runType run --compactFile athena.xml --enableG4GPS --macro macro/gps.mac --outputFile gps_example.root
0084 ```
0085
0086 ### Geometry visualization
0087
0088 There are many ways to see the geometry and tracks:
0089
0090 1. Through Geant4 event display
0091 2. geoDisplay (root geoViewer)
0092 3. ddeve (root EVE based event display\...)
0093 4. dd\_web\_display (using browser and jsroot library)
0094
0095 To run Geant4 event display:
0096
0097 ``` {.bash}
0098 # Assumed to run from the root of Athena detector repo
0099 npsim --runType vis --compactFile athena.xml --macro macro/vis.mac --outputFile test.root --enableG4GPS --enableQtUI
0100 ```
0101
0102 Geometry conversion
0103 -------------------
0104
0105 ### Convert to GDML
0106
0107 There is a convert\_to\_gdml.py script in the detector repository
0108 (<https://eicweb.phy.anl.gov/EIC/detectors/athena/-/blob/master/scripts/convert_to_gdml.py>).
0109 That can be used to export ALL of ATHENA to gdml, but not individual
0110 detector systems.
0111
0112 This is actually
0113 [done](https://eicweb.phy.anl.gov/EIC/detectors/athena/-/blob/master/.gitlab-ci.yml#L168)
0114 on every commit and the results are saved as job artifacts.
0115
0116 [The latest athena.gdml from the master
0117 branch](https://eicweb.phy.anl.gov/api/v4/projects/473/jobs/artifacts/master/raw/geo/athena.gdml?job=report&item=default)
0118
0119 ### Convert to root
0120
0121 One can use dd\_web\_display to actually just save root geometry
0122
0123 ``` {.bash}
0124 dd_web_display --export athena.xml # will create a .root file with the geometry
0125 ```
0126
0127 How XML is invoked from C++ in DD4Hep
0128 -------------------------------------
0129
0130 \> How does the XML file in the compact directory know which c++ file to
0131 load when we include the respective XML file in the main athena.xml
0132 file?
0133
0134 1. Xml compact files has [\<detector \...\>\</detector\>]{.title-ref}
0135 tag which has [type]{.title-ref} attribute that tells which C++ type
0136 to use:
0137
0138 ``` {.xml}
0139 <detector id="ForwardRICH_ID" name="DRICH" type="athena_DRICH" ... >
0140 ```
0141
0142 2. C++ file usually has [createDetector(\...)]{.title-ref} function and
0143 [DECLARE\_DETELEMENT]{.title-ref} macro which binds the function to
0144 the name used in xml [\<detector\>]{.title-ref} type attribute. C++
0145 code looks like this:
0146
0147 ``` {.c++}
0148 static Ref_t createDetector(Detector& desc, xml::Handle_t handle, SensitiveDetector sens) {
0149 // ...
0150 }
0151
0152 DECLARE_DETELEMENT(athena_DRICH, createDetector)
0153 ```
0154
0155 3. How DD4Hep finds and loads compiled components?
0156
0157 \> This is going into technical details which users usually don\'t
0158 need. Installation paths and environment variables are set by
0159 container/spack and should work out of the box.
0160
0161 DD4Hep uses modular plugin mechanism to load C++ code. When athena
0162 C++ is compiled, two files are created:
0163
0164 - [athena.components]{.title-ref} - a text file stating what
0165 components one can find in athena.so. From our example, there
0166 will be a record like
0167 [v2:libathena.so:athena\_DRICH]{.title-ref} among other records.
0168 - [libathena.so]{.title-ref} - compiled C++ library with all
0169 detectors from athena repo
0170
0171 So when the type of the detector is given, like
0172 [athena\_DRICH]{.title-ref}. DD4Hep uses
0173 [LD\_LIBRARY\_PATH]{.title-ref} to look through .components files
0174 and then figures out what .so file to load to get the correct C++
0175 code executed.