EIC AI Background

Full-simulation pipeline, background mixing and CSV datasets for machine learning with the ePIC detector at the Electron-Ion Collider.

Scope

The project produces background-mixed ePIC simulations and converts them to flat CSV for ML training and detector-occupancy studies. It has three parts:

1. Simulation pipeline — JeffersonLab/msf-simulation-pipeline. Python scripts that generate SLURM job arrays for each stage of the ePIC chain (afterburner abconv → optional signal + background merge → npsim → EICrecon → CSV) on the JLab farm. Stages from the afterburner onward read dataset cards: YAML file lists made from a farm directory or, for official campaigns, from Rucio. One self-contained YAML config per campaign sets inputs, outputs, container image and converter roles.
2. CSV conversion — sroai/eic2ai, a single-pass C++ program (submodule of the pipeline). It reads each input once — the .edm4eic.root file and, for roles that need simulation hits, its paired .edm4hep.root — and writes every requested role (tracker hits, calorimeter hits, reco particles, DIS kinematics, …) as <stem>.<role>.csv.zip. It supersedes the per-role ROOT macros in the pipeline's csv_convert/: same rows, unified column names. 40_csv_convert.py runs either one; a config selects eic2ai with converter: eic2ai, and the macros stay the default otherwise.
3. Analyses — earlier Python analyses on the CSVs, kept in the archived eic/ai-epic-background repository.

Pipeline at a glance

generator HepMC
  → abconv (afterburner)        *.hepmc3.tree.root       stage 10
  → SignalBackgroundMerger      *.bg.hepmc3.tree.root    stage 11 (background campaigns)
  → npsim                       *.edm4hep.root           stage 20 / 22
  → EICrecon                    *.edm4eic.root           stage 30
  → eic2ai or csv_convert       <stem>.<role>.csv(.zip)  40_csv_convert.py

Stage 11 mixes each signal event with the official ePIC background cocktails (synchrotron radiation; electron-beam bremsstrahlung, Coulomb and Touschek; proton beam gas) into a 2 µs timeframe with the SignalBackgroundMerger binary from eic/HEPMC_Merger. Its successor, eic/TimeframeBuilder, is being prepared for ePIC production; the pipeline has not switched. Details on the Backgrounds page.

XRootD needs a 5.9+ client with TLS

JLab XRootD (root://dtn2304.jlab.org:8443) accepts only XRootD clients 5.9 and newer, and the login runs over TLS, so the client needs a CA directory. Check with xrdcp --version. eic_xl 26.06-stable and later work as shipped (5.9.1+, X509_CERT_DIR=/opt/local/certificates; 26.10.0-stable: 5.9.2). Both problems show as Login failed: Got invalid login response: an older client, or a 5.9 client without CA certificates (XRD_LOGLEVEL=Debug then prints Failed to initialize TLS context: CA directory does not exist). For the second, set export X509_CERT_DIR=/etc/ssl/certs. The old host dtn-eic.jlab.org is retired.

Pages

• Full-Sim Pipeline — stages, job creator and campaign configs.
• Backgrounds — the merge step, cocktails and generator-status offsets.
• CSV Convert — eic2ai and the ROOT macros, roles and how to run them.
• Data Format — column layout of every CSV role.
• Available Datasets — background-mixed datasets on Rucio.
• AI / ML Datasets — loading the CSVs in pandas, numpy and PyTorch.

Repositories

What	Repository
Simulation pipeline, campaign configs, background cocktails, ROOT macros	JeffersonLab/msf-simulation-pipeline
eic2ai converter (submodule of the pipeline)	sroai/eic2ai
This website	sroai/sroai.github.io
Earlier analyses and documentation (archived)	eic/ai-epic-background