Full simulation and reco
Quick tutorials
This is quick tutorial with the steps of how to run sim&recon from scratch. This work both on BNL and JLab farms as well as personal PCs.
0. Install eic-shell
> curl https://eicweb.phy.anl.gov/containers/eic_container/-/raw/master/install.sh | bash
# to run eic environment in singularity container
> ./eic-shell
More on installing and using singularity here: Use singularity
1. Convert MCEG to HepMC
The input format should be in HepMC format. If the conversion is needed: Convert MCEG
2. Run DD4HEP simulation
Select a detector
# Detectors live in
# /opt/detectors
# one can select particular configuration as
# source /opt/detector/athena-deathvalley-1.5T/setup.sh
#
# or one can set the latest detector
source /opt/detector/setup.sh
# Run simulation
npsim --compactFile=$DETECTOR_PATH/athena.xml --runType=run -N=2 --outputFile=sim_output.edm4hep.root --inputFiles mceg.hepmc
3. Run Juggler/Gaudi reconstruction
#set the same detector as in the simulations
source /opt/detector/setup.sh
export JUGGLER_SIM_FILE=sim_output.edm4hep.root JUGGLER_REC_FILE=rec_output.edm4hep.root JUGGLER_N_EVENTS=10
gaudirun.py /opt/benchmarks/physics_benchmarks/options/reconstruction.py
Full Tutorials
More detailed tutorials are available on a dedicated websites:
Detector simulation
Tracking
Full simulation tips
Particle gun
There are at least 2 ways of running a particle gun out of the box:
using npsim command line
using geant macro file and invoke gps
Using npsim (wrapper around ddsim) command line:
# Assumed to run from the root of Athena detector repo
# no spread
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=''
# uniform spread inside an angle:
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
Using GPS
General Particle Source tutorial
GPS is configured in Geant4 macro files. An example of such file may be found here
To run npsim with GPS you have to add –enableG4GPS flag and specify Geant4 macro file:
npsim --runType run --compactFile athena.xml --enableG4GPS --macro macro/gps.mac --outputFile gps_example.root
Geometry visualization
There are many ways to see the geometry and tracks:
Through Geant4 event display
geoDisplay (root geoViewer)
ddeve (root EVE based event display…)
dd_web_display (using browser and jsroot library)
To run Geant4 event display:
# Assumed to run from the root of Athena detector repo
npsim --runType vis --compactFile athena.xml --macro macro/vis.mac --outputFile test.root --enableG4GPS --enableQtUI
Geometry conversion
Convert to GDML
There is a convert_to_gdml.py script in the detector repository (https://eicweb.phy.anl.gov/EIC/detectors/athena/-/blob/master/scripts/convert_to_gdml.py). That can be used to export ALL of ATHENA to gdml, but not individual detector systems.
This is actually done on every commit and the results are saved as job artifacts.
Convert to root
One can use dd_web_display to actually just save root geometry
dd_web_display --export athena.xml # will create a .root file with the geometry
How XML is invoked from C++ in DD4Hep
> How does the XML file in the compact directory know which c++ file to load when we include the respective XML file in the main athena.xml file?
Xml compact files has <detector …></detector> tag which has type attribute that tells which C++ type to use:
<detector id="ForwardRICH_ID" name="DRICH" type="athena_DRICH" ... >
C++ file usually has createDetector(…) function and DECLARE_DETELEMENT macro which binds the function to the name used in xml <detector> type attribute. C++ code looks like this:
static Ref_t createDetector(Detector& desc, xml::Handle_t handle, SensitiveDetector sens) { // ... } DECLARE_DETELEMENT(athena_DRICH, createDetector)
How DD4Hep finds and loads compiled components?
> This is going into technical details which users usually don’t need. Installation paths and environment variables are set by container/spack and should work out of the box.
DD4Hep uses modular plugin mechanism to load C++ code. When athena C++ is compiled, two files are created: - athena.components - a text file stating what components one can find in athena.so. From our example, there will be a record like v2:libathena.so:athena_DRICH among other records. - libathena.so - compiled C++ library with all detectors from athena repo
So when the type of the detector is given, like athena_DRICH. DD4Hep uses LD_LIBRARY_PATH to look through .components files and then figures out what .so file to load to get the correct C++ code executed.