All in One View

Last updated on 2026-07-10 | Edit this page

Estimated time: 5 minutes

Overview

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 using the answer submission form. 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 page will also include links to some tutorials and resources you might find helpful.

Each page has an embedded answer submission form. You will get the clues for the final task from this form. Make sure you make a note of the clues you get for each task!

Callout

Comment:

If you get stuck with any task, feel free to ask or check in on the Scavenger Hunt Mattermost channel.

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!

Content from Tasks 1-3

Last updated on 2026-07-12 | Edit this page

Estimated time: 180 minutes

Overview

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 in the Setting Up Your EIC Environment tutorial.

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 on the eic_xl container registry. You can check your current version from eic-shell:

BASH

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 on the ePIC getting-started guide on how to join mattermost if you’re not there already. Either browse and join the channel or follow this link to the scavenger-hunt Mattermost channel.

Challenge

Exercise: Switch container version

Switch to the container version specified in the header of the scavenger-hunt mattermost channel.
To begin, download the install.sh script:

BASH

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.

BASH

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. Use them in the answer checker at the bottom of this page!

Show me the solution

After installing and launching the specified container, eic-info reports the version you selected and root --version prints 6.XX.YY. Record the XX and YY numbers for the answer checker.

Callout

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 the File Access 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-2)/ 10 in the year 2026. This will follow the format 26.MM.1 (where if MM<10, you will put a 0 in front of the number).

Challenge

Exercise: Copy a campaign file

Inserting the number you got for MM:

Download a file with the DID epic:/RECO/26.MM.1/epic_craterlake/EXCLUSIVE/DVCS_ABCONV/EpIC_v1.1.6-1.2/10x100/q2_1_100/EpIC_1.1.6-1.2_DVCS_BH_10x100_q2_1_100_minus_abconv_run0.0MM1.eicrecon.edm4eic.root (replacing MM with the number you obtained above)
- You can check you got the right DID using the answer checker at the bottom of the page.
How many entries are within the branch elements of VertexBarrelHits for this file?
Enter your answer into the checker to get the next clue!

Show me the solution

Once the file is copied locally you can open it in ROOT and inspect the VertexBarrelHits branch (for example with events->Draw("VertexBarrelHits.eDep") another collection within the branch). Enter the number of entries into the answer checker to receive the clue.

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, we will examine the reconstructed output differences from BeAGLE1.03.02-1.0 and BeAGLE1.03.02-1.3. Below replace NN with the solution to NN = YY + 2*MM - 1.

Challenge

Exercise: Compare two generator versions

Inserting the numbers you got for MM and NN:

Grab files from the following DIDs: epic:/RECO/26.MM.1/epic_craterlake/DIS/BeAGLE1.03.02-1.0/eH2/10x130/q2_1to1000/BeAGLE1.03.02-1.0_DIS_eH2_10x130_q2_1to1000_ab.00NN.eicrecon.edm4eic.root and epic:/RECO/26.MM.1/epic_craterlake/DIS/BeAGLE1.03.02-1.3/eH2/en/10x130/q2_1to1000/BeAGLE1.03.02-1.3_DIS_eH2_en_10x130_q2_1to1000_ab_run001.00NN.eicrecon.edm4eic.root
- You can check you got the right DIDs using the answer checker at the bottom of the page.
Check the mean of the GeneratedJets.energy in each file.
From the mean values of the GeneratedJets.energy histograms (no cuts). Select the correct set of two values in the answer checker to get the clue from task 3!

Show me the solution

Open each file in ROOT and histogram GeneratedJets.energy with no cuts (events->Draw("GeneratedJets.energy")), then read the histogram mean from each. Select the pair of mean values in the answer checker to obtain the task 3 clue.

Answer Checker

Key Points

Find the first three parts of the file name!

Content from Tasks 4-6

Last updated on 2026-07-10 | Edit this page

Estimated time: 180 minutes

Overview

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.

Challenge

Exercise: Compare afterburned and non-afterburned beam electrons

Download
- Non-AB file: xrdcp root://dtn-eic.jlab.org:1094//volatile/eic/sjdkay/Scavenger_Hunt/NonAfterburned_File.hepmc3.tree.root
- AB file: xrdcp root://dtn-eic.jlab.org:1094//volatile/eic/sjdkay/Scavenger_Hunt/Afterburned_File.hepmc3.tree.root
Select the mean value of the x component of the momentum for the beam electrons in these two files in the answer checker below to get your clue from task 4!

Show me the solution

After copying both files, histogram the x-component of the beam-electron momentum (particles.momentum.m_v1) in each file and read off the mean. Select the correct pair of means in the answer checker to receive the task 4 clue.

