Package: deepmem
DeepMEMThis repository contains the code that was used for the IRIS-HEP Fellowship project:Deep Learning Implementations for Sustainable Matrix Element Method Calculations.Project DescriptionThe Matrix Element Method (MEM) is a powerful statistical analysis technique for experimental and simulated particle physics data. It has several benefits over black-box methods like neural networks, owing to its transparent and interpretable results. The drawback of MEM; however, is the significant amount of computationally intensive calculations involved in its execution, which impedes research that relies on it. This project aims to improve the viability of MEM, by implementing deep learning techniques to accurately and efficiently approximate MEM calculations - providing the much required speedup over the traditional approach, while preserving its interpretability. The implemented model can be used as a good approximation during the exploratory phase of research, and the full ME calculations can be used for the final runs, making the workflow for research involving MEM much more efficient.InstallationFrom PyPIdeepmemis distributed onPyPIand can be installed in your Python virtual environment withpip$python-mpipinstalldeepmemFrom version controldeepmemcan also be installed from source by cloning a version of this repository and then from the top level of the repository locally installing in your Python virtual environment withpip$python-mpipinstall.Developers will probably want to create an editable install so their code changes are automatically picked up without having to reinstall$python-mpipinstall--editable.Requirements for deploymentThe code is stable in python 3.8.5. Use therequirements.txtfile to install the dependencies usingpipor package installer of choice.Explanation of inputsTo run this code simply rundeepmemwith the required shell arguments and input file modifications.The code takes two types of inputs:Through an JSON input file (e.g.:input_files/input.json): This is supposed to have inputs that do not require dynamimc user changes, i.e, during the training/optimization phase these will remain mostly constant.Through shell arguments (e.g. deepmem--device=0): These are inputs that would usually require dynamic user changes before running the code.Examples:Go through the input file atinput_files/input.jsonand modify the paths to the data, where to save and load models, scalers, etc.
Then run the following code to train the model on the options in theinput_files/input.jsonusing the0th numbered CUDA GPUfor50 epochs:$deepmem--device=0--epochs=50--mode=trainThereafter run the following code to run the testing phase once again using the options in theinput_files/input.jsonusing the0th numbered CUDA GPUfor inference:$deepmem--device=0--mode=testIt should save a histogram with a visual explanation of the model performance inpost/histogram.png(path can be changed in input file)Shell Arguments Explanation:$deepmem--helpusage: deepmem [-h] [--loader LOADER] [--device DEVICE] [--epochs EPOCHS] [--inputfile INPUTFILE] [--mode MODE]optional arguments:-h, --help            show this help message and exit--loader LOADER--device DEVICE--epochs EPOCHS--inputfile INPUTFILE--mode MODE           'train' or 'test'Pass these todeepmemwhen running the code.--loader: [Default: hybridMT] Which dataloader implementation to use out of [inbuilt, hybrid, hybridMT]AT THE MOMENT ONLY hybridMT is properly supported. It loads all the data into memory and can be use for reasonably sized datasets (works comfortably with ~300k events on DGX)--device: [Default: None] Which numbered cuda device to use for training. UsingNonewill select the CPU instead (Not recommended)--epochs: [Default: 10] Number of epochs to train for--inputfile: [Default: input_files/input.json] Path to the input file--mode: [Default: train] Whether to run in training mode or testing modeInput File Options Explanation:input_paths :[list of strings] Contains paths to the .root files of the inputs (events data)output_paths :[list of strings] Contains paths to the .root files of the outputs (weights) corresponding to the inputs aboveinput_tree :[string] Specifies which tree/directory in the input file to parseoutput_tree :[string] Specifies which tree/directory in the output file to parseprefixes :[list of list of strings] Contains the prefixes to search for in the input file. Further explanation belowsuffixes :[list of list of strings] Contains the suffixes to search for in the input file. Further explanation belowfor example:If prefixes are [ ["lep1_"] , ["lep2_", "j1_"] , ["MET"] ] and suffixes are [ ["PT"] , ["PT", "Eta"] , ["", "_Phi"]] the dataloader wil load the following variables from the input filelep1_PT, "lep2_PT, lep2_Eta, j1_PT, j1_Eta, MET, MET_Phi. It is basically all combinations of prefixes and suffixes from lists at the same index.dir_name_processing :[boolean] [DEPRECATED]Further processing on the particle name string (if required) to identify particle directory.weights :[list of strings] Specifies the directory with weights associated with each eventbatch_size :[integer] Batch size hyperparameter for training. Relevant for--loader=hybrid and --loader=hybridMTchunk_entries :[integer] Specifies the number of entries in one loaded chunk. Only Relevant for--loader=hybridNOT RELEVANT FOR hybridMTshuffle :[boolean] Whether the loaded data needs to be shuffled. Relevant for--loader=hybrid and --loader=hybridMTsplit :[list of 3 ints] Training, Validation and Testing SplitKEEP THIS AT 8,1,1 for now since stability of other splits is still being determinedLearningRate :[float] Initial learning rate of the modelsave_lowest_loss_model_at :[string] Where to save model that achieved lowest loss during trainingsave_scaler_at :[string] Where to save scaler fit to the training data (during training)load_saved_model_from :[string] Where to load model that will be used during testing phaseload_scaler_from :[string] Where to load scaler that will be used during testing phase (should be the same scaler that was saved during training phase)save_testing_histogram_at :[string] Where to save final output histogram