Back to home page

EIC code displayed by LXR

 
 

    


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