Skip to content

Commit 8535d68

Browse files
ShujieLShujieL
committed
update tutorials
1 parent 52c905d commit 8535d68

File tree

4 files changed

+246
-109
lines changed

4 files changed

+246
-109
lines changed

‎_episodes/00-setup.md

Lines changed: 3 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
---
22
title: "Set up the Jupyter Notebook Environment"
3-
teaching: 10
3+
teaching: 5
44
exercises: 5
55
questions:
66
- "How to access simulation campaign output with python?"
77
objectives:
88
- "Set up interactive python platform with Jupyter-notebook."
9-
- "Access the simulation campaign output with `uproot`."
9+
keypoints:
10+
- "install uproot and xrootd"
1011
---
1112
## Set up Jupyter-notebook
1213
- on Google Colab (recommended):
@@ -24,41 +25,4 @@ objectives:
2425
> Note: we will be using other standard python packages such as `numpy` and `pandas`, which are pre-installed on Colab.
2526
{: .callout}
2627

27-
28-
## Access simulation campaign output
29-
> The simulation campaign [website](https://eic.github.io/epic-prod/documentation/default_datasets.html) documents the available datasets and version information.
30-
>
31-
> To browse the directory and download rootfiles with stand-alone `xrdfs` command, see the [previous tutorials](https://eic.github.io/tutorial-analysis/01-introduction/index.html). Here we will proceed with the python interface:
32-
```console
33-
from XRootD import client
34-
# Create XRootD client
35-
eic_server = 'root://dtn-eic.jlab.org/'
36-
fs = client.FileSystem(eic_server)
37-
# List directory contents
38-
fpath = '/work/eic2/EPIC/RECO/24.10.0/epic_craterlake/DIS/NC/18x275/minQ2=10/'
39-
status, files = fs.dirlist(fpath)
40-
# Print files
41-
if status.ok:
42-
print(files.size)
43-
for entry in files:
44-
print(entry.name)
45-
else:
46-
print(f"Error: {status.message}")
47-
```
48-
49-
> To open a simulation campaign file
50-
```console
51-
fname = eic_server+fpath+'pythia8NCDIS_18x275_minQ2=10_beamEffects_xAngle=-0.025_hiDiv_1.0000.eicrecon.tree.edm4eic.root'
52-
tree_name = "events" #"podio_metadata"
53-
tree = ur.open(fname)[tree_name]
54-
print(f"Read {fname}:{tree_name}. \n {tree.num_entries} events in total")
55-
```
56-
57-
58-
> Exercise 1: open a local rootfile
59-
> - open a local rootfile of your choice
60-
> - use ```tree.keys(filter_name="*",recursive=False)``` to display all branches
61-
{: .challenge}
62-
63-
6428
{% include links.md %}

‎_episodes/01-dd4hep.md

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
title: "Introduction to the DD4hep simulation"
3+
teaching: 25
4+
exercises: 15
5+
questions:
6+
- "Understand the inputs and outputs of the DD4hep simulation"
7+
objectives:
8+
- "Event generation"
9+
- "Detector description"
10+
- "MCParticles and detector hits"
11+
- "Simulation campaign files"
12+
keypoints:
13+
- "event generator --`dd4hep`--> simulated hits and particles"
14+
---
15+
16+
17+
## DD4hep simulation
18+
This Geant4-based simualtion package propagates particles through magnetic field and materials. Particles and detector hits for each event are saved in the output rootfiles.
19+
20+
- __Input 1: Event generation__
21+
22+
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](https://arxiv.org/pdf/1912.08005).
23+
24+
One can also use the DD4hep's particle gun to generate outgoing particles with given vertex and distribution, see the [previous tutorial](https://eic.github.io/tutorial-simulations-using-ddsim-and-geant4/aio/index.html) on `ddsim`.
25+
26+
27+
- __Input 2: Detector description__
28+
29+
The ePIC detector description in DD4hep is maintained [on github](https://github.com/eic/epic/). 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.
30+
31+
Below is an example from epic/compact/tracking/vertex_barrel.xml:
32+
33+
```console
34+
<readouts>
35+
<readout name="VertexBarrelHits">
36+
<segmentation type="CartesianGridXY" grid_size_x="0.020*mm" grid_size_y="0.020*mm" />
37+
<id>system:8,layer:4,module:12,sensor:2,x:32:-16,y:-16</id>
38+
</readout>
39+
</readouts>
40+
```
41+
All hits from this silicon vertex barrel detector, including their position, energy deposit, time, will be stored under the branch `VertexBarrelHits` in output.
42+
Each detector hit also comes an assigned 64-bit cell ID, with the last 32 bits from right to left represents the hit localtion 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.
43+
44+
- __Output__
45+
The `event` tree in the simulation output contains
46+
- `MCParticles`: records the truth info of primary and secondary particles
47+
- Individual branches for signals from various sub-detector systems e.g. `VertexBarrelHits`
48+
49+
> Exercise 1.1: access simulation campaign rootfiles
50+
The simulation campaign [website](https://eic.github.io/epic-prod/documentation/default_datasets.html) documents the available datasets and version information.
51+
-__Browse the directory__
52+
For stand-alone `xrdfs` command, see the [previous tutorials](https://eic.github.io/tutorial-analysis/01-introduction/index.html). Here we will proceed with the python interface:
53+
54+
```console
55+
from XRootD import client
56+
# Create XRootD client
57+
eic_server = 'root://dtn-eic.jlab.org/'
58+
fs = client.FileSystem(eic_server)
59+
# List directory contents
60+
fpath = '/work/eic2/EPIC/RECO/24.12.0/epic_craterlake/SINGLE/e-/10GeV/130to177deg/'
61+
status, files = fs.dirlist(fpath)
62+
# Print files
63+
if status.ok:
64+
print(files.size)
65+
for entry in files:
66+
print(entry.name)
67+
else:
68+
print(f"Error: {status.message}")
69+
```
70+
71+
-__Open a simulation campaign file__
72+
```console
73+
fname = eic_server+fpath+'e-_10GeV_130to177deg.0307.eicrecon.tree.edm4eic.root'
74+
tree_name = "events" #"podio_metadata"
75+
tree = ur.open(fname)[tree_name]
76+
print(f"Read {fname}:{tree_name}. \n {tree.num_entries} events in total")
77+
```
78+
{: .challenge}
79+
80+
81+
> Exercise 1.2: inspect available branches in a rootfile
82+
> - use ```tree.keys(filter_name="*",recursive=False)``` to display all branches
83+
> - extract a given branch to dataframe
84+
```console
85+
bname = "MCParticles"
86+
df = tree[bname].array(library="ak")
87+
df = ak.to_dataframe(df)
88+
print(df)
89+
```
90+
{: .challenge}
91+
92+
> Exercise 1.3: extract momentum distribution of primary electrons
93+
```console
94+
## select electrons
95+
from particle import Particle
96+
part = Particle.from_name("e-")
97+
pdg_id = part.pdgid.abspid
98+
condition1 = df["MCParticles.PDG"]==pdg_id
99+
## select primary particles
100+
condition2 = df["MCParticles.generatorStatus"]==1
101+
102+
## extract momentum
103+
## all electrons
104+
df_new = df[condition1]
105+
mom = np.sqrt(df_new["MCParticles.momentum.x"]**2+df_new["MCParticles.momentum.y"]**2+df_new["MCParticles.momentum.z"]**2)
106+
bins = np.arange(0,20)
107+
_ = plt.hist(mom,bins=bins,alpha=0.5)
108+
## primary electrons
109+
df_new = df[condition1&condition2]
110+
mom = np.sqrt(df_new["MCParticles.momentum.x"]**2+df_new["MCParticles.momentum.y"]**2+df_new["MCParticles.momentum.z"]**2)
111+
_ = plt.hist(mom,bins=bins,histtype="step", color='r')
112+
```
113+
{: .challenge}
114+
115+
{% include links.md %}

‎_episodes/01-introduction.md

Lines changed: 0 additions & 70 deletions
This file was deleted.

‎_episodes/02-eicrecon.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: "Reconstruction workflow"
3+
teaching: 25
4+
exercises: 15
5+
questions:
6+
- "Understand the EICrecon workflow"
7+
objectives:
8+
- "Hit digitization"
9+
- "data model"
10+
- "Reconstruction algorithms"
11+
keypoints:
12+
- "simulated hits--`EICrecon`--> reconstructed quantities"
13+
---
14+
15+
16+
## Reconstruction workflow
17+
The ePIC reconsutrction framework `EICrecon` is maintained [on github](https://github.com/eic/eicrecon/). It process simulated hits from various detectors to reconstruct trajectory, PID, etc, and eventually reconstruct the simulated particle and physics observables at the vertex.
18+
19+
Each reconstruction step involves 3 components:
20+
- the algorithm,
21+
- the JOmniFactory where algorithm and data type are declared.
22+
- the factory generator to excute the algorithm.
23+
24+
> in this section, we will use __track reconstruction__ as an example. Please refer to the Lehigh reconstruction workfest [presentations](https://indico.bnl.gov/event/20727/sessions/7433/#20240725) for reconstruction workflow of other systems.
25+
26+
27+
> - __Digitization__
28+
All simualted 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`:
29+
```console
30+
// Digitization
31+
app->Add(new JOmniFactoryGeneratorT<SiliconTrackerDigi_factory>(
32+
"SiBarrelVertexRawHits", // factory name
33+
{
34+
"VertexBarrelHits" // input
35+
},
36+
{
37+
"SiBarrelVertexRawHits", // outputs
38+
"SiBarrelVertexRawHitAssociations"
39+
},
40+
{
41+
.threshold = 0.54 * dd4hep::keV, // configurations
42+
},
43+
app
44+
));
45+
```
46+
The actual algorithm locates at `EICrecon/src/algorithms/digi/SiliconTrackerDigi.cc`, with its input and output specified in `SiliconTrackerDigi_factory.h`:
47+
48+
```console
49+
class SiliconTrackerDigi_factory : public JOmniFactory<SiliconTrackerDigi_factory, SiliconTrackerDigiConfig> {
50+
51+
public:
52+
using AlgoT = eicrecon::SiliconTrackerDigi;
53+
private:
54+
std::unique_ptr<AlgoT> m_algo;
55+
56+
PodioInput<edm4hep::SimTrackerHit> m_sim_hits_input {this};
57+
58+
PodioOutput<edm4eic::RawTrackerHit> m_raw_hits_output {this};
59+
PodioOutput<edm4eic::MCRecoTrackerHitAssociation> m_assoc_output {this};
60+
61+
ParameterRef<double> m_threshold {this, "threshold", config().threshold};
62+
ParameterRef<double> m_timeResolution {this, "timeResolution", config().timeResolution};
63+
...
64+
```
65+
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](https://github.com/eic/EDM4eic/blob/main/edm4eic.yaml):
66+
```console
67+
edm4eic::RawTrackerHit:
68+
Description: "Raw (digitized) tracker hit"
69+
Author: "W. Armstrong, S. Joosten"
70+
Members:
71+
- uint64_t cellID // The detector specific (geometrical) cell id from segmentation
72+
- int32_t charge
73+
- int32_t timeStamp
74+
```
75+
In addition, the one-to-one relation between the sim hit and its digitized hit is stored as an `MCRecoTrackerHitAssociation` object:
76+
```console
77+
edm4eic::MCRecoTrackerHitAssociation:
78+
Description: "Association between a RawTrackerHit and a SimTrackerHit"
79+
Author: "C. Dilks, W. Deconinck"
80+
Members:
81+
- float weight // weight of this association
82+
OneToOneRelations:
83+
- edm4eic::RawTrackerHit rawHit // reference to the digitized hit
84+
- edm4hep::SimTrackerHit simHit // reference to the simulated hit
85+
```
86+
which is filled in `SiliconTrackerDigi.cc`:
87+
```console
88+
auto hitassoc = associations->create();
89+
hitassoc.setWeight(1.0);
90+
hitassoc.setRawHit(item.second);
91+
hitassoc.setSimHit(sim_hit);
92+
```
93+
94+
> Exercise 2.1: please find other detector systems that use `SiliconTrackerDigi` for digitization
95+
{: .challenge}
96+
97+
98+
> -__Track Reconstruction__
99+
By default, we use the Combinatorial Kalman Filter from the ACTS library to handle track finding and fitting. This happens in the `CKFTracking` factory.
100+
101+
> Exercise 2.2: please find the inputs and outputs of `CKFTracking`, and draw a flow chart from `CentralTrackerMeasurements` to `CentralTrackVertices`.
102+
{: .challenge}
103+
104+
-__Reconstruction output__
105+
- `events` tree:
106+
- `MCParticles` and detector sim hits are copied from simulation output to recon output
107+
- outputs from each step of recon algorithms must be either `edm4hep` or `edm4eic` object if you want to save them in recon output
108+
- the default list of saved objects in recon output is defined in `EICrecon/src/services/io/podio/JEventProcessorPODIO.cc`. It can be configured in command line.
109+
- `podio_metadata` tree:
110+
- `events___idTable` provides a lookup table between output collection name and IDs.
111+
112+
113+
> Exercise 2.3:
114+
> The __vector member__ or __relation__ of a given data collection is saved in a separate branch starts with "_".
115+
- use ```tree.keys(filter_name="_CentralCKFTrajectories*",recursive=False)``` to list those members in `CentralCKFTrajectories`
116+
- for a given event, the vector member `_CentralCKFTrajectories_measurementChi2` provides a list of chi2 for each meaurement 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).
117+
{: .challenge}
118+
119+
> Exercise 2.4:
120+
> `CentralTrackerMeasurements` saved all available space points for tracking as 2D meaurement attached to representing surfaces.
121+
- 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
122+
{: .challenge}
123+
{% include links.md %}
124+
125+
## Future reading
126+
- Generate your own simulation and reconstruction rootfiles [tutorial](https://eic.github.io/tutorial-simulations-using-ddsim-and-geant4/)
127+
- Contribute to reconstruction algorithsm [tutorial](https://eic.github.io/tutorial-reconstruction-algorithms/)
128+
- Develop analysis benchmarks [tutorial](https://eic.github.io/tutorial-developing-benchmarks/)

0 commit comments

Comments
 (0)