This lesson is being piloted (Beta version)

ePIC User Learning Scavenger Hunt

Introduction

Overview

Teaching: 5 min
Exercises: 0 min
Questions

  • How do I start the scavenger hunt?

Objectives

  • Start the hunt!

Welcome to the ePIC User Learning Scavenger Hunt! This hunt will consist of a series of ePIC software tasks for you to complete. Each task will produce a piece of the filename that you will have to utilise to “solve” the final task. When solved, you will need to input your answer HERE (Link to be added). If you’re correct, you’ll find out and receive a special prize as part of the 2026 Collaboration meeting!

The tasks are split into a few distinct blocks which are detailed below. Each block has a dedicated page and there will be a tool included in each for you to use to check if you’ve got the correct answers. Each page will also include links to some tutorials and resources you might find helpful.

Tasks 1-3 - Getting started on Mattermost, working with eic-shell and accessing files

This series of tasks serves as some setup for future stages, but will also include a few clues and pieces of information we need to find out to solve find the file we need to use for the final task.

Tasks 4-6 - Running Simulations, afterburner and checking geometry

This series of tasks gets you started on simulating ePIC data and understanding the ePIC simulation.

Tasks 7-8 - Looking at Campaign Output, Analysing it

These two tasks will involve analysing simulation campaign data.

Final Task

Once you piece together the filename from the three task blocks, you can then find it and complete the final task. This page will also include a link to the answer submission page.

Key Points

  • Welcome to the ePIC User Learning Scavenger Hunt!

Tasks 1-3

Overview

Teaching: 0 min
Exercises: 180 min
Questions

  • Information and objectives for tasks 1-3

Objectives

  • Find the first three parts of the file name!

Task 1 - eic-shell Versioning

eic-shell contains all of the software we need to do an EIC/ePIC analysis. To get started on this task, and all of the others, you will need eic-shell working on either your local machine, or a computing cluster you can access (e.g. BNL or JLab systems). Instructions on installing eic-shell can be found here.

Typically, you should use the latest version of this container. However, on some occassions you may want to reproduce an earlier analysis or result that used a different version of the software within the container. You can see what versions of eic-shell are available here. You can check your current version from eic-shell:

> eic-info

Your current version is listed at the bottom of this output at the output next to “jug_dev: “. By default, you are likely running the “nightly” release which is the most up-to-date. For this scavenger hunt training activity, we will work from a different, common release.

For this task, you will switch your eic-shell version to the one specified in the channel header of the scavenger-hunt mattermost channel. See the instructions here on how to join mattermost if you’re not there already. Either browse and join the channel or follow this link.

Exercise:

  • Switch to the container version specified in the header of the scavenger-hunt mattermost channel.
  • To begin, download the install.sh script: 
    wget --output-document install.sh https://get.epic-eic.org
./install.sh -v <<version>>
eic-shell

    Running eic-shell should now open the specified version. You can check this by running “eic-info”. Now you can open root to check your root version.

    root --version

    The version output will printed in the format 6.XX.YY. These numbers XX and YY will be used in the next part of the challenge to find your campaign files. To solve task 1, put your two values into the following equation - \(XX - YY + 9\). The solution to this equation is your answer from task 1!

Comment: -If you are using a system with CVFMS enabled, such as the JLab farm, you can also run:

  • ./eic-shell --version <<version>> once eic-shell is installed

Task 2 - Browsing and Copying Campaign Files

Regular simulation campaigns are run on a monthly basis. In these campaigns, physics and background events are passed through the latest version of the ePIC simulation and reconstruction software.

Information on browsing and copying files from simulation campaigns is outlined in this tutorial. Further information on the campaigns can be found on the production working group pages.

From above, you will access the campaign files in MM=XX/4 in the year 2025. This will follow the format 25.MM.0.

Exercise:

  • Download the file /volatile/eic/EPIC/RECO/25.MM.0/epic_craterlake/EXCLUSIVE/UCHANNEL_PI0/18x275/pi0_18x275_uChannel_Q2of0to10_hiDiv.01YY.eicrecon.edm4eic.root (replacing MM and YY with the numbers you obtained above)
  • How many entries are within the branch elements of VertexBarrelHits for this file? Take this number of entries divide it by five, round this value to the nearest integer. This is your answer for task 2!
  • As an equation: \(round(Entries/5)\)
  • Note, if this value is a single digit integer, place a 0 in front of it. E.g. 1 becomes 01.

Task 3 - Differences Between Event Generators

Many event generators exist for a wide range of processes. In some cases, the same process can be simulated using two different versions of the same generator. The output of the two versions can differ. In this task, get an alternative version of the file from Task 2 that was produced using a different event generator.

Exercise:

  • Grab FILE.
  • Check QUANTITY in this file compared to the previous file.
  • The difference between the mean value of QUANTITY from FILE1 and TASK2 FILE is your third clue!

Answer Checker

Once you have your solutions from tasks 1-3, you can check your answers using this link.

Key Points

Tasks 4-6

Overview

Teaching: 0 min
Exercises: 180 min
Questions

  • Information and objectives for tasks 4-6

Objectives

  • Find the next three parts of the file name!

Task 4 - Afterburner vs Non-Afterburner

The “afterburner” is applied to event generator files to apply beam effects to the events in the file. Once processed with the afterburner, these files are then processed through the simulation and reconsturction chain. For this task, we will compare the original, non-afterburned events to the afterburned events.

