All in One View

Content from Set up the Jupyter Notebook Environment

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

Estimated time: 10 minutes

Overview

Questions

  • How to access simulation campaign output with python?

Objectives

  • Set up interactive python platform with Jupyter-notebook.

Set up Jupyter-notebook

  • on Google Colab (recommended):
    • copy the example Colab notebook to your own google drive.
    • run the first cell under “setup” to install uproot and xrootd (takes ~10 minutes)
  • on your local environment:
    • if not yet, install uproot and xrootd with your local package manager, or, in jupyter-notebook, run

BASH 

!pip install xrootd
!pip install uproot
!pip install fsspec-xrootd
!pip install particle ## optional
Callout

Note: we will be using other standard python packages such as numpy and pandas, which are pre-installed on Colab.

Key Points
  • install uproot and xrootd

Content from Introduction to the DD4hep simulation

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

Estimated time: 40 minutes

Overview

Questions

  • Understand the inputs and outputs of the DD4hep simulation

Objectives

  • Event generation
  • Detector description
  • MCParticles and detector hits
  • Simulation campaign files

DD4hep simulation

This Geant4-based simulation package propagates particles through magnetic field and materials. Particles and detector hits for each event are saved in the output rootfiles.

Input 1: Event generation

The collision event at ePIC, including the beam particles, vertices, and outgoing particles, are typically generated with a dedicated event generator, e.g. PYTHIA8 for specific physics channels. The outputs are provided to the DD4hep simulation in HEPMC3 format.

One can also use the DD4hep’s particle gun to generate outgoing particles with given vertex and distribution, see the Simulations Using npsim and Geant4 tutorial on ddsim.

Input 2: Detector description

The ePIC detector description in DD4hep is maintained in the eic/epic repository on GitHub. On the bottom of each sub-detector compact file under epic/compact, the readout block specifies how the detector hits are saved in the output rootfile.

Below is an example from epic/compact/tracking/vertex_barrel.xml:

XML 

<readouts>
  <readout name="VertexBarrelHits">
    <segmentation type="CartesianGridXY" grid_size_x="0.020*mm" grid_size_y="0.020*mm" />
    <id>system:8,layer:4,module:12,sensor:2,x:32:-16,y:-16</id>
  </readout>
</readouts>

All hits from this silicon vertex barrel detector, including their position, energy deposit, time, will be stored under the branch VertexBarrelHits in output. Each detector hit also comes with an assigned 64-bit cell ID, with the last 32 bits from right to left representing the hit location in a 0.020 x 0.020 mm mesh grid. This segmentation often represents the detector granularity (in this case, the silicon pixel sensor size) that will be used later for hit digitization.

Output

The event tree in the simulation output contains

  • MCParticles: records the truth info of primary and secondary particles
  • Individual branches for signals from various sub-detector systems e.g. VertexBarrelHits
Challenge

Exercise 1.1: access simulation campaign rootfiles

The simulation campaign dataset documentation documents the available datasets and version information.

  • Browse the directory

    For the stand-alone xrdfs command, see the previous Analysis tutorial. Here we will proceed with the python interface:

    PYTHON 

    from XRootD import client
# Create XRootD client
eic_server = 'root://dtn-eic.jlab.org/'
fs = client.FileSystem(eic_server)
# List directory contents
fpath      = '/volatile/eic/EPIC/RECO/26.02.0/epic_craterlake/SINGLE/e-/10GeV/130to177deg/'
status, files = fs.dirlist(fpath)
# Print files
if status.ok:
    print(files.size)
    for entry in files:
        print(entry.name)
else:
    print(f"Error: {status.message}")

  • Open a simulation campaign file

    PYTHON 

    fname      = eic_server+fpath+'e-_10GeV_130to177deg.0000.eicrecon.edm4eic.root'
tree_name  = "events"
# tree_name = "podio_metadata"
tree       = ur.open(fname)[tree_name]
print(f"Read {fname}:{tree_name}. \n {tree.num_entries} events in total")

fs.dirlist returns the list of files available in the campaign directory, and ur.open(...)[tree_name] opens the events tree and reports the number of entries. If the directory listing fails, check that the campaign version in fpath still exists on the server (campaigns roll over and older versions are removed).

Challenge

Exercise 1.2: inspect available branches in a rootfile

  • use tree.keys(filter_name="*",recursive=False) to display all branches
  • extract a given branch to dataframe

