This is the first tutorial of the dRICH Tutorial Series, which will cover setup and running of dRICH simulations.
- Setup of eic-shell and Github: https://indico.bnl.gov/event/16826/
- DD4hep geometry basics: https://indico.bnl.gov/event/16828/
First, clone the necessary repositories from Github and from EICweb. If you are a member of the EIC organization on Github and a member of the EPIC Devs Team, you may clone Github repositories with SSH, otherwise you must clone with HTTPS. Direct contributions to Github repositories requires SSH access, otherwise you must fork repositories. The story is the same for EICweb: use SSH if you are a member, otherwise use HTTPS.
In today's tutorial we will only be working with the following repositories:
drich-devepicEICrecon(somedrich-devlocal code is dependent on this)
These are the only ones you need to clone for today. Future tutorials will use other repositories, so after today's tutorial, it is recommended to clone those as well. Here are the clone commands:
drich-devSSH:git clone [email protected]:eic/drich-dev.git
HTTPS:git clone https://github.com/eic/drich-dev.git
Once you have a clone of drich-dev, you must cd into it, prior to cloning the other repositories:
cd drich-devNow proceed by cloning the other repositories (today we will only need epic):
- Github Repositories:
SSH:git clone [email protected]:eic/epic.git git clone [email protected]:eic/irt.git git clone [email protected]:eic/EDM4eic.git git clone [email protected]:eic/EICrecon.git
HTTPS:git clone https://github.com/eic/epic.git git clone https://github.com/eic/irt.git git clone https://github.com/eic/EDM4eic.git git clone https://github.com/eic/EICrecon.git
- EICweb Repositories:
SSH:git clone [email protected]:EIC/benchmarks/reconstruction_benchmarks.git
HTTPS:git clone https://eicweb.phy.anl.gov/EIC/benchmarks/reconstruction_benchmarks.git
During development, you may make changes to multiple different repositories, and may be on different branches on each. To help keep track, there are two scripts:
./check_branches.sh # list the current branch on every repository
./check_status.sh # run 'git status' for each repositoryThe eic-shell image contains all of the necessary software to run ePIC simulations and reconstruction, including builds of the repositories that you cloned above. We make our own clones here in drich-dev, so that you may override the eic-shell image builds and make changes.
From here on, you must be in an eic-shell container shell.
You can find which versions of software are installed in eic-shell by running:
eic-infoYou may also find the installations themselves at /opt/local, which is useful if you want to check header files or libraries.
Let's now build the local repositories, which will override the eic-shell builds.
First, set the environment variables:
source environ.shCheck if the number of CPUs was detected correctly:
echo $BUILD_NPROCIf it is wrong, then we need to fix the number detection in environ.sh; for now just hard code the correct number in environ.sh and run source environ.sh again, or just run
export BUILD_NPROC=<CORRECT_NUMBER>replacing <CORRECT_NUMBER> with the correct number
Practically all repositories use cmake, so you may proceed using the typical cmake commands. For convenience, drich-dev provides a cmake wrapper build.sh to build any local repository. The syntax is:
build.sh <REPOSITORY> # build a repository named <REPOSITORY>
build.sh <REPOSITORY> clean # remove the cmake buildsystem, and then buildBy default, the installation prefix (CMAKE_INSTALL_PREFIX) will be $EIC_SHELL_PREFIX. Running source environ.sh has modified your default $EIC_SHELL_PREFIX to a local directory: ./prefix; this directory is where all the software that build.sh builds will be installed.
Today, we only need to build epic (you do not need to build EICrecon yet):
build.sh epicIt's not yet necessary, but you may build the other repositories by running:
build.sh irt
build.sh EDM4eic
build.sh EICrecon
build.sh reconstruction_benchmarksImportant: if you choose to build all of the repositories, you need to be sure to build them in the correct order of dependence. You can build all of the repositories in this order by running:
rebuild_all.sh # build all the repositories (that you have cloned) in the recommended order
rebuild_all.sh clean # remove the cmake buildsystems, and then buildNotice that the build scripts allow for a clean option, which is useful for starting over from a clean state. In case you want to clean everything and start over, simply remove the ./prefix directory, then run rebuild_all.sh clean. This is also useful to do after upgrading your eic-shell image (run eic-shell --upgrade), which you should do regularly, unless you are using a CVMFS build.
After you have built the repositories, sourcing the environment variables file will set some additional variables to complete the override of eic-shell; run it again:
source environ.shNow that you have a build installed in ./prefix, the next time you open an eic-shell container, you just need to run source environ.sh to get started.
Finally, build the local code in drich-dev, which uses a Makefile:
make # build drich-dev code
make clean # remove drich-dev build (run 'make' again afterward to rebuild)The epic repository contains the geometry for ePIC and is based on DD4hep. The next tutorial will go over the code within, but today we will learn how to run it.
First, let's look at the dRICH geometry itself. The geoConverter command is used for this; for convenience drich-dev provides a wrapper: geometry.sh. Run:
geometry.sh # print the usage guide
geometry.sh -d # make a TGeo ROOT file for the dRICH only
geometry.sh -e # make a TGeo ROOT file for the full ePIC detector
By default the output file will be geo/detector_geometry.root. You may open it with ROOT or JSROOT. For JSROOT, you may use a hosted instance (found in the aforementioned link), or you may host your own instance (see below; this is convenient if you intend to make many geometry changes).
Coordinate system:
- x axis is horizontal, to the left when facing the dRICH
- y axis is vertical, toward the sky
- z axis is along the electron beamline, toward the dRICH
There are several constant numbers in the geometry, for example, the z-position of the dRICH. You may view them using the npdet_info tool; for convenience, drich-dev provides a wrapper script search_compact_params.sh. Run:
search_compact_params.sh # print the usage guide
search_compact_params.sh -e # dump all of the constants for ePIC
search_compact_params.sh -e | grep DRICH # dump all of the constants for the dRICH (they all begin with 'DRICH')The first column is the constant name, the second is the raw value (numbers in standard DD4hep units), and the third column is the original formula or specification used for the constant). Length units are centimeters.
Checking for geometry overlaps is a computationally intensive procedure; therefore, it is better to let the Continuous Integration (CI) run overlap checks. CI jobs are triggered by every commit to a branch associated with a pull request. If you want to run overlap checks locally, run overlap_check.sh.
Using a remotely hosted JSROOT instance has its limitations; namely, every time you make a change to the geometry you must re-upload the TGeo ROOT file. For better productivity, consider self-hosting by following this guide.
First, download a release of JSROOT and unpack it to somewhere, for example ~/jsroot.
Make a symbolic link to the drich-dev/geo subdirectory
ln -s /path/to/drich-dev/geo ~/jsroot/Add the following script, named jsroot to your $PATH:
#!/bin/bash
pushd ${HOME}/jsroot # change this to wherever you unpacked the jsroot release
echo "FOR FULL DETECTOR:"
printf "\nhttp://localhost:8000/?file=geo/detector_geometry.root&dark&opt=ctrl;\n\n"
echo "FOR DRICH ONLY:"
printf "\nhttp://localhost:8000/?file=geo/detector_geometry.root&dark&item=default/world_volume/DRICH_0/DRICH_gas_0&opt=ctrl;vislvl8;more\n\n"
echo "FOR PFRICH ONLY:"
printf "\nhttp://localhost:8000/?file=geo/detector_geometry.root&dark&item=default/world_volume/PFRICH_0/PFRICH_gas_0&opt=ctrl;vislvl8;more\n\n"
echo "============================================"
python -m http.server
popdRun jsroot from your shell (not eic-shell) and open one of the URLs in your browser (when you are done, you may terminate the HTTP server by pressing ^C). As you make changes to the geometry in epic, you just need to:
build.sh epic && geometry.sh -d # or your preferred option, such as -e
Then refresh the webpage you have opened in your browser to see the update.
Now let's throw particles at the dRICH. To run simulations in DD4hep, use ddsim; however, this will not enable Cherenkov physics. ePIC therefore uses an extended version of ddsim, called npsim, to enable Cherenkov physics and some other settings for the PID detectors.
Here in drich-dev, we have a wrapper of npsim specific for the dRICH: simulate.py. This script generates Geant4 macro files and runs them with npsim. You can either run one of the "tests" or supply a hepmc file. Run with no arguments for a usage guide:
simulate.pyLet's run test 1 with 10 events, which will throw 10 pi+s at the angle of theta=23.5 degrees, 20 GeV each (the defaults, at the time of writing this tutorial):
simulate.py -t1 -n10Exercise: try other particles, energies, angles, or other tests.
The resulting file will be out/sim.edm4hep.root and it contains the TTree called events. Let's open the file:
root out/sim.edm4hep.root
new TBrowser()For convenience, environ.sh added a function broot() to automatically open a file in a TBrowser, so you could alternatively run broot out/sim.edm4hep.root.
The dRICH simulated hits (pre-digitization) are in the DRICHHits branch. The datatype is edm4hep::SimTrackerHit, and as part of the common Event Data Model for High Energy Physics (EDM4hep), you may find documentation here
Draw the number of incident photons per event:
events->Draw("@DRICHHits.size()") // the syntax for this particular TLeaf is a bit strange, but see the TBrowser view
Draw the energy deposition:
events->Draw("DRICHHits.EDep")The units are standard: GeV. Let's instead draw the wavelength in nanometers:
events->Draw("1239.8/DRICHHits.EDep/1e9")
(note there are cutoffs at 200 and 700 nm, because of issues in the material property tables).
Draw the (true, non pixelated) hit positions:
events->Draw("DRICHHits.position.y:DRICHHits.position.x")Zoom in on the Cherenkov rings
Alternatively, drich-dev provides the executable draw_hits to draw these hits:
draw_hits d
display out/sim.edm4hep.hits.png
Exercise: Check out the other branches and make some plots.
Exercise: Run some of the other tests, for example, scanning over theta (test 4), theta and azimuth (test 5), or momentum (tests 7 and 8). Note that optics tests are special tests that will be described below.
drich-dev provides an event display program. Run event_display for a usage guide.
Draw all of the events in one:
event_display d s out/sim.edm4hep.rootView the image in out/ev/.
You may also draw one event at a time (see the usage guide)
event_display d s out/sim.edm4hep.root n 0 0View the images in out/ev/.
Each green box is a single SiPM, and each histogram bin is a single SiPM pixel (8x8 pixels per SiPM). If you want to zoom in, use interactive mode by changing n to i, which will keep the TCanvas open and allow you to zoom in. For example, here is a closeup of the gas ring from a single event, by running
event_display d s out/sim.edm4hep.root i 0