Exercise:

  • Download
    • Non-AB file - /volatile/eic/sjdkay/Scavenger_Hunt/NonAfterburned_File.hepmc3.tree.root
    • AB file - /volatile/eic/sjdkay/Scavenger_Hunt/Afterburned_File.hepmc3.tree.root
  • Find the difference between the mean value of the x component of the momentum for the beam electrons in these two files.
  • Take the absolute value of this difference, multiply it by \(10^{9}\) and round it to the nearest integer and add 2. This is your clue for task 4.

As a formula: \(round((abs(Diff)*10^{9})) + 2\)

Comment:

  • These are just .hepmc files converted to root trees, not simulation or reconstruction data at this point.

Task 5 - ddsim vs npsim

The simulation of the ePIC detector in eic-shell is via a Geant4 based DD4hep smulation. Information on running the simulation can be found in the Simulations using npsim and geant4 tutorial. In this tutorial, simulations using the ddsim and npsim commands are discussed. There are significant differences between the two commands. Namely that npsim includes siulation of optical photons, the output from a simulation using each command can be quite different.

Exercise:

  • In this task, process 100 events from the afterburned file in task 4 using ddsim and npsim and the “epic_craterlake_10x130.xml” configuration. Use eic-shell version “25.08-stable” as in Task 1.
    • AB file - /volatile/eic/sjdkay/Scavenger_Hunt/Afterburned_File.hepmc3.tree.root
  • Find the ratio between the total hit energies for npsim to ddsim in the barrel hadronic calormiter.
    • “HcalBarrelHits”
  • Round your value for this ratio to the nearest integer and take \(10^{Ratio}\). This value is your clue from task 5.

Again, as a formula:

\(Ratio = \frac{\sum E_{npsim}}{\sum E_{ddsim}}\) \(round(Ratio) \rightarrow 10^{round(Ratio)}\)

Task 6 - Looking at Geometry Files

The detector geometry for the ePIC detector is defined using the DD4he toolkit. Information on the detector geometries can be found in the Geometry Development with DD4hep tutorial. Geometries are defined in .xml files, there is a top level detector geometry .xml file which connects various detector subsystem .xml files and definitions.xml files for these subsystems.

Exercise:

  • Using the latest version of eic-shell and the latest definition of the detector geometry, find the DIMENSION of the DETECTOR subsystem. This is your clue for task 6.

Answer Checker

Once you have your solutions from tasks 4-6, you can check your answers using this link.

Key Points

Tasks 7-8

Overview

Teaching: 0 min
Exercises: 120 min
Questions

  • Information and objectives for tasks 7-8

Objectives

  • Find the final two parts of the file name!

Task 7 - Exploring a Reconstructed Output File

In this task, we will take a closer look at the branches contained within a reconstruction file. You may find lesson 2 of the analysis tutorial to be useful here if you have not looked at analysis files before.

Exercise:

  • Using the file - /volatile/eic/EPIC/RECO/25.08.0/epic_craterlake/EXCLUSIVE/UCHANNEL_PI0/18x275/pi0_18x275_uChannel_Q2of0to10_hiDiv.0104.eicrecon.edm4eic.root, do the following:
  • Check the number of branches this file contains
    • Find the number of branches that contain ZDC within their name, do not include branches that begin with _
    • Find the number of branch elements contained within these branches
  • Divide the number of branch elements by the number of branches, square root this number and round it to the nearest integer. This number to get your clue for task 7.

As a formula - \(round(sqrt(Elements/Branches))\)

Task 8 - Using MC Particles

In this task, we will do a basic analysis of some information contained within a reconstruction file. Namely, we will look at the inforrmation in the MCParticles branch. Accessing the truth information is very important in simulation studes. You may find lesson 3 of the analysis tutorial to be useful here if you have not looked at analysis files before.

Exercise:

  • Using the file - /volatile/eic/EPIC/RECO/25.08.0/epic_craterlake/EXCLUSIVE/UCHANNEL_PI0/18x275/pi0_18x275_uChannel_Q2of0to10_hiDiv.0104.eicrecon.edm4eic.root, the same as Task 7, do the following using the MCParticles branch:
    • Determine the number of stable, final state electrons that have an associated reconstructed particle
    • Determine the number of stable, final state photons that have an associated reconstructed particle
  • Determine multiply the number of electrons and photons you found together to get your answer to task 8.
    • If this product is not a 4 digit integer, add 0’s in front to make it a 4 digit number. E.g. 14 would be 0014.

Comment:

  • You will need to utilise the ReconstructedParticleAssociations collection to find whether your MC particles have an associated reconstructed particle or not.

Answer Checker

Once you have your solutions from tasks 7-8, you can check your answers using this link.

Key Points

Final Challenge

Overview

Teaching: 0 min
Exercises: 120 min
Questions

  • Information on the final challenge

Objectives

  • Solve the final challenge!

Download your file

Using the clues from tasks 1-8, download your file. Insert your solutions into the file path below to construct the required path and grab this file!

Hint:

  • Don’t forget, each task page has an answer checker you can use to see if your solutions are correct.

Filepath Check

If you want to double check you got the correct file and your plugged in the task clues correctly, use this CHECKER LINK.

Final Challenge

Final challenge TBC. Will be some simple analysis of the required file to download. Produce a plot/quantity and get a number from this. Input the number as an answer - maybe even a specific plot?

Answer Submission

Link to answer submission form.

Key Points