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_vae.mac and/or examplePar04_onnx_vae.mac
0134 and/or examplePar04_torch_vae.mac and/or examplePar04_onnx_calodit.mac and/or
0135 examplePar04_torch_calodit.mac). It will use a trained model to run inference and create showers
0136 in the detector by directly depositing energy.
0137
0138 There are two models available VAE and CaloDiT-2. CaloDiT-2 is a more sophisticated transformer-based
0139 diffusion model which gives much better accuracy, especially on the cell energy distribution, and
0140 also can be easily adapted to new detectors.
0141 Notes for CaloDiT-2; first, it operates on a lower granular cylindrical virtual mesh than VAE (which became
0142 from this release also the default for full simulation).
0143 Second, we do not support LWTNN inference, as PyTorch to LWTNN conversion is not straightforward.
0144
0145 8. How to build and run the example
0146 -----------------------------------
0147 - LWTNN, ONNX Runtime, and LibTorch are available on LCG. In order to use them, you can set a CMAKE_PREFIX_PATH:
0148 % source /cvmfs/sft.cern.ch/lcg/contrib/gcc/11.3.0/x86_64-centos7/setup.sh
0149 % 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>
0150
0151 - Compile and link to generate the executable (in your CMake build directory):
0152 % cmake <Par04_SOURCE>
0153 % make
0154
0155 - Execute the application (in batch mode):
0156 % ./examplePar04 -m examplePar04.mac
0157 which produces two root file for full simulation.
0158
0159 - Execute the application (in interactive mode):
0160 % ./examplePar04 -i -m vis.mac
0161 which allows to visualize hits (from full simulation).
0162
0163 - If ONNX Runtime is available:
0164 % ./examplePar04 -m examplePar04_onnx_vae.mac
0165 % ./examplePar04 -m examplePar04_onnx_calodit.mac
0166 For interactive mode with visualization:
0167 % ./examplePar04 -i -m vis_onnx_vae.mac
0168 % ./examplePar04 -i -m vis_onnx_calodit.mac
0169
0170 - If LWTNN is available:
0171 % ./examplePar04 -m examplePar04_lwtnn_vae.mac
0172 For interactive mode with visualization:
0173 % ./examplePar04 -i -m vis_lwtnn_vae.mac
0174
0175 - If LibTorch is available:
0176 % ./examplePar04 -m examplePar04_torch_vae.mac
0177 % ./examplePar04 -m examplePar04_torch_calodit.mac
0178 For interactive mode with visualization:
0179 % ./examplePar04 -i -m vis_torch_vae.mac
0180 % ./examplePar04 -i -m vis_torch_calodit.mac
0181
0182 - Additional options available:
0183 % ./examplePar04 -m examplePar04.mac -r 0
0184 For serial run manager mode
0185 % ./examplePar04 -m examplePar04.mac -r 1 -t 8
0186 For multi-threaded run manager mode with 8 threads
0187 % ./examplePar04 -m examplePar04.mac -r 2
0188 For tasking run manager mode with number of tasks that can be change via env variable G4FORCE_EVENTS_PER_TASK
0189
0190
0191 By default, CMake will attempt to build fast simulation with ONNX Runtime and LWTNN. However, if none
0192 of those libraries is found, it will proceed with full simulation only. The search can be switched
0193 off manually switching CMake flag INFERENCE_LIB to OFF (-DINFERENCE_LIB=OFF)
0194
0195 9. Macros
0196 ---------
0197
0198 common_settings_lowgran.mac - A macro with common settings, executed by all other macros that use low granularity
0199 (e.g. detector settings). This can be used directly by fast simulation, and for full sim
0200 the sensitivity of absorber must be set to false (it's done in examplePar04.mac or vis.mac).
0201
0202 common_settings_highgran.mac - A macro with common settings, executed by all other macros that use high granularity
0203 (e.g. detector settings). This can be used directly by fast simulation, and for full sim
0204 the sensitivity of absorber must be set to false.
0205
0206 common_settings_vis.mac - A macro with common settings, executed by all visualisation macros.
0207
0208 common_settings_postInit.mac - A macro with common settings, executed after initialization, e.g. for particle gun settings.
0209
0210 vis.mac - Allows to run visualization. Pass it to the example in interactive mode ("-i" passed to the executable).
0211 It can be used to visualize full simulation. Lower granularity is used for visualisation. To be compared to CaloDiT-2.
0212
0213 vis_onnx_vae.mac - Allows to run visualization with ONNX Runtime inference using VAE. Pass it to the example in interactive mode
0214 ("-i" passed to the executable). It contains necessary settings of the inference.
0215
0216 vis_lwtnn_vae.mac - Allows to run visualization with LWTNN inference using VAE. Pass it to the example in interactive mode
0217 ("-i" passed to the executable). It contains necessary settings of the inference.
0218
0219 vis_torch_vae.mac - Allows to run visualization with LibTorch inference using VAE. Pass it to the example in interactive mode
0220 ("-i" passed to the executable). It contains necessary settings of the inference.
0221
0222 examplePar04.mac - Runs full simulation. It will run 100 events with single electrons, 10 GeV and
0223 along y axis. Lower granularity is used, to be compared with CaloDiT-2.
0224
0225 examplePar04_onnx_vae.mac - Available only if ONNX Runtime is found by CMake. Runs fast simulation with
0226 a NN stored in onnx file for VAE.
0227
0228 examplePar04_lwtnn_vae.mac - Available only if LWTNN is found by CMake. Runs fast simulation with
0229 a NN stored in json file for VAE.
0230
0231 examplePar04_torch_vae.mac - Available only if LibTorch is found by CMake. Runs fast simulation with
0232 a NN stored in pt file for VAE.
0233
0234 vis_onnx_calodit.mac - Allows to run visualization with ONNX Runtime inference using CaloDiT-2.
0235
0236 vis_torch_calodit.mac - Allows to run visualization with LibTorch inference using CaloDiT-2.
0237
0238 examplePar04_onnx_calodit.mac - Available only if ONNX Runtime is found by CMake. Runs fast simulation with
0239 a NN stored in onnx file for CaloDiT-2.
0240
0241 examplePar04_torch_calodit.mac - Available only if LibTorch is found by CMake. Runs fast simulation with
0242 a NN stored in pt file for CaloDiT-2.
0243
0244 10. UI commands
0245 --------------
0246
0247 UI commands useful in this example:
0248
0249 - activation/disactivation of the fast simulation model:
0250 /param/ActivateModel inferenceModel
0251 /param/InActivateModel inferenceModel
0252
0253 - particle gun commands
0254 /gun/particle e-
0255 /gun/energy 10 GeV
0256 /gun/direction 0 1 0
0257 /gun/position 0 0 0
0258
0259 UI commands defined in this example:
0260 - detector settings
0261 /Par04/detector/setDetectorInnerRadius 80 cm
0262 /Par04/detector/setDetectorLength 2 m
0263 /Par04/detector/setNbOfLayers 90
0264 /Par04/detector/setAbsorber 0 G4_W 1.4 mm false
0265 /Par04/detector/setAbsorber 1 G4_Si 0.3 mm true
0266
0267 - readout mesh
0268 /Par04/mesh/setSizeOfRhoCells 2.325 mm # (4.65 for CaloDiT-2)
0269 /Par04/mesh/setSizeOfZCells 3.4 mm
0270 /Par04/mesh/setNbOfRhoCells 18 # (9 for CaloDiT-2)
0271 /Par04/mesh/setNbOfPhiCells 50 # (16 for CaloDiT-2)
0272 /Par04/mesh/setNbOfZCells 45
0273
0274 - inference setup
0275 /Par04/inference/setSizeLatentVector 10
0276 /Par04/inference/setSizeConditionVector 4
0277 /Par04/inference/setModelPathName MLModels/Generator.onnx # (or cd.onnx for CaloDiT-2)
0278 /Par04/inference/setProfileFlag 0
0279 /Par04/inference/setOptimizationFlag 0
0280 /Par04/inference/setInferenceLibrary ONNX
0281 /Par04/inference/setSizeOfRhoCells 2.325 mm # (4.65 for CaloDiT-2)
0282 /Par04/inference/setSizeOfZCells 3.4 mm
0283 /Par04/inference/setNbOfRhoCells 18 # (9 for CaloDiT-2)
0284 /Par04/inference/setNbOfPhiCells 50 # (16 for CaloDiT-2)
0285 /Par04/inference/setNbOfZCells 45
0286
0287 11. Python scripts for training
0288 --------------
0289
0290 The scripts available in the training folder were used to firstly convert
0291 the ROOT files to the h5 files, preprocess the data and then train
0292 the VAE model of this example. More details can be found in
0293 training_vae/README.
0294
0295 For CaloDiT-2 training and adaptation to new detectors, refer training_calodit/README.
0296
0297
0298 12. Public data
0299 --------------
0300
0301 Data generated with full simulation with higher granularity, with this example has been published on zenodo:
0302 https://doi.org/10.5281/zenodo.6082201
0303 It was used (as well as VAE) for this publication:
0304 https://doi.org/10.1016/j.physletb.2023.138079
0305
0306 Data generated with low granularity (so-called dataset2) and high granularity (so-called dataset3) are
0307 released for the CaloChallenge:
0308 dataset2 (lowgran): https://doi.org/10.5281/zenodo.6366271
0309 dataset3 (highgran): https://doi.org/10.5281/zenodo.6366324