Version:
[ ReleaseNotes ] [ 1.0 ] [ 1.1 ] [ 2.0 ] [ 3.0 ] [ 3.1 ] [ 3.2 ] [ 4.0 ] [ 4.0.p1 ] [ 4.0.p2 ] [ 4.1 ] [ 4.1.p1 ] [ 5.0 ] [ 5.0.p1 ] [ 5.1 ] [ 5.1.p1 ] [ 5.2 ] [ 5.2.p1 ] [ 5.2.p2 ] [ 6.0 ] [ 6.0.p1 ] [ 6.1 ] [ 6.2 ] [ 6.2.p1 ] [ 6.2.p2 ] [ 7.0 ] [ 7.0.p1 ] [ 7.1 ] [ 7.1.p1 ] [ 8.0 ] [ 8.0.p1 ] [ 8.1 ] [ 8.1.p1 ] [ 8.1.p2 ] [ 8.2 ] [ 8.2.p1 ] [ 8.3 ] [ 8.3.p1 ] [ 8.3.p2 ] [ 9.0 ] [ 9.0.p1 ] [ 9.0.p2 ] [ 9.1 ] [ 9.1.p1 ] [ 9.1.p2 ] [ 9.1.p3 ] [ 9.2 ] [ 9.2.p1 ] [ 9.2.p2 ] [ 9.2.p3 ] [ 9.2.p4 ] [ 9.3 ] [ 9.3.p1 ] [ 9.3.p2 ] [ 9.4 ] [ 9.4.p1 ] [ 9.4.p2 ] [ 9.4.p3 ] [ 9.4.p4 ] [ 9.5 ] [ 9.5.p1 ] [ 9.5.p2 ] [ 9.6 ] [ 9.6.p1 ] [ 9.6.p2 ] [ 9.6.p3 ] [ 9.6.p4 ] [ 10.0 ] [ 10.0.p1 ] [ 10.0.p2 ] [ 10.0.p3 ] [ 10.0.p4 ] [ 10.1 ] [ 10.1.p1 ] [ 10.1.p2 ] [ 10.1.p3 ] [ 10.2 ] [ 10.2.p1 ] [ 10.2.p2 ] [ 10.2.p3 ] [ 10.3 ] [ 10.3.p1 ] [ 10.3.p2 ] [ 10.3.p3 ] [ 10.4 ] [ 10.4.p1 ] [ 10.4.p2 ] [ 10.4.p3 ] [ 10.5 ] [ 10.5.p1 ] [ 10.6 ] [ 10.6.p1 ] [ 10.6.p2 ] [ 10.6.p3 ] [ 10.7 ] [ 10.7.p1 ] [ 10.7.p2 ] [ 10.7.p3 ] [ 10.7.p4 ] [ 11.0 ] [ 11.0.p1 ] [ 11.0.p2 ] [ 11.0.p3, ] [ 11.0.p4 ] [ 11.1 ] [ 11.1.1 ] [ 11.1.2 ] [ 11.1.3 ] [ 11.2 ] [ 11.2.1 ] [ 11.2.2 ] [ 11.3.0 ]
1 -------------------------------------------------------------------
2
3 =========================================================
4 Geant4 - an Object-Oriented Toolkit for Simulation in HEP
5 =========================================================
6
7 Example Par04
8 -------------
9
10 This example demonstrates how to use the Machine Learning (ML) inference
11 to create energy deposits as a fast simulation model using ONNX Runtime [1],
12 LWTNN [2], and LibTorch [3] libraries.
13
14 The model used in this example was trained externally (in Python) on data
15 from this examples' full simulation and can be applied to perform fast simulation.
16 The python scripts are available in the training folder.
17
18 The geometry used in the example is a cylindrical setup of layers: tungsten
19 absorber and silicon as the active material. 3D readout geometry (cylindrical)
20 is defined dynamically, based on the particle direction at the entrance to the
21 calorimeter. This is set using a fast simulation model that is triggered at
22 detector entrance. Analysis of energy deposits is done in the event action,
23 ntuple with hits is stored.
24
25 [1]: https://github.com/microsoft/onnxruntime
26 [2]: https://github.com/lwtnn/lwtnn
27 [3]: https://pytorch.org/cppdocs/frontend.html
28
29 1. Detector description
30 -----------------------
31
32 The detector consists of cylindrical layers of passive and active material,
33 tungsten and silicon, respectively.
34
35 Fast simulation is attached to the region of the detector.
36
37 Input macro can specify which layer is considered an active layer (sensitive
38 detector is attached to it). For fast simulation both layers should be marked
39 as sensitive. It is connected to the way the deposits are created: position is
40 centre of the layer, which may often fall within the absorber (which is thicker
41 than the active material). In a realistic detector setup, the positions used in
42 fast simulation would be calculated properly, to deposit energy within the active
43 material.
44
45 2. Sensitive detectors
46 -----------------------
47
48 2.1. Par04SensitiveDetector
49 ---------------------------
50 This SD scores energy originating from showers, in a cylinder around the particle
51 direction and position in the calorimeter.
52 Sensitive detector inherits from both base classes:
53 - G4VSensitiveDetector: for processing of detailed/non-fast simulation hits
54 - G4VFastSimSensitiveDetector: for processing of fast sim (G4FastSim) hits.
55 Hits are placed in the same hit collection, with a different flag to distinguish
56 between those originated in the full simulation, and those from the fast
57 simulation.
58 During visualisation, hits are represented as volumes of different colour:
59 green for full simulation and red for fast simulation.
60
61 2.2. Par04ParallelFullSensitiveDetector
62 ---------------------------------------
63 This SD represents a physical readout structure to the detector (a regular grid).
64 UI settings are available to set number of slices (azimuthal segmentation) and number
65 of rows (segmentation along beam axis). Number of layers cannot be changed as it
66 corresponds to the number of layers placed at the detector construction time. Only
67 deposits in the active (sensitive) layers are scored in this SD.
68
69 2.2. Par04ParallelFastSensitiveDetector
70 ---------------------------------------
71 This SD represents a physical readout that takes into account deposits originating
72 from fast simulation, so cells span over active and passive layers. This allows to
73 account all energy from the parameterisation.
74
75 3. Primary generation
76 ---------------------
77
78 Particle gun is used as a primary generator. 10 GeV electron is used by default.
79 By default particles are generated along y axis. Those values
80 can be changed using /gun/ UI commands.
81
82 4. Physics List
83 ---------------
84
85 FTFP_BERT modular physics list is used. On top of it, fast simulation physics
86 is registered for selected particles (electrons, positrons).
87
88
89 5. User actions
90 ----------------------------------------------------------
91
92 - Par04RunAction : run action used for initialization and termination
93 of the run. Histograms for analysis of shower development
94 in the detector are created.
95
96 - Par04EventAction : event action used for initialization and termination
97 of the event. Analysis of shower development is performed
98 on event-by-event basis.
99
100 6. ML Inference
101 ----------------------------------------------------------
102 - Par04MLFastSimModel : model used for parametrisation of electrons, positrons,
103 and gammas. Energy is deposited and
104 distributed according to inferred values from the ML model.
105 This class triggers the inference setup, asks for values,
106 and deposits energies at given positions.
107
108 - Par04InferenceSetup : this class is used to initialize the inference parameters
109 (user application specific) such as the inference library,
110 the path and name of the inference model and the size of
111 the input inference vector(latent dimension and and condition size).
112 This class constructs this vector and triggers the interface
113 corresponding to the specified input inference library.
114 After the inference, the post processing step consists of
115 scaling back inferred values to the original range.
116
117 - Par04InferenceInterface : is a base class that allows to read in the ML model, configure
118 and execute inference.
119
120 - Par04OnnxInference and Par04LWTNNInference and Par04TorchInference : inference library specific
121 classes that inherit from the base class Par04InferenceInterface.
122
123
124 7. Output
125 ---------
126
127 The execution of the program (examplePar04) produces an output with histograms.
128 Ntuples are also stored. They are not merged if the application is run on multiple threads.
129
130 The macro file examplePar04.mac is used to run full simulation. It will simulate 100
131 events, for single 10 GeV electron beams.
132 If CMake is able to find inference libraries (LWTNN and/or ONNX Runtime and/or LibTorch), a configuration
133 macro will be available for that library (examplePar04_lwtnn.mac and/or examplePar04_onnx.mac
134 and/or examplePar04_torch.mac). It will use a trained model to run inference and create showers
135 in the detector by directly depositing energy.
136
137 8. How to build and run the example
138 -----------------------------------
139 - LWTNN, ONNX Runtime, and LibTorch are available on LCG. In order to use them, you can set a CMAKE_PREFIX_PATH:
140 % source /cvmfs/sft.cern.ch/lcg/contrib/gcc/11.3.0/x86_64-centos7/setup.sh
141 % cmake -DCMAKE_PREFIX_PATH="/cvmfs/sft.cern.ch/lcg/releases/LCG_102b/lwtnn/2.11.1/x86_64-centos7-gcc11-opt/;/cvmfs/sft.cern.ch/lcg/releases/LCG_102b/onnxruntime/1.11.1/x86_64-centos7-gcc11-opt/;/cvmfs/sft.cern.ch/lcg/releases/LCG_102b/torch/1.11.0/x86_64-centos7-gcc11-opt/lib/python3.9/site-packages/torch/" <Par04_SOURCE>
142
143 - Compile and link to generate the executable (in your CMake build directory):
144 % cmake <Par04_SOURCE>
145 % make
146
147 - Execute the application (in batch mode):
148 % ./examplePar04 -m examplePar04.mac
149 which produces two root file for full simulation.
150
151 - Execute the application (in interactive mode):
152 % ./examplePar04 -i -m vis.mac
153 which allows to visualize hits (from full simulation).
154
155 - If ONNX Runtime is available:
156 % ./examplePar04 -m examplePar04_onnx.mac
157 For interactive mode with visualization:
158 % ./examplePar04 -i -m vis_onnx.mac
159
160 - If LWTNN is available:
161 % ./examplePar04 -m examplePar04_lwtnn.mac
162 For interactive mode with visualization:
163 % ./examplePar04 -i -m vis_lwtnn.mac
164 - If LibTorch is available:
165 % ./examplePar04 -m examplePar04_torch.mac
166 For interactive mode with visualization:
167 % ./examplePar04 -i -m vis_torch.mac
168
169 - Additional options available:
170 % ./examplePar04 -m examplePar04.mac -r 0
171 For serial run manager mode
172 % ./examplePar04 -m examplePar04.mac -r 1 -t 8
173 For multi-threaded run manager mode with 8 threads
174 % ./examplePar04 -m examplePar04.mac -r 2
175 For tasking run manager mode with number of tasks that can be change via env variable G4FORCE_EVENTS_PER_TASK
176
177
178 By default, CMake will attempt to build fast simulation with ONNX Runtime and LWTNN. However, if none
179 of those libraries is found, it will proceed with full simulation only. The search can be switched
180 off manually switching CMake flag INFERENCE_LIB to OFF (-DINFERENCE_LIB=OFF)
181
182 9. Macros
183 ---------
184
185 common_settings.mac - A macro with common settings, executed by all other macros (e.g. detector settings).
186
187 vis.mac - Allows to run visualization. Pass it to the example in interactive mode ("-i" passed to the executable).
188 It can be used to visualize full simulation.
189
190 vis_onnx.mac - Allows to run visualization with ONNX Runtime inference. Pass it to the example in interactive mode
191 ("-i" passed to the executable). It contains necessary settings of the inference.
192
193 vis_lwtnn.mac - Allows to run visualization with LWTNN inference. Pass it to the example in interactive mode
194 ("-i" passed to the executable). It contains necessary settings of the inference.
195
196 vis_torch.mac - Allows to run visualization with LibTorch inference. Pass it to the example in interactive mode
197 ("-i" passed to the executable). It contains necessary settings of the inference.
198
199 examplePar04.mac - Runs full simulation. It will run 100 events with single electrons, 10 GeV and
200 along y axis.
201
202 examplePar04_onnx.mac - Available only if ONNX Runtime is found by CMake. Runs fast simulation with
203 a NN stored in onnx file.
204
205 examplePar04_lwtnn.mac - Available only if LWTNN is found by CMake. Runs fast simulation with
206 a NN stored in json file.
207
208 examplePar04_torch.mac - Available only if LibTorch is found by CMake. Runs fast simulation with
209 a NN stored in pt file.
210
211 10. UI commands
212 --------------
213
214 UI commands useful in this example:
215
216 - activation/disactivation of the fast simulation model:
217 /param/ActivateModel inferenceModel
218 /param/InActivateModel inferenceModel
219
220 - particle gun commands
221 /gun/particle e-
222 /gun/energy 10 GeV
223 /gun/direction 0 1 0
224 /gun/position 0 0 0
225
226 UI commands defined in this example:
227 - detector settings
228 /Par04/detector/setDetectorInnerRadius 80 cm
229 /Par04/detector/setDetectorLength 2 m
230 /Par04/detector/setNbOfLayers 90
231 /Par04/detector/setAbsorber 0 G4_W 1.4 mm false
232 /Par04/detector/setAbsorber 1 G4_Si 0.3 mm true
233
234 - readout mesh
235 /Par04/mesh/setSizeOfRhoCells 2.325 mm
236 /Par04/mesh/setSizeOfZCells 3.4 mm
237 /Par04/mesh/setNbOfRhoCells 18
238 /Par04/mesh/setNbOfPhiCells 50
239 /Par04/mesh/setNbOfZCells 45
240
241 - inference setup
242 /Par04/inference/setSizeLatentVector 10
243 /Par04/inference/setSizeConditionVector 4
244 /Par04/inference/setModelPathName MLModels/Generator.onnx
245 /Par04/inference/setProfileFlag 0
246 /Par04/inference/setOptimizationFlag 0
247 /Par04/inference/setInferenceLibrary ONNX
248 /Par04/inference/setSizeOfRhoCells 2.325 mm
249 /Par04/inference/setSizeOfZCells 3.4 mm
250 /Par04/inference/setNbOfRhoCells 18
251 /Par04/inference/setNbOfPhiCells 50
252 /Par04/inference/setNbOfZCells 45
253
254 11. Python scripts for training
255 --------------
256
257 The scripts available in the training folder were used to firstly convert
258 the ROOT files to the h5 files, preprocess the data and then train
259 the VAE model of this example. More details can be found in
260 training/README.
261
262
263 12. Public data
264 --------------
265
266 Data generated with full simulation with this example has been published on zenodo:
267 https://doi.org/10.5281/zenodo.6082201
