<< back to HepSim manual

HepSim software is deployed using a Singularity/Docker that enables HepSim users to have a full control of their simulation environment. The container runs using the Singularity program (version 2.3.1 and above) and Docker.

Download the singularity image file from here: centos7hepsim.img (about 8 GB). HepSim software environment can be setup from this image as:

wget http://atlaswww.hep.anl.gov/hepsim/soft/centos7hepsim.img # get singularity image
singularity  exec centos7hepsim.img  bash -l                   # setup HepSim software

After the last line, the HepSim environment software should be ready. The software will be located in the directory given by the environmental variable HEPSIM (/opt/hepsim/) For example, type “slic -h”. It shows the available commands for Geant4 full simulations.

If you are using Docker, you can pull the docker image as

docker pull chekanov/centos7hepsim

The HepSim image is based on a minimalistic version CentOS7 x64 with the basic C++ development environments. It includes:

• basic editors, vi, vim, gvim, nano, pico
• X11 development libraries
• gcc4.92, boost, python3.5, clhep and other libraries taken from OpenScienceGrid
• FPadSim package with Geant4 10.3p2, SLIC 5, LCIM 4, Java JDK8, LCIO, ant, maven, etc.
• Jas4pp analysis environment and all hs-tools commands
• C++ ProMC package
• ROOT analysis environment (check ROOTSYS variable)
• Pythia8 with pre-built ProMC output (check PYTHIA8 and PROMC variables)
• Delphes 3.4 fast simulation of detector response (check DELPHES_DIR variable)
• Fastjet 3.3 package (check FASTJET variable)
• HEPMC package (check HEPMC variable)
• LHAPDF PDF library with a few PDF sets (check “ls $LHAPDF6/share/LHAPDF” available PDF)
• promc2lcio and promc2stdhep converters

Note that we do not use the native gcc 4.85 from CentOS7 to make this container compatible with OSG. Type “env” to check the settings. You can see the installed packages as:

singularity exec centos7hepsim.img ls /opt/hepsim/

delphes        fastjet3.3.0  hepmc   lhapdf			promc	    root
delphes-3.4.1  fpadsim	     HEPMC   lhapdf6			generators  root_v6.10.02
fastjet        fpadsim-1.4   jas4pp  oasis.opensciencegrid.org	

Section dev_fpadsim explains how to use this image to create full simulations using detector tags.

One can setup a recent Jas4pp (with hs-tools) as

singularity exec centos7hepsim.img  bash -l
source /opt/jas4pp.sh

and then type “jaspp”. Please forward X11 to see the GUI. All other HepSim commands, such as “hs-ls”, “hs-run” should be available.

To setup simulation and reconstruction software from HepSim, you can use this commend:

singularity exec centos7hepsim.img  bash -l
source /opt/hepsim.sh

The docker container has a few basic tests that checks that everything works as expected. These are:

• Creating Pythia8 events with ProMC and ROOT output
• Creating Delphes fast simulations using external ProMC file
• Creating LCIO files with full simulation using FPadSim

Since many libraries are set from the container, make sure that ROOT is not installed on the host computer. Type “type root” to check the installation. This command should show an empty line.

Here is the description with how to make HepSim tests. First, run these lines that setup the HepSim environment and copy the “tests” directory to the host computer.

singularity exec centos7hepsim.img  bash -l
cp -rf /opt/hepsim/tests .

Here is the example of tests:

Pythia8 inside the Docker image is located in the directory /opt/hepsim/generators. Let's create ProMC files using the Pythia8 generator:

cd tests/pythia8
./TEST.sh

This code compiles a Pythia8 program with ProMC output. You will see several ProMC files inside the directory “out”. The input for Pythia is given by the control card inside the directory “cards”. To recompile the Pythia8 program, type “make”.

Now let us make ROOT files with Delphes fast simulations. This example downloads a ProMC file and creates ROOT file:

cd tests/rfast103
./TEST.sh

To reproduce HepSim fast simulations, you will need “tag files that include Delphes description files. Read more about this in Section HepSim tags.

Now let us make LCIO file with full (Geant4) simulation using included single-particle gun and FPadSim software that includes the full chain ProMC-Slic-LCSIM-PandoraPFA”.

cd tests/rfull102
./TEST.sh

This example uses the input file “pgun_pi10gev_001.promc” with 10 GeV single pions, converts to LCIO, and than creates fully simulated and reconstructed files inside “output”. The final file is output/pgun_pi10gev_001_pandora.slcio with all tracking and PFO information. The detector itself is located inside “sidcc3/compact.xml”.

If you make modifications inside “sidcc3/compact.xml”, you will need to convert this file to other formats to run “TEST.sh”. To do this, run

cd tests/rfull102
./A_RUN_GEOMETRY

More about the full simulations can be found in Sect. Full simulations with FPadSim. Note that, in addition to the singularity container, you need a “tag” file with the detector description. Read more about this in Section HepSim tags.

The singularity centos7hepsim.img image is created using CentOS7 using singularity version 2.3.1. Look inside this container as:

sudo singularity shell --contain --writable centos7hepsim.img

and check the directory “/opt/”. It includes the script “hepsim.sh” which setups the HepSim software environment.

Here are a few useful commands to work with this image:

sudo singularity shell --contain --writable centos7hepsim.img # open to make changes
singularity expand centos7hepsim.img                          # expand the image +750 MB
singularity copy   centos7hepsim.img  -pr test  /opt/hepsim/  # copy "test" from host computer

You can make the changes in this containers to fit your needs.

You can setup the HepSim environment on OSG-grid using this command:

singularity  exec /cvmfs/singularity.opensciencegrid.org/chekanov/centos7hepsim:latest bash -l

Here is the description how to use singularity with condor jobs on OSG Singularity on OSG

The previous CentOS7 image is incompatible with older f77-based Monte Carlo generators. You can run Fortran Monte Carlo programs (LEPTO, LEPTO/Ariadne, Aroma, Epjpsi, Pythia6) using the slc6hepsim.img singularity image. This image is based on Scientific-Linux 6.8 with the native gcc4.4 with f77 compatibility libraries. The image includes CERNLIB, LHAPDF5.8, HEPMC, CLHEP and other older libraries. All Monte Carlo models are interfaced with ProMC IO for compact output of events.

wget http://atlaswww.hep.anl.gov/hepsim/soft/slc6hepsim.img # get singularity image
singularity exec slc6hepsim.img  bash -l                    # setup f77 software

Or, if you use Docker:

docker pull chekanov/slc6hepsim

Monte Carlo generators are located inside the directory /opt/generators/ directory, which can be setup using /opt/setup.sh script. The same script setups the required packaged from /opt/share/sl6 directory.

David Blyth created a lighter version of FPadSim image for EIC work described in Sec. Singularity image for EIC. It is based on Arch Linux, and does not contain the usual Linux environment included inside centos7hepsim image.

— Sergei Chekanov 2017/09/24 17:49