docs/examples/full_chain_odd.md

0001 # Walkthrough of the OpenDataDetector full chain example
0002
0003 The OpenDataDetector (ODD) is fictitious silicon detector which resides in its own repository on [GitLab](https://gitlab.cern.ch/acts/OpenDataDetector). It is used for testing and as a performance baseline in ACTS.
0004
0005 Our full chain ODD example is written in Python and can be found [here](https://github.com/acts-project/acts/blob/main/Examples/Scripts/Python/full_chain_odd.py).
0006
0007 The first step is to load the ODD detector description and to construct the detector. `getOpenDataDetectorDirectory` gives us the ODD folder within the `thirdparty` directory in Acts. We load our preferred material map and provide it to the detector construction `getOpenDataDetector`.
0008
0009 ```python
0010 actsDir = pathlib.Path(__file__).parent.parent.parent.parent
0011 geoDir = getOpenDataDetectorDirectory()
0012
0013 oddMaterialMap = geoDir / "data/odd-material-maps.root"
0014 oddMaterialDeco = acts.IMaterialDecorator.fromFile(oddMaterialMap)
0015
0016 detector = getOpenDataDetector(odd_dir=geoDir, materialDecorator=oddMaterialDeco)
0017 trackingGeometry = detector.trackingGeometry()
0018 decorators = detector.contextDecorators()
0019 ```
0020
0021 In our simple example we assume a homogeneous magnetic field along the beam axis with 2 T. The magnetic field is passed to all the different algorithms in our simulation and the reconstruction pipeline.
0022
0023 ```python
0024 field = acts.ConstantBField(acts.Vector3(0.0, 0.0, 2.0 * u.T))
0025 ```
0026
0027 The simulation step involves random processes and in order to get the same results across different executions we provide our preferred random number generator with an arbitrary seed.
0028
0029 ```python
0030 rnd = acts.examples.RandomNumbers(seed=42)
0031 ```
0032
0033 All simulation and reconstruction pipelines in ACTS begin with a `Sequencer`. It controls the execution of the different algorithms in the chain. We provide the number of events, the number of threads to use (`-1` to use all the machine's cores) and the desired log level.
0034
0035 ```python
0036 s = acts.examples.Sequencer(events=100, numThreads=-1, logLevel=acts.logging.INFO)
0037 ```
0038
0039 Our first simulation step is the particle gun.
0040 It spawns particles and their initial parameters, like position and momentum, inside our detector.
0041
0042 In our simple example we generate a single muon with random charge (i.e. muon or anti-muon) with 1-10 GeV with uniform pseudorapidity from -3 to 3.
0043
0044 Relativistic muons are hardly deflected in the detector and will keep most of their energy which makes them almost ideal for track reconstruction.
0045
0046 ```python
0047 addParticleGun(
0048     s,
0049     MomentumConfig(1.0 * u.GeV, 10.0 * u.GeV, transverse=True),
0050     EtaConfig(-3.0, 3.0, uniform=True),
0051     ParticleConfig(1, acts.PdgParticle.eMuon, randomizeCharge=True),
0052     rnd=rnd,
0053 )
0054 ```
0055
0056 These newly created particles now need to be propagated through our detector. Fatras will do this for us if we provide it the detector geometry and the magnetic field.
0057
0058 Learn more about Fatras [here](/fatras/fatras).
0059
0060 ```python
0061 addFatras(
0062     s,
0063     trackingGeometry,
0064     field,
0065     outputDirRoot=outputDir,
0066     rnd=rnd,
0067 )
0068 ```
0069
0070 The last step in the simulation is the digitization. Here we simulate the readout of the detector after a charged particle interacted with active detector material.
0071
0072 In the simplest case we use a gaussian smearing of the true hit and displace it slightly.
0073
0074 ```python
0075 oddDigiConfig = actsDir / "Examples/Configs/odd-digi-smearing-config.json"
0076
0077 addDigitization(
0078     s,
0079     trackingGeometry,
0080     field,
0081     digiConfigFile=oddDigiConfig,
0082     outputDirRoot=outputDir,
0083     rnd=rnd,
0084 )
0085 ```
0086
0087 With the last step we completed the simulation and switch the focus to the actual topic: reconstruction.
0088
0089 The first step in our reconstruction is the track seeding. Here we try to find tracks and estimate their parameters.
0090
0091 ```python
0092 oddSeedingSel = actsDir / "Examples/Configs/odd-seeding-config.json"
0093
0094 addSeeding(
0095     s,
0096     trackingGeometry,
0097     field,
0098     geoSelectionConfigFile=oddSeedingSel,
0099     outputDirRoot=outputDir,
0100 )
0101 ```
0102
0103 The Combinatorial Kalman Filter (CKF) will use the seeds to propagate the trajectory forward and backward in time with the idea to find more measurements along the way.
0104 It combines (i.e. smooths) these measurements and outputs reconstructed tracks which include smoothed track parameters for each measurement.
0105
0106 ```python
0107 addCKFTracks(
0108     s,
0109     trackingGeometry,
0110     field,
0111     outputDirRoot=outputDir,
0112 )
0113 ```
0114
0115 Our very last step in the reconstruction is the vertexing. In this step we try to find the origin of our tracks which are usually in the beam pipe at center of our detector.
0116
0117 ```python
0118 addVertexFitting(
0119     s,
0120     field,
0121     vertexFinder=VertexFinder.AMVF,
0122     outputDirRoot=outputDir,
0123 )
0124 ```