Callout

Comment:

These are just .hepmc files converted to root trees, not simulation or reconstruction data at this point.
- particles.momentum.m_v1 corresponds to the x-component of the momentum for particles in this file.

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. You might also find the Geometry Development with DD4hep tutorial useful. There are significant differences between the two commands. The output from a simulation using each command can be quite different.

Challenge

Exercise: ddsim vs npsim hit energies

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.
- AB file: /volatile/eic/sjdkay/Scavenger_Hunt/Afterburned_File.hepmc3.tree.root
Check the mean of the hit energies for npsim and ddsim in the barrel hadronic calorimeter (HcalBarrelHits), select which of these values is larger in the answer checker at the bottom of the page to get your clue from task 5.

Show me the solution

Run both simulations over the same 100 events, then histogram HcalBarrelHits.energy from each output and compare the means. Select whichever of ddsim or npsim gives the larger mean hit energy in the answer checker to receive the task 5 clue.

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.

Challenge

Exercise: Vertex Barrel Layer thickness

Using eic-shell version 25.08-stable, find the Vertex Barrel Layer thickness of the Vertex Barrel subsystem in the epic_craterlake.xml config.
Put the value of the thickness into the answer checker below to get your clue for task 6!

Show me the solution

Follow the <include> chain from epic_craterlake.xml into the Vertex Barrel subsystem definition files and read the layer thickness parameter defined there. Enter that value into the answer checker to receive the task 6 clue.

Answer Checker

Key Points

Find the next three parts of the file name!

Content from Tasks 7-8

Last updated on 2026-07-10 | Edit this page

Estimated time: 120 minutes

Overview

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.

Challenge

Exercise: Count ZDC branches

Using the file - epic:/RECO/25.10.2/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 _
- Check how many elements the “ReconstructedFarForwardZDCNeutrals” branch collection has
- Select the corresponding values in the answer checker at the bottom of this page to get your clue for task 7!

Show me the solution

Open the file in ROOT and list the branches (for example events->GetListOfBranches()->GetEntries()). Count those whose name contains ZDC and does not start with _, then check the element count of the ReconstructedFarForwardZDCNeutrals collection. Select the matching values in the answer checker to receive the task 7 clue.

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.

Challenge

Exercise: Reconstructed stable final-state particles

Using the file - epic:/RECO/25.10.2/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
- Enter your corresponding values into the answer checker at the bottom of the page to get your clue for task 8!

Show me the solution

Loop over MCParticles, keeping stable final-state electrons and photons, and use the ReconstructedParticleAssociations collection to keep only those with an associated reconstructed particle. Enter the two counts (electrons and photons) into the answer checker to receive the task 8 clue.

Callout

Comment:

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

Answer Checker

Key Points

Find the final two parts of the file name!

Content from Final Challenge

Last updated on 2026-07-12 | Edit this page

Estimated time: 120 minutes

Overview

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!

epic:/RECO/XX.YY.Z/epic_craterlake/DIS/NC/IIxJJ/minQ2=KK/pythia8NCDIS_IIxJJ_minQ2=KK_beamEffects_xAngle=-0.025_hiDiv_A.BBBB.eicrecon.edm4eic.root
- XX - Your clue from task 1
- YY - Your clue from task 2
- Z - Your clue from task 3
- II - Your clue from task 4
- JJ - Your clue from task 5
- KK - Your clue from task 6
- A - Your clue from task 7
- BBBB - Your clue from task 8

Callout

Hint:

Don’t forget, the clues come from the answer checker on each task page!

DID Check

If you want to double check you got the correct DID and your plugged in the task clues correctly, use the checker form below:

Final Challenge

With the DID you’ve constructed from your clues, download or stream this file and the next 9 files in this set such that you have ten files total. Simply increment the BBBB value to get the next in the sequence.

From these ten files, identify using the ‘MCParticles’ and ‘ReconstructedParticles’ collection along with their associations:

All of the electrons that reconstruct in the central detector
All of the photons that reconstruct in the central detector

For each set of particles, produce a 2D colour plot of the true (MC) pseudorapidity (eta) vs |P|. Set the colour pallete for your plots using the number of MC particles in the 237th event. E.g. gStyle->SetPalette(#MC_Parts);. If you aren’t using ROOT, check the colour palette this corresponds to and set a similar palette.

Upload these as a single pdf or png using the submission link below.

Callout

Hint:

Use the pseudorapidity range of -5 to 5 and |P| range of 0 to 50.
Use bin sizes of 0.1 for pseudorapidity and 0.25 for|P|.

Answer Submission

Submit your final answer using the answer submission form - good luck!

Key Points

Solve the final challenge!