PYTHON 

bname = "MCParticles"
df    = tree[bname].array(library="ak")
df    = ak.to_dataframe(df)
print(df)

tree.keys(...) lists the top-level branches (e.g. MCParticles and the per-detector hit collections). Reading MCParticles into an awkward array and converting to a dataframe gives one row per particle, with columns such as MCParticles.PDG, MCParticles.generatorStatus, and the momentum components.

Challenge

Exercise 1.3: extract momentum distribution of primary electrons

PYTHON 

# select electrons
from particle import Particle
part   = Particle.from_name("e-")
pdg_id = part.pdgid.abspid
condition1  = df["MCParticles.PDG"]==pdg_id
# select primary particles
condition2  = df["MCParticles.generatorStatus"]==1
# extract momentum and plot
# all electrons
df_new = df[condition1]
mom    = np.sqrt(df_new["MCParticles.momentum.x"]**2+df_new["MCParticles.momentum.y"]**2+df_new["MCParticles.momentum.z"]**2)
bins   = np.arange(0,20)
_      = plt.hist(mom,bins=bins,alpha=0.5)
# primary electrons
df_new = df[condition1&condition2]
mom    = np.sqrt(df_new["MCParticles.momentum.x"]**2+df_new["MCParticles.momentum.y"]**2+df_new["MCParticles.momentum.z"]**2)
_      = plt.hist(mom,bins=bins,histtype="step", color='r')

The first histogram (filled) shows the momentum of all electrons, including secondaries; the second (red outline), obtained by additionally requiring generatorStatus==1, shows only the primary electrons. The primary distribution is a subset of the all-electron distribution, peaked near the generated beam/scattered-electron momentum.

Key Points
  • event generator –dd4hep–> simulated hits and particles

Content from Reconstruction workflow

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

Estimated time: 40 minutes

Overview

Questions

  • Understand the EICrecon workflow

Objectives

  • Hit digitization
  • data model
  • Reconstruction algorithms

Reconstruction workflow

The ePIC reconstruction framework EICrecon is maintained in the eic/eicrecon repository on GitHub. It processes simulated hits from various detectors to reconstruct trajectory, PID, etc, and eventually reconstruct the simulated particle and physics observables at the vertex. In this section, we will use track reconstruction as an example. Please refer to the Lehigh reconstruction workfest presentations for the reconstruction workflow of other systems.

Each reconstruction step involves 3 components:

  • the algorithm,
  • the JOmniFactory where algorithm and data type are declared,
  • the factory generator to execute the algorithm.

Digitization

All simulated detector hits are digitized to reflect certain detector specs e.g. spatial and time resolution, and energy threshold. For example, the VertexBarrelHits from simulation are digitized through the SiliconTrackerDigi factory in EICrecon/src/detectors/BVTX/BVTX.cc:

CPP 

    // Digitization
  app->Add(new JOmniFactoryGeneratorT<SiliconTrackerDigi_factory>(
      "SiBarrelVertexRawHits", // factory name
      {
        "VertexBarrelHits"  // input
      },
      {
        "SiBarrelVertexRawHits",  // outputs
        "SiBarrelVertexRawHitAssociations"
      },
      {
          .threshold = 0.54 * dd4hep::keV, // configurations
      },
      app
  ));

The actual algorithm locates at EICrecon/src/algorithms/digi/SiliconTrackerDigi.cc, with its input and output specified in SiliconTrackerDigi_factory.h:

