Running EIC Simulations

EIC Software

The main EIC simulation software website can be found at https://eic.github.io/ and some information on the EIC Software Users Group can be found at http://www.eicug.org/web/content/eic-software. There is also an excellent Quick start guide that is highly recommended, and a series of training videos are avilable on the EIC User Group's YouTube channel.

For electron-deuteron scattering, the two most important pieces of software are ESCalate, which allows you to smear simulations into detectors and then view and analyze it, and BeAGLE, which is a Pythia-based Monte Carlo that is currently the only one that works with deuteron beams for the EIC.

ESCalate

To get started with ESCalate, it is highly recommended to follow the instructions on the Quick start guide. However, there are a few important things to know:

1. Install Docker
2. Run the following to get a local copy of the software. This will take a while, and after hitting enter is a good time to make a nice cup of coffee.
   • docker pull electronioncollider/escalate
3. The -rm part of the running command on the Quick Start guide will clear all changes made in the container! To avoid this, and to connect your docker container to a local folder outside of the container as an external back-up, start docker using the following (Make sure to put quotes around your directory if any of the folder names contain spaces):
   • docker run -it -p 8888:8888 -v /specific/external/directory/:/home/eicuser/epw/share electronioncollider/escalate

   • Note: I tend to put the above into a simple executable file named something like goEscalate to not have to remember that whole command

4. Now you should be able to access the Jupyter notebook by opening a browser and going to
   • http://127.0.0.1:8888/
5. Once you can access the Jupyter notebook, it would be a good time to check out the first hour of this training video to get familiar with how the software is set up and how to use it.

Some useful tips:

• Clicking any of the large icons on the far-left will shrink/extend the left menu
• You can access the container terminal by hitting the "+" on the upper-left above your current folder and then selecting "Terminal" under "Other" on the bottom
• If plots seem like they're running but instead of showing a plot you see a large blank space where a plot should be, that's an indication that plotly is not set up correctly. This can be fixed by installing jupyterlab-plotly from the terminal (if you try to do it from the JupyterLab Extensions menu, you will likely run into a communication error). You can do this by opening the terminal as described above and entering the following command:

• sudo jupyter labextension install jupyterlab-plotly
• If that didn't seem to fix the problem, try the following:

• Close and reopen your browser
• Restart the kernal using the circular arrow button on the top of the page

• I ran into this problem starting in 02_full_simulation/2-02_output_analysis.ipynb and the above steps fixed it

BeAGLE

BeAGLE is currently the best electron-deuteron scattering generator for the EIC. In order to run BeAGLE, currently that can be done on the JLab ifarm computers. To set it up, do the following (Summarized from the BeAGLE Wiki):

1. Create a directory where you want to store BeAGLE input and output files and name it something like beagle-user
2. Input the following two lines and add them to your ~/.cshrc:
   • source /u/group/ldgeom/PACKAGES/BeAGLE/setup_BeAGLE
   • source /u/group/ldgeom/PACKAGES/setup.csh
3. Copy the following into your beagle-user folder:
   • cp $BEAGLESYS/nuclear.bin /path/to/beagle-user/.
4. At this point, BeAGLE should be able to run and you can test this by using:
   • $BEAGLESYS/BeAGLE
5. In your beagle-user folder, create the following directories:
   • mkdir inputFiles
   • mkdir outForPythiaMode
   • Important note: Currently, your output file needs to be named outForPythiaMode otherwise it won't work. You can change your inputFiles folder name to whatever you want.
6. To get started, there are example files in $BEAGLESYS/Examples you can use and then use the information in the BeAGLE Wiki to modify accordingly. To use them:
   • cp $BEAGLESYS/Example/eD* /path/to/beagle-user/inputFiles/.
   • cp $BEAGLESYS/Example/eA* /path/to/beagle-user/.
7. Now you're ready to run BeAGLE! You can do this by:
   • $BEAGLESYS/BeAGLE < inputFiles/input.inp | tee log.txt
8. For the example mentioned above, you can run it using:
   • $BEAGLESYS/BeAGLE < inputFiles/eD_18x135_Q2_1_10_y_0.01_0.95_test40k_Shd1_tau7_kt=ptfrag=0.32_shdfac=1.32.Jpsidiffnodecay.highpf.inp | tee log_1.txt
9. Once BeAGLE finishes, you can take the output *.txt file in OutForPythiaMode and copy it into your Docker container to run the ESCalate detector smearing code for viewing/analyzing.