FAQ

Welcome to the Frequently Asked Questions page! Please use the Helpdesk on Mattermost for urgent correspondence.

Submit new questions and comments by email: emailicon

Q: How can we browse the simulation output from a specific campaign and locate certain output files?

A: Visit the epicprod website to view the list of avaiable campaigns. Pick a campaign that you want to view in detail. For example: 25.01.1. Here, you will find the output directories listed in a nested tree structure. The directory nomenclature usually follows the pattern:

<base directory>/<campaign tag>/<detector config>/<physics processes>/<generator release tag if available>/<electron momentum>x<proton momentum>/<q2 range>/

The preferred method to list the files in a directory is to use the xrdfs interface within eic-shell container. For example:

    xrdfs root://dtn-eic.jlab.org   
    ls /volatile/eic/EPIC/RECO/25.01.1/epic_craterlake/DIS/NC/18x275/minQ2=1000

See more details here and in the resources section under Production Files Access.

Q: What input datasets are used in a particular production campaign and where can I find them?

A: The directory structure of the input datasets mimic the directory structure of the output files from <physics processes> onwards. Consider, the output files under root://dtn-eic.jlab.org//volatile/eic/EPIC/RECO/25.01.1/epic_craterlake/DIS/NC/10x100/minQ2=1. The corresponding input datasets can be found in the following manner:

xrdfs root://dtn-eic.jlab.org
ls /volatile/eic/EPIC/EVGEN/DIS/NC/10x100/minQ2=1

Q: What is the procedure to introduce a new dataset into a production campaign or replace an existing one?

A: Follow the input dataset creation guidelines listed in the epic-prod website.

Q: How can we load files into ROOT directly from xrootd?

A: Enter the full file path including server address using root TFile::Open. For example:

    auto f = TFile::Open("root://dtn-eic.jlab.org//volatile/eic/EPIC/RECO/25.01.1/epic_craterlake/DIS/NC/18x275/minQ2=1000/pythia8NCDIS_18x275_minQ2=1000_beamEffects_xAngle=-0.025_hiDiv_1.0000.eicrecon.tree.edm4eic.root")

See more details here.

Q: How can we copy files from xrootd?

A: Use xrdcp with full path and local destination directory. For example:

xrdcp root://dtn-eic.jlab.org//volatile/eic/EPIC/RECO/25.01.1/epic_craterlake/DIS/NC/18x275/minQ2=1000/pythia8NCDIS_18x275_minQ2=1000_beamEffects_xAngle=-0.025_hiDiv_1.0000.eicrecon.tree.edm4eic.root <local destination>

Q: What is included in the campaign, and what are the major changes compared to before?

A: We version track the epic and eicrecon repositories and the new features introduced in a campaign are tracked in the release notes. For example: epic-25.01.1 and eicrecon-1.21.0 represent the software changes introduced in January, 2025 campaign. Version tracking is also enforced for input datasets.

Q: How can we effectively use the information stored in EICRecon rootfile outputs, such as matching reconstructed particles to their MC particles?

A: To an extent, this is covered in the dRICH tutorials, starting at session 3 and partly covered in existing recorded tutorials. TODO: Probably needs to be supplemented with example codes.

Q: How can we apply beam effects, including adjusting the ion beam when using a particle gun?

A: Beam effects are handled by the afterburner, which expects HepMC3 input. They cannot be simply turned on in just the npsim particle gun.

Q: How do we check and change beam magnet settings for both simulation and reconstruction?

A: TODO:Changing magnet configuration in reconstruction makes little sense. Checking and changing it for simulation should be answered by the prod group.

Q: What is the best practice for analyzing EICrecon output, especially regarding hadron PID likelihoods?

A: TODO: Needs an updated analysis tutorial. I don’t believe at this point we have a simple unified PID likelihood approach.

Q: How can we develop a benchmark for an analysis code to pass on to the validation software team?

