Par04/training/README.md

0001 This repository contains the set of scripts used to train, generate and validate the generative model used
0002 in this example.
0003
0004 - root2h5.py: translation of ROOT file with showers to h5 files.
0005 - core/constants.py: defines the set of common variables.
0006 - core/model.py: defines the VAE model class and a handler to construct the model.
0007 - utils/preprocess.py: defines the data loading and preprocessing functions.
0008 - utils/hyperparameter_tuner.py: defines the HyperparameterTuner class.
0009 - utils/gpu_limiter.py: defines a logic responsible for GPU memory management.
0010 - utils/observables.py: defines a set of observable possibly calculated from a shower.
0011 - utils/plotter.py: defines plotting classes responsible for manufacturing various plots of observables.
0012 - train.py: performs model training.
0013 - generate.py: generate showers using a saved VAE model.
0014 - observables.py: defines a set of shower observables.
0015 - validate.py: creates validation plots using shower observables.
0016 - convert.py: defines the conversion function to an ONNX file.
0017 - tune_model.py: performs hyperparameters optimization.
0018
0019 ## Getting Started
0020
0021 `setup.py` script creates necessary folders used to save model checkpoints, generate showers and validation plots.
0022
0023 ```
0024 python3 setup.py
0025 ```
0026
0027 ## Full simulation dataset
0028
0029 The full simulation dataset can be downloaded from/linked to [Zenodo](https://zenodo.org/record/6082201#.Ypo5UeDRaL4).
0030
0031 If custom simulation is used, the output of full simulation must be translated to h5 files using `root2h5.py` script. Please see the header of that script to see what name of the root file is expected.
0032
0033 ## Training
0034
0035 In order to launch the training:
0036
0037 ```
0038 python3 train.py
0039 ```
0040
0041 You may specify those three following flags. If you do not, then default values will be used.
0042
0043 ```--max-gpu-memory-allocation``` specifies a maximum memory allocation on a single, logic GPU unit. Should be given as
0044 an integer.
0045
0046 ```--gpu-ids``` specifies IDs of physical GPUs. Should be given as a string, separated with comas, no spaces.
0047 If you specify more than one GPU then automatically ```tf.distribute.MirroredStrategy``` will be applied to the
0048 training.
0049
0050 ```--study-name``` specifies a study name. This name is used as an experiment name in W&B dashboard and as a name of
0051 directory for saving models.
0052
0053 ## Hyperparameters tuning
0054
0055 If you want to tune hyperparameters, specify in `tune_model.py` parameters to be tuned. There are three types of
0056 parameters: discrete, continuous and categorical. Discrete and continuous require range specification (low, high), while
0057 the categorical parameter requires a list of possible values to be chosen. Then run it with:
0058
0059 ```
0060 python3 tune_model.py
0061 ```
0062
0063 If you want to parallelize tuning process you need to specify a common storage (preferable MySQL database) by
0064 setting `--storage="URL_TO_MYSQL_DATABASE"`. Then you can run multiple processes with the same command:
0065
0066 ```
0067 python3 tune_model.py --storage="URL_TO_MYSQL_DATABASE"
0068 ```
0069
0070 Similarly to training procedure, you may specify ```--max-gpu-memory-allocation```, ```--gpu-ids``` and
0071 ```--study-name```.
0072
0073 ## ML shower generation (MLFastSim)
0074
0075 In order to generate showers using the ML model, use `generate.py` script and specify information of geometry, energy
0076 and angle of the particle and the epoch of the saved checkpoint model. The number of events to generate can also be
0077 specified (by default is set to 10.000):
0078
0079 ```
0080 python3 generate.py --geometry=SiW --energy=64 --angle=90 --epoch=1000 --study-name=YOUR_STUDY_NAME
0081 ```
0082
0083 If you do not specify an epoch number the based model (saved as ```VAEbest```) will be used for shower generation.
0084
0085 ## Validation
0086
0087 In order to validate the MLFastSim and the full simulation, use `validate.py` script and specify information of
0088 geometry, energy and angle of the particle:
0089
0090 ```
0091 python3 validate.py --geometry=SiW --energye=64 --angle=90
0092 ```
0093
0094 ## Conversion
0095
0096 After training and validation, the model can be converted into a format that can be used in C++, such as ONNX,
0097 use `convert.py` script:
0098
0099 ```
0100 python3 convert.py --epoch 1000
0101 ```