CPP 

  class SiliconTrackerDigi_factory : public JOmniFactory<SiliconTrackerDigi_factory, SiliconTrackerDigiConfig> {

  public:
      using AlgoT = eicrecon::SiliconTrackerDigi;
  private:
      std::unique_ptr<AlgoT> m_algo;

      PodioInput<edm4hep::SimTrackerHit> m_sim_hits_input {this};

      PodioOutput<edm4eic::RawTrackerHit> m_raw_hits_output {this};
      PodioOutput<edm4eic::MCRecoTrackerHitAssociation> m_assoc_output {this};

      ParameterRef<double> m_threshold {this, "threshold", config().threshold};
      ParameterRef<double> m_timeResolution {this, "timeResolution", config().timeResolution};
      ...

By comparing the two blocks of code above, we can see that the digitized hits, SiBarrelVertexRawHits, are stored in the data type RawTrackerHit that is defined in the edm4eic data model:

YAML 

edm4eic::RawTrackerHit:
    Description: "Raw (digitized) tracker hit"
    Author: "W. Armstrong, S. Joosten"
    Members:
      - uint64_t          cellID      // The detector specific (geometrical) cell id from segmentation
      - int32_t           charge
      - int32_t           timeStamp

In addition, the one-to-one relation between the sim hit and its digitized hit is stored as an MCRecoTrackerHitAssociation object:

YAML 

edm4eic::MCRecoTrackerHitAssociation:
    Description: "Association between a RawTrackerHit and a SimTrackerHit"
    Author: "C. Dilks, W. Deconinck"
    Members:
      - float                 weight        // weight of this association
    OneToOneRelations:
      - edm4eic::RawTrackerHit rawHit       // reference to the digitized hit
      - edm4hep::SimTrackerHit simHit       // reference to the simulated hit

which is filled in SiliconTrackerDigi.cc:

CPP 

  auto hitassoc = associations->create();
  hitassoc.setWeight(1.0);
  hitassoc.setRawHit(item.second);
  hitassoc.setSimHit(sim_hit);
Challenge

Exercise 2.1

Please find other detector systems that use SiliconTrackerDigi for digitization.

Search the detector setup files under EICrecon/src/detectors/ for SiliconTrackerDigi_factory. Besides the barrel vertex tracker (BVTX), the other silicon tracker subsystems (e.g. the silicon barrel and endcap trackers) use the same digitization factory, each with its own input hit collection and threshold configuration.

Track Reconstruction

By default, we use the Combinatorial Kalman Filter from the ACTS library to handle track finding and fitting. This happens in the CKFTracking factory.

Challenge

Exercise 2.2

Please find the inputs and outputs of CKFTracking, and draw a flow chart from CentralTrackerMeasurements to CentralTrackVertices.

Look up the CKFTracking factory in the tracking detector setup (EICrecon/src/global/tracking/). Its input is the collection of 2D measurements (CentralTrackerMeasurements) and its outputs are the track candidates/trajectories that are then turned into track parameters and, downstream, the vertices. The flow chart follows the chain measurements → trajectories → track parameters → vertices.

Reconstruction output

  • events tree:
    • MCParticles and detector sim hits are copied from simulation output to recon output
    • outputs from each step of recon algorithms must be either an edm4hep or edm4eic object if you want to save them in recon output
    • the default list of saved objects in recon output is defined in EICrecon/src/services/io/podio/JEventProcessorPODIO.cc. It can be configured on the command line.
  • podio_metadata tree:
    • events___CollectionTypeInfo provides a lookup table between output collection name and IDs (its collectionID and name members line up index-by-index; older files exposed this as events___idTable).
Challenge

Exercise 2.3

The vector member or relation of a given data collection is saved in a separate branch that starts with “_“.

  • Please use

    PYTHON 

    tree.keys(filter_name="_CentralCKFTrajectories*", recursive=False)

    to list those members in CentralCKFTrajectories

  • for a given event, the vector member _CentralCKFTrajectories_measurementChi2 provides a list of chi2 for each measurement hit respectively. If multiple trajectories are found for one event, you can use CentralCKFTrajectories.measurementChi2_begin to locate the start index of a given trajectory (subentry).

The tree.keys(...) call returns the branches prefixed with _CentralCKFTrajectories_, including _CentralCKFTrajectories_measurementChi2. To read the chi2 values belonging to a particular trajectory, use the measurementChi2_begin/measurementChi2_end indices of that trajectory as the slice into the flat _CentralCKFTrajectories_measurementChi2 vector.

Challenge

Exercise 2.4

CentralTrackerMeasurements saves all available space points for tracking as 2D measurements attached to representing surfaces.

  • Please use the relation _CentralTrackerMeasurements_hits to trace back to the original detector hit collection (hint: use the collection ID lookup table), and obtain the 3D coordinate of the hit.

Each entry of _CentralTrackerMeasurements_hits is an object ID holding a collection ID (_CentralTrackerMeasurements_hits.collectionID) and an index (_CentralTrackerMeasurements_hits.index). Use the events___CollectionTypeInfo branch in the podio_metadata tree to build a collectionID -> name map (zip its .collectionID and .name members), map the collection ID back to the original hit collection name, then index into that collection to read the hit’s 3D position.

What’s next

Key Points
  • simulated hits–EICrecon–> reconstructed quantities