Warning, /tutorial-simulations-using-ddsim-and-geant4/_episodes/01-single-particle-simulations.md is written in an unsupported language. File is not indexed.
0001 ---
0002 title: "Single Particle Simulations with `ddsim`"
0003 teaching: 30
0004 exercises: 20
0005 questions:
0006 - "How can I simulate single particles for detetor studies?"
0007 objectives:
0008 - "Know where to find the available options for `ddsim`."
0009 - "Understand the differences between steering files and command line options."
0010 - "Know what the key output file collections are."
0011 keypoints:
0012 - "`ddsim` can be used with a particle gun to generate single particle simulations."
0013 ---
0014 In this first episode we will go through the running of single particle events with `ddsim`, using the built-in event generator of `ddsim`. This is the quickest way so run some straightforward tests of the geometry and produce output hits in the detectors for further analysis.
0015
0016 > You may also see reference to using `npsim` in some tutorials. We will discuss the difference between `ddsim` and `npsim`, along with cases where one should be used over the other, in the next episode of this tutorial. As a brief overview, `npsim` is `ddsim` under the hood which is itself, predominantly Geant4 under the hood. We will start with `ddsim` simply to demonstrate usage.
0017 {: .callout}
0018
0019 ## Passing options to `ddsim`
0020
0021 The program `ddsim` is part of the DD4hep installation when it is compiled with Geant4 support. In the EIC standard environment `eic-shell` it is available and used for many simulations in the suite of continuous integration and benchmarking checks for the geometry. Simply entering `ddsim --help` will show the large wealth of options that can be passed to `ddsim` on the command line.
0022
0023 It is also possible to use a python steering file to control the simulations. This is often a more convenient approach for sharing settings with others or archiving them for later reference or to iteratively add functionality. However, it should be noted that this can also lead to divergence in 'default' running conditions when these are not propagated to other environments.
0024
0025 > Exercise:
0026 > - Consult the avialable options of `ddsim` by passing it the `--help` flag.
0027 > - Find the appropriate option to specify the output file when using `ddsim`.
0028 > - Use the `--dumpSteeringFile` flag to print out a default steering file, and redirect it into a file `steering.py`.
0029 {: .challenge}
0030
0031 ## Available options in `ddsim`
0032
0033 There are several option blocks that can be used with `ddsim`. Those are best looked at in the `steering.py` file, where additional documentation is added.
0034 - `SIM.action.*` or `--action.*` options can be used to tune sensitive detector actions,
0035 - `SIM.field.*` or `--field.*` options affect the magnetic field steppers,
0036 - `SIM.filter.*` or `--filter.*` options can add filters to sensitive detectors,
0037 - `SIM.gun.*` or `--gun.*` options can set single particle gun settings,
0038 - `SIM.physics.*` or `--physics.*` options allow setting the physics list,
0039 - `SIM.random.*` or `--random.*` options can be used to fix the random seed.
0040
0041 Some options, such as `SIM.physics.setupUserPhysics`, take as argument a python function, so they can only be used inside the python steering files. We will come back to this later.
0042
0043 When using the steering file approach, it is often useful to remove all options which you will not change (this allows you to take advantage of updates to the `ddsim` command itself without being stuck on old default settings). In this case, you would simply start from a steering file that only contains:
0044 ```python
0045 from DDSim.DD4hepSimulation import DD4hepSimulation
0046 from g4units import mm, GeV, MeV
0047 SIM = DD4hepSimulation()
0048 ```
0049 and which can be passed to `ddsim` with the `--steeringFile` flag:
0050 ```console
0051 $ ddsim --steeringFile steering.py
0052 ```
0053 This steering file merely sets up the simulation object that can then be configured with settings that deviate from the default.
0054
0055 > Exercise:
0056 > - Compose a 'minimal' steering file that only contains the required header line.
0057 > - Attempt to run this steering file and note what `ddsim` claims is missing (we will specify this on the command line next).
0058 {: .challenge}
0059
0060 ## Running a first single-particle simulation
0061
0062 When we used the minimal steering file, `ddsim` pointed out that we did not specify the 'geometry compact file', nor the number of events and source of those events. In this sections we'll specify the geometry and tell `ddsim` to use a particle gun.
0063
0064 The compact file is the entry point of our geometry, for which we must load the geometry environment first
0065 ```console
0066 $ source /opt/detector/setup.sh
0067 $ ddsim --steeringFile steering.py --compactFile $DETECTOR_PATH/$DETECTOR_CONFIG.xml
0068 ```
0069
0070 Next, we will specify that we want `ddsim` to use the DD4hep particle gun, with `--enableGun` (or `-G`), and that we want 10 events, with `--numberOfEvents 10` (or `-N 10`):
0071 ```console
0072 $ ddsim --steeringFile steering.py --compactFile $DETECTOR_PATH/$DETECTOR_CONFIG.xml -G -N 10
0073 ```
0074
0075 > Note: If you are running `eic-shell` directly on cvmfs, this may take a little while the first time. All large Geant4 data files are accessed for the first time and need to be retrieved.
0076 {: .callout}
0077
0078 When we run `ddsim`, by default it prints out some information for each generated event:
0079 ```console
0080 GenerationInit INFO +++ Initializing event 1. Within run:0 event 1.
0081 Gun INFO Particle [0] mu- Mom:10.000 GeV vertex:( 0.000 0.000 0.000)[mm] direction:( 0.000 0.000 1.000)
0082 Gun INFO Shoot [0] 10.000 GeV mu- pos:(0.000 0.000 0.000)[mm] dir:( 0.000 0.000 1.000)
0083 Gun INFO +-> Interaction [0] 10.000 GeV mu- pos:(0.000 0.000 0.000)[mm]
0084 Gun INFO +++ +-> ID: 0 mu- status:00000002 PDG: 13 Vtx:(+0.00e+00,+0.00e+00,+0.00e+00)[mm] time: +0.00e+00 [ns] #Dau: 0 #Par:0
0085 PrimaryHandler INFO +++++ G4PrimaryVertex at (+0.00e+00,+0.00e+00,+0.00e+00) [mm] +0.00e+00 [ns]
0086 ParticleHandler INFO +++ Event 0 Begin event action. Access event related information.
0087 ```
0088
0089 You will notice that the particle gun has reverted to a default particle in a default direction: a 10 GeV muon in the positive z direction. That is, of course, not going to result in many hits in our ePIC detector... We will now take a closer look at some of the particle gun options.
0090 ```console
0091 --gun.energy GUN.ENERGY
0092 --gun.particle GUN.PARTICLE
0093 --gun.multiplicity GUN.MULTIPLICITY
0094 --gun.phiMin GUN.PHIMIN
0095 Minimal azimuthal angle for random distribution
0096 --gun.phiMax GUN.PHIMAX
0097 --gun.thetaMin GUN.THETAMIN
0098 --gun.thetaMax GUN.THETAMAX
0099 --gun.momentumMin GUN.MOMENTUMMIN
0100 Minimal momentum when using distribution (default = 0.0)
0101 --gun.momentumMax GUN.MOMENTUMMAX
0102 --gun.direction GUN.DIRECTION
0103 direction of the particle gun, 3 vector
0104 --gun.distribution {uniform,cos(theta),eta,pseudorapidity,ffbar}
0105 choose the distribution of the random direction for theta
0106
0107 Options for random distributions:
0108
0109 'uniform' is the default distribution, flat in theta
0110 'cos(theta)' is flat in cos(theta)
0111 'eta', or 'pseudorapidity' is flat in pseudorapity
0112 'ffbar' is distributed according to 1+cos^2(theta)
0113
0114 Setting a distribution will set isotrop = True
0115
0116 --gun.isotrop GUN.ISOTROP
0117 isotropic distribution for the particle gun
0118
0119 use the options phiMin, phiMax, thetaMin, and thetaMax to limit the range of randomly distributed directions
0120 if one of these options is not None the random distribution will be set to True and cannot be turned off!
0121
0122 --gun.position GUN.POSITION
0123 position of the particle gun, 3 vector
0124 ```
0125
0126 While many of the options have straighforward names, others may be more confusing. The `gun.distribution` option is particularly relevant when we want to distribute single particle events over a range of angles. Depending on your needs, you may prefer one over the other, but in this tutorial we will simply use `cos(theta)` to throw uniformly on the unit sphere in the forward direction:
0127 ```console
0128 $ ddsim --steeringFile steering.py --compactFile $DETECTOR_PATH/$DETECTOR_CONFIG.xml -G -N 10 --gun.thetaMin "3*deg" --gun.thetaMax "45*deg" --gun.distribution "cos(theta)" --gun.momentumMin "1*GeV" --gun.momentumMax "10*GeV" --gun.particle "pi+"
0129 ```
0130
0131 > Note: Avoid the use of the `gun.energy` option, since it is inherently more ambiguous than `gun.momentum` for massive particles (in the context of EIC).
0132 {: .callout}
0133
0134 Note how we pass arguments with units in this example. The double quotes are in many cases necessary on the command line to avoid having the `*` be expanded by your shell. In the python steering file they can be ommitted and one can simply write, e.g., `SIM.gun.thetaMin = 3*deg`.
0135
0136 When running this simulation above, note the output on the command line
0137 ```console
0138 GenerationInit INFO +++ Initializing event 1. Within run:0 event 1.
0139 Gun INFO Particle [0] pi+ Mom:4.924 GeV vertex:( 0.000 0.000 0.000)[mm] direction:( 0.017 0.403 0.915)
0140 Gun INFO Shoot [0] 10.000 GeV pi+ pos:(0.000 0.000 0.000)[mm] dir:( 0.000 0.000 1.000)
0141 Gun INFO +-> Interaction [0] 10.000 GeV pi+ pos:(0.000 0.000 0.000)[mm]
0142 Gun INFO +++ +-> ID: 0 pi+ status:00000002 PDG: 211 Vtx:(+0.00e+00,+0.00e+00,+0.00e+00)[mm] time: +0.00e+00 [ns] #Dau: 0 #Par:0
0143 PrimaryHandler INFO +++++ G4PrimaryVertex at (+0.00e+00,+0.00e+00,+0.00e+00) [mm] +0.00e+00 [ns]
0144 ParticleHandler INFO +++ Event 0 Begin event action. Access event related information.
0145 ```
0146 For historical reasons (which are being addressed), the relevant line is the one with `Particle [0]`.
0147
0148 > Exercise:
0149 > - Simulate 10 events in the negative endcap, using an angle distribution that is uniform in `cos(theta)`, and with an electron multiplicity of 2.
0150 > - Add all gun options (but not the number of events) to the minimal steering file you constructed earlier and rename the steering file to `ee_1GeV_10GeV_EndcapN.py` and run the simulation again.
0151 > - Verify that the momentum ranges and angular ranges are correct in the output.
0152 {: .challenge}
0153
0154 ## Output files
0155
0156 Until now we have not bothered to check the output files (in case you were wondering and went exploring, you may have noticed that output went into `dummyOutput.slcio`). In this section we'll explore how to write output files.
0157
0158 The command line option to use to specify the output file is the `--outputFile` option (or `SIM.outputFile` in the steering file). Depending on the extension of the output file, a specific output file format is chosen. The default output is in the slcio format, but we have standardized on the EDM4hep data model inside ROOT files. To choose this output file format, use a file extension `.edm4hep.root`. We could, for example, run the following command:
0159 ```console
0160 $ ddsim --steeringFile ee_1GeV_10GeV_EndcapN.py --compactFile $DETECTOR_PATH/$DETECTOR_CONFIG.xml --numberOfEvents 10 --outputFile ee_1GeV_10GeV_EndcapN_1e1.edm4hep.root
0161 ```
0162 > Note: The extension `.edm4hep.root` of the output file is important since `ddsim` infers the output file type from the extension.
0163 {: .callout}
0164
0165 Let's take a look at the output file in ROOT (you can do this inside or outside the container, depending on your system and facility with opening ROOT browsers).
0166 ```console
0167 $ root -l ee_1GeV_10GeV_EndcapN_1e1.edm4hep.root
0168 root [1] .ls
0169 TFile** ee_1GeV_10GeV_EndcapN_1e1.edm4hep.root data file
0170 TFile* ee_1GeV_10GeV_EndcapN_1e1.edm4hep.root data file
0171 KEY: TTree events;1 Events tree
0172 KEY: TTree metadata;1 Metadata tree
0173 KEY: TTree run_metadata;1 Run metadata tree
0174 KEY: TTree evt_metadata;1 Event metadata tree
0175 KEY: TTree col_metadata;1 Collection metadata tree
0176 ```
0177 All EDM4hep files will have the same structure. We focus here on the `events` tree (if you see `EVENT`, in capital letters, you will need to ensure that you are indeed using the `.edm4hep.root` extension).
0178
0179 > Note: In a future version of `ddsim` the output file format will change slightly, and the various `metatadata` trees will not be there anymore.
0180 {: .callout}
0181
0182 ### `MCParticles`
0183
0184 Let's first focus on the `MCParticles` branch. This contains 'truth' information and exact Geant4 step output for selected tracks. It is filled independent of sensitive detectors defined in the geometry. It is most useful to analyze the initial state of the simulation (i.e. the final state of the event generator). In our case, the number of generated particles from the particle gun is always 2, which is what we expect to recover by looking at the `@MCParticles.size()` in the `events` tree:
0185 ```console
0186 root [2] events->Draw("@MCParticles.size()")
0187 ```
0188 Wait a minute. What happened here? The `MCParticles` branch contains more than just the generated events. To include only the generated particles that were 'thrown' into the detector, we can select those with `generatorStatus` equal to 1.
0189 ```console
0190 root [3] events->Draw("MCParticles.PDG","MCParticles.generatorStatus==1")
0191 ```
0192 Another approach which is sometimes useful to reduce the number of 'other' particles that are written is to pass the option `--part.minimalKineticEnergy "1*TeV"`. This restricts the particles that are written to those that have an energy higher than 1 TeV. Initial state event generator particles are exempt from this requirement and are always written.
0193
0194 ### `*Hits`
0195
0196 The second set of branches that are important, and that are used as input to the event reconstruction framework, are the `*Hits` branches. These branches include the hits in sensitive detectors: either tracker hits or calorimeter hits. You will notice that these two different types of hits contain slightly different information.
0197
0198 > Exercise:
0199 > - Open the file `ee_1GeV_10GeV_EndcapN_1e1.edm4hep.root` which you just created in a local ROOT installation or online at [https://root.cern/js/latest](https://root.cern/js/latest).
0200 > - Plot the z component of the momentum for generated particles only and verify that this is indeed negative for particles going towards the negative endcap.
0201 > - Verify that the total number of entries is consistent with the multiplicity and number of events you have simulated.
0202 > - Plot the deposited energy of the hits in the endcap Ecal and compare the number of hits in the positive and negative endcaps.
0203 {: .challenge}
0204
