Warning, /geant4/examples/extended/parameterisations/Par04/README is written in an unsupported language. File is not indexed.
0001 -------------------------------------------------------------------
0002
0003 =========================================================
0004 Geant4 - an Object-Oriented Toolkit for Simulation in HEP
0005 =========================================================
0006
0007 Example Par04
0008 -------------
0009
0010 This example demonstrates how to use the Machine Learning (ML) inference
0011 to create energy deposits as a fast simulation model using ONNX Runtime [1],
0012 LWTNN [2], and LibTorch [3] libraries.
0013
0014 The model used in this example was trained externally (in Python) on data
0015 from this examples' full simulation and can be applied to perform fast simulation.
0016 The python scripts are available in the training folder.
0017
0018 The geometry used in the example is a cylindrical setup of layers: tungsten
0019 absorber and silicon as the active material. 3D readout geometry (cylindrical)
0020 is defined dynamically, based on the particle direction at the entrance to the
0021 calorimeter. This is set using a fast simulation model that is triggered at
0022 detector entrance. Analysis of energy deposits is done in the event action,
0023 ntuple with hits is stored.
0024
0025 [1]: https://github.com/microsoft/onnxruntime
0026 [2]: https://github.com/lwtnn/lwtnn
0027 [3]: https://pytorch.org/cppdocs/frontend.html
0028
0029 1. Detector description
0030 -----------------------
0031
0032 The detector consists of cylindrical layers of passive and active material,
0033 tungsten and silicon, respectively.
0034
0035 Fast simulation is attached to the region of the detector.
0036
0037 Input macro can specify which layer is considered an active layer (sensitive
0038 detector is attached to it). For fast simulation both layers should be marked
0039 as sensitive. It is connected to the way the deposits are created: position is
0040 centre of the layer, which may often fall within the absorber (which is thicker
0041 than the active material). In a realistic detector setup, the positions used in
0042 fast simulation would be calculated properly, to deposit energy within the active
0043 material.
0044
0045 2. Sensitive detectors
0046 -----------------------
0047
0048 2.1. Par04SensitiveDetector
0049 ---------------------------
0050 This SD scores energy originating from showers, in a cylinder around the particle
0051 direction and position in the calorimeter.
0052 Sensitive detector inherits from both base classes:
0053 - G4VSensitiveDetector: for processing of detailed/non-fast simulation hits
0054 - G4VFastSimSensitiveDetector: for processing of fast sim (G4FastSim) hits.
0055 Hits are placed in the same hit collection, with a different flag to distinguish
0056 between those originated in the full simulation, and those from the fast
0057 simulation.
0058 During visualisation, hits are represented as volumes of different colour:
0059 green for full simulation and red for fast simulation.
0060
0061 2.2. Par04ParallelFullSensitiveDetector
0062 ---------------------------------------
0063 This SD represents a physical readout structure to the detector (a regular grid).
0064 UI settings are available to set number of slices (azimuthal segmentation) and number
0065 of rows (segmentation along beam axis). Number of layers cannot be changed as it
0066 corresponds to the number of layers placed at the detector construction time. Only
0067 deposits in the active (sensitive) layers are scored in this SD.
0068
0069 2.2. Par04ParallelFastSensitiveDetector
0070 ---------------------------------------
0071 This SD represents a physical readout that takes into account deposits originating
0072 from fast simulation, so cells span over active and passive layers. This allows to
0073 account all energy from the parameterisation.
0074
0075 3. Primary generation
0076 ---------------------
0077
0078 Particle gun is used as a primary generator. 10 GeV electron is used by default.
0079 By default particles are generated along y axis. Those values
0080 can be changed using /gun/ UI commands.
0081
0082 4. Physics List
0083 ---------------
0084
0085 FTFP_BERT modular physics list is used. On top of it, fast simulation physics
0086 is registered for selected particles (electrons, positrons).
0087
0088
0089 5. User actions
0090 ----------------------------------------------------------
0091
0092 - Par04RunAction : run action used for initialization and termination
0093 of the run. Histograms for analysis of shower development
0094 in the detector are created.
0095
0096 - Par04EventAction : event action used for initialization and termination
0097 of the event. Analysis of shower development is performed
0098 on event-by-event basis.
0099
0100 6. ML Inference
0101 ----------------------------------------------------------
0102 - Par04MLFastSimModel : model used for parametrisation of electrons, positrons,
0103 and gammas. Energy is deposited and
0104 distributed according to inferred values from the ML model.
0105 This class triggers the inference setup, asks for values,
0106 and deposits energies at given positions.
0107
0108 - Par04InferenceSetup : this class is used to initialize the inference parameters
0109 (user application specific) such as the inference library,
0110 the path and name of the inference model and the size of
0111 the input inference vector(latent dimension and and condition size).
0112 This class constructs this vector and triggers the interface
0113 corresponding to the specified input inference library.
0114 After the inference, the post processing step consists of
0115 scaling back inferred values to the original range.
0116
0117 - Par04InferenceInterface : is a base class that allows to read in the ML model, configure
0118 and execute inference.
0119
0120 - Par04OnnxInference and Par04LWTNNInference and Par04TorchInference : inference library specific
0121 classes that inherit from the base class Par04InferenceInterface.
0122
0123
0124 7. Output
0125 ---------
0126
0127 The execution of the program (examplePar04) produces an output with histograms.
0128 Ntuples are also stored. They are not merged if the application is run on multiple threads.
0129
0130 The macro file examplePar04.mac is used to run full simulation. It will simulate 100
0131 events, for single 10 GeV electron beams.
0132 If CMake is able to find inference libraries (LWTNN and/or ONNX Runtime and/or LibTorch), a configuration
0133 macro will be available for that library (examplePar04_lwtnn.mac and/or examplePar04_onnx.mac
0134 and/or examplePar04_torch.mac). It will use a trained model to run inference and create showers
0135 in the detector by directly depositing energy.
0136
0137 8. How to build and run the example
0138 -----------------------------------
0139 - LWTNN, ONNX Runtime, and LibTorch are available on LCG. In order to use them, you can set a CMAKE_PREFIX_PATH:
0140 % source /cvmfs/sft.cern.ch/lcg/contrib/gcc/11.3.0/x86_64-centos7/setup.sh
0141 % 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>
0142
0143 - Compile and link to generate the executable (in your CMake build directory):
0144 % cmake <Par04_SOURCE>
0145 % make
0146
0147 - Execute the application (in batch mode):
0148 % ./examplePar04 -m examplePar04.mac
0149 which produces two root file for full simulation.
0150
0151 - Execute the application (in interactive mode):
0152 % ./examplePar04 -i -m vis.mac
0153 which allows to visualize hits (from full simulation).
0154
0155 - If ONNX Runtime is available:
0156 % ./examplePar04 -m examplePar04_onnx.mac
0157 For interactive mode with visualization:
0158 % ./examplePar04 -i -m vis_onnx.mac
0159
0160 - If LWTNN is available:
0161 % ./examplePar04 -m examplePar04_lwtnn.mac
0162 For interactive mode with visualization:
0163 % ./examplePar04 -i -m vis_lwtnn.mac
0164 - If LibTorch is available:
0165 % ./examplePar04 -m examplePar04_torch.mac
0166 For interactive mode with visualization:
0167 % ./examplePar04 -i -m vis_torch.mac
0168
0169 - Additional options available:
0170 % ./examplePar04 -m examplePar04.mac -r 0
0171 For serial run manager mode
0172 % ./examplePar04 -m examplePar04.mac -r 1 -t 8
0173 For multi-threaded run manager mode with 8 threads
0174 % ./examplePar04 -m examplePar04.mac -r 2
0175 For tasking run manager mode with number of tasks that can be change via env variable G4FORCE_EVENTS_PER_TASK
0176
0177
0178 By default, CMake will attempt to build fast simulation with ONNX Runtime and LWTNN. However, if none
0179 of those libraries is found, it will proceed with full simulation only. The search can be switched
0180 off manually switching CMake flag INFERENCE_LIB to OFF (-DINFERENCE_LIB=OFF)
0181
0182 9. Macros
0183 ---------
0184
0185 common_settings.mac - A macro with common settings, executed by all other macros (e.g. detector settings).
0186
0187 vis.mac - Allows to run visualization. Pass it to the example in interactive mode ("-i" passed to the executable).
0188 It can be used to visualize full simulation.
0189
0190 vis_onnx.mac - Allows to run visualization with ONNX Runtime inference. Pass it to the example in interactive mode
0191 ("-i" passed to the executable). It contains necessary settings of the inference.
0192
0193 vis_lwtnn.mac - Allows to run visualization with LWTNN inference. Pass it to the example in interactive mode
0194 ("-i" passed to the executable). It contains necessary settings of the inference.
0195
0196 vis_torch.mac - Allows to run visualization with LibTorch inference. Pass it to the example in interactive mode
0197 ("-i" passed to the executable). It contains necessary settings of the inference.
0198
0199 examplePar04.mac - Runs full simulation. It will run 100 events with single electrons, 10 GeV and
0200 along y axis.
0201
0202 examplePar04_onnx.mac - Available only if ONNX Runtime is found by CMake. Runs fast simulation with
0203 a NN stored in onnx file.
0204
0205 examplePar04_lwtnn.mac - Available only if LWTNN is found by CMake. Runs fast simulation with
0206 a NN stored in json file.
0207
0208 examplePar04_torch.mac - Available only if LibTorch is found by CMake. Runs fast simulation with
0209 a NN stored in pt file.
0210
0211 10. UI commands
0212 --------------
0213
0214 UI commands useful in this example:
0215
0216 - activation/disactivation of the fast simulation model:
0217 /param/ActivateModel inferenceModel
0218 /param/InActivateModel inferenceModel
0219
0220 - particle gun commands
0221 /gun/particle e-
0222 /gun/energy 10 GeV
0223 /gun/direction 0 1 0
0224 /gun/position 0 0 0
0225
0226 UI commands defined in this example:
0227 - detector settings
0228 /Par04/detector/setDetectorInnerRadius 80 cm
0229 /Par04/detector/setDetectorLength 2 m
0230 /Par04/detector/setNbOfLayers 90
0231 /Par04/detector/setAbsorber 0 G4_W 1.4 mm false
0232 /Par04/detector/setAbsorber 1 G4_Si 0.3 mm true
0233
0234 - readout mesh
0235 /Par04/mesh/setSizeOfRhoCells 2.325 mm
0236 /Par04/mesh/setSizeOfZCells 3.4 mm
0237 /Par04/mesh/setNbOfRhoCells 18
0238 /Par04/mesh/setNbOfPhiCells 50
0239 /Par04/mesh/setNbOfZCells 45
0240
0241 - inference setup
0242 /Par04/inference/setSizeLatentVector 10
0243 /Par04/inference/setSizeConditionVector 4
0244 /Par04/inference/setModelPathName MLModels/Generator.onnx
0245 /Par04/inference/setProfileFlag 0
0246 /Par04/inference/setOptimizationFlag 0
0247 /Par04/inference/setInferenceLibrary ONNX
0248 /Par04/inference/setSizeOfRhoCells 2.325 mm
0249 /Par04/inference/setSizeOfZCells 3.4 mm
0250 /Par04/inference/setNbOfRhoCells 18
0251 /Par04/inference/setNbOfPhiCells 50
0252 /Par04/inference/setNbOfZCells 45
0253
0254 11. Python scripts for training
0255 --------------
0256
0257 The scripts available in the training folder were used to firstly convert
0258 the ROOT files to the h5 files, preprocess the data and then train
0259 the VAE model of this example. More details can be found in
0260 training/README.
0261
0262
0263 12. Public data
0264 --------------
0265
0266 Data generated with full simulation with this example has been published on zenodo:
0267 https://doi.org/10.5281/zenodo.6082201