A: TODO: We originally planned a dedicated “Tutorial: Writing physics benchmarks that run automatically and reproducibly” - this needs to be revisited. Otherwise, Dmitry K, Wouter, Sylvester may be able to write up something short. This is a good FAQ candidate really, if we can get this answered.

Q: How can we access various (SI)DIS variables through different reconstruction methods?

A: TODO: Things like InclusiveKinematicsDA.cc are part of EicRecon, but I don’t know how to use it. I don’t believe it’s calculated by default during campaigns, so one would still need an analysis level version. Would be good example analysis code, and I’m sure it exists in many forms on various people’s laptops.

Q: How do we match tracks and clusters from the calorimeters?

Q: How can we access hadron and electron PID data?

A: You can access a sampled hypothesis via PDG field of the ReconstructedParticle. The particleIDs relation will contain all of the available hypotheses (for expert use).

Q: How do we navigate from reconstructed to truth information?

A: Needs a refreshed tutorial; needs example code

Q: Is there an organized repository or wiki that guides newcomers to the right tutorials and slides?

A: Yes, but the dRICH one is closest, plus the tutorials indico. TODO: Should be combined and front and center of the landing page.

Q: Are there quick starter-code examples (Analyzer macros) for accessing branch information and creating physics plots?

A: TODO: Yes, but not well organized and more is better.

Q: Can you provide an example of analyzing EICrecon data using basic methods?

A: https://indico.bnl.gov/event/18373/ has some, so does the dRICH tutorial. TODO: Needs more example code.

Q: How do I disable a certain particle decay during the detector simulation?

A: You can disable/modify a decay by changing its branching ratio. Create a ddsim/npsim steering file with contents like

from DDSim.DD4hepSimulation import DD4hepSimulation
SIM = DD4hepSimulation()
SIM.ui.commandsConfigure = [
    "/particle/select lambda",
    # dump before
    "/particle/property/decay/dump",
    # proton pi-
    "/particle/property/decay/select 0",
    "/particle/property/decay/br 0",
    # neutron pi0
    "/particle/property/decay/select 1",
    "/particle/property/decay/br 1",
    # dump after
    "/particle/property/decay/dump",
]
SIM.ui.commandsInitialize = []
SIM.ui.commandsPostRun = []
SIM.ui.commandsPreRun = []
SIM.ui.commandsTerminate = []

and pass it via --macroFile option in your ddsim/npsim invocation.

Q: How do I obtain the generated cross-section for a simulated dataset?

Information of generated events can be found in the .hepmc3.tree.root files in /work/eic/EPIC/EVGEN. Here is an example on how to print out the cross section stored in the ROOT tree:

root -l -b -q root://dtn-eic.jlab.org//volatile/eic/EPIC/EVGEN/DIS/NC/18x275/minQ2=1/pythia8NCDIS_18x275_minQ2=1_beamEffects_xAngle=-0.025_hiDiv_1.hepmc3.tree.root -e 'hepmc3_tree->Scan("hepmc3_event.attribute_string", "hepmc3_event.attribute_id==0 && hepmc3_event.attribute_name ==\"GenCrossSection\"", "colsize=30", 1, hepmc3_tree->GetEntries()-1)'

Or:

TFile* file = TFile::Open("root://dtn-eic.jlab.org//volatile/eic/EPIC/EVGEN/DIS/NC/18x275/minQ2=1/pythia8NCDIS_18x275_minQ2=1_beamEffects_xAngle=-0.025_hiDiv_1.hepmc3.tree.root");

TTreeReader tree_reader("hepmc3_tree", file);
tree->Scan("hepmc3_event.attribute_string", "hepmc3_event.attribute_id==0 && hepmc3_event.attribute_name ==\"GenCrossSection\"", "colsize=30", 1, tree->GetEntries()-1);

The “1” at the end of the file name indicates that these events are used in /volatile/eic/EPIC/RECO/25.01.1/epic_craterlake/DIS/NC/18x275/minQ2=1/pythia8NCDIS_18x275_minQ2=1_beamEffects_xAngle=-0.025_hiDiv_1.xxxx.hepmc3.tree.root