Skip to content
Snippets Groups Projects
Commit 4d501f3c authored by hashimsharif's avatar hashimsharif
Browse files

Merge branch 'approx_hpvm_reorg_keras' of... 

Merge branch 'approx_hpvm_reorg_keras' of https://gitlab.engr.illinois.edu/llvm/hpvm into approx_hpvm_reorg_keras
parents 89391cae e1878ff6
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
hpvm/docs/KerasFrontend.md 0 → 100644
+ 191
− 0
View file @ 4d501f3c
# Keras Frontend
Install Keras Frontend after moving to directory `/hpvm/hpvm/projects/keras`
## Requirements
* python == 3.6.x
* pip >= 18
If your system uses a different Python version, we recommend using the conda environment `keras_python36.yml`. Install this using:
```
conda env create -f keras_python36.yml --name keras_python36
```
Activate the conda environment before installing the pip package (below) using:
```
conda activate keras_python36
```
**NOTE:** This step must be performed each time (for each shell process) the frontend is to be used.
## Installing the Keras Frontend Package
At the root of this project (`/projects/keras/`) install the Keras frontend pip package as:
```
pip3 install -e ./
```
**NOTE:** If you are using the conda environment, activate it prior to this step.
## Suppported Operations
List of supported operations and limitations are documented [here](../projects/keras/docs/Support.md)
# Keras Benchmarks
Run the Keras benchmarks under `hpvm/hpvm/test/dnn_benchmarks/keras`
## Download CNN Model Files
Prior to running the benchmarks, ensure you download the CNN model data (inputs and weights) if not done in automatic build script.
```
wget https://databank.illinois.edu/datafiles/o3izd/download -O model_params.tar.gz
tar -xf model_params.tar.gz
```
Move extracted `model_params` directory to `/test/dnn_benchmarks/model_params` (Benchmarks expect data at this location)
## Running Benchmaks
List of benchmarks and the expected accuracies:
| Benchmark | Accuracy |
| ----------- | ----------- |
| alexnet.py | 79.28 |
| alexnet2.py | 84.98 |
| alexnet_imagenet.py | 56.30 |
| lenet.py | 98.70 |
| mobilenet_cifar10.py | 84.42 |
| resnet18_cifar10.py | 89.56 |
| resnet50_imagenet.py | 75.10 |
| vgg16_cifar10.py | 89.96 |
| vgg16_cifar100.py | 66.50 |
| vgg16_imagenet.py | 69.46 |
### Synopsis
```
python3 ${BENCH_NAME}.py [hpvm_reload|keras_reload] [frontend] [compile]
```
**Command-line Parameters**
`hpvm_reload` : Reloads HPVM weights (`.bin` binary format used by HPVM weights - present in `model_params` download directory) from directory path specified in the `reload_dir` parameter set in code - this is described in "Parameters to Change in Code" (below).
`keras_reload`: Alternatively, reload weights in Keras `.h5` file format with path to file specified in `keras_model_file` described in "Parameters to Change in Code" (below).
`frontend`: Invokes the HPVM frontend and dumps weights (in HPVM `.bin` format) in the output directory specified. The parameters that control where data and source files are dumped are specified by parameters `data_dir` and `src_dir`, respectively. These are described below.
`compile`: Optional Parameter. When specified, it compiles the HPVM-C code generated by the frontend into an HPVM binary under the directory specified by `src_dir` (described below). If `src_dir` path exists, a unique directory (which appends a unique ID) is created.
The binary is built with the name `HPVM_binary`.
**NOTE:** Before running `HPVM_binary` necessary to set CUDA and CUDNN paths with:
```
source ${PATH_TO_YOUR_HPVM_ROOT}/hpvm/set_paths.sh
```
**Parameters to Change in Code**
The AlexNet source is commented with explanations on how to use the Keras frontend interface. AlexNet source is [here](https://gitlab.engr.illinois.edu/llvm/hpvm/-/blob/approx_hpvm_reorg_keras/hpvm/projects/keras/src/alexnet.py).
* `NAME`: Benchmark Name - Can be set to any desired value
* `reload_dir`: Path to directory from where to reload weights in HPVM format. This directory is used to reload weights if `hpvm_reload` command-line option is used.
* `keras_model_file`: Path to Keras .h5 model file to reload weigths from. Either of `reload_dir` or `keras_model_file` can be used.
`keras_model_file` is used when `keras_reload` commad-line parameter is used with the Benchmark script.
* `data_dir`: Directory to dump weights specified specified in [constructor](https://gitlab.engr.illinois.edu/llvm/hpvm/-/blob/approx_hpvm_reorg_keras/hpvm/projects/keras/src/Benchmark.py#L21)
* `src_dir`: Directory to dump ApproxHPVM sources in HPVM-C (C with HPVM compiler intrinsics) specified in [constructor](https://gitlab.engr.illinois.edu/llvm/hpvm/-/blob/approx_hpvm_reorg_keras/hpvm/projects/keras/src/Benchmark.py#L22)
* `num_classes`: number of output classes - dependent on the dataset used. For CIFAR10, `num_classes` is 10, CIFAR100 has 100 classes,
for ImageNet, number of classes is 1000.
* `batch_size`: This parameter controls the size of each batch that is processed in HPVM. The batch size should be kept as large as the GPU memory
can support. This parameter should be adapted according to the memory size of the deployed device.
### Using the Frontend with Custom (New) Benchmarks
Any new benchmarks must inherit from the commom parent `Benchmark` class
and override the virtual functions for building the model, training,
and data preprocessing. These methods are described below:
`def buildModel(self)`:
Constructs and returns a keras model
`def data_preprocess(self)`:
returns X_train, y_train, X_test, y_test, X_tuner, and y_tuner data (in that order):
These are described here:
* `X_train:` Training data (fp32) in NCHW format
* `y_train:` Training labels (int32)
* `X_test:` Testing/Evaluation data in NCHW format
* `y_test:` Testing/Evaluation labels
* `X_tuner:` Data to be used for autotuning
* `y_tuner:` Labels corresponding to tuning data
`def trainModel(self, model, X_train, y_train, X_test, y_test)`:
Trains the Keras model constructed in `buildModel` and is expected to return the
trained keras model - training parameters should be tuned here.
### Directly using Keras Frontend API
Alternate to extending the `Benchmark` class, users may directly invoke the Keras Frontend API. This can be done as:
```python
from keras_frontend.approxhpvm_translator import translate_to_approxhpvm
# Construct and train your Keras Model (or load pre-trained weights)
translate_to_approxhpvm(model, data_dir, src_dir, test_data, test_labels, tune_data, tune_labels, batch_size, num_classes)
```
## Running HPVM Binary
Run the `HPVM_binary` generated under the directory specified by `src_dir` (described above). Usage:
```
./HPVM_binary -t {test|tune} -c ${config_file_path}
```
`test|tune`: Runs with either tune (autotuning data) or test set (for evaluation)
`config_file_path`: Path to an HPVM tensor configuration file (includes approximation settings)
**NOTE:** The accuracy of the bennchmarks is dumped into a file named `final_accuracy` in the current working directory - this includes accuracy averaged across batches
## Automated Tests
`scripts/test_benchmarks.py` is an automated test script that evaluates the accuracy of each Benchmark in Keras and HPVM (after comilation using HPVM Compiler) and compares the accuracy of each binary to the known correct accuracy. Run from root of `/test/dnn_benchmarks/keras`:
```
python test_benchmarks.py
```
hpvm/projects/keras/README.md
+ 2
− 41
View file @ 4d501f3c
# Keras Frontend
## Requirements
* python == 3.6.x
* pip >= 18
If your system uses a different Python version, we recommend using the conda environment `keras_python36.yml`. Install this using:
```
conda env create -f keras_python36.yml --name keras_python36
```
Activate the conda environment before installing the pip package (below) using:
```
conda activate keras_python36
```
**NOTE:** This step must be performed each time (for each shell process) the frontend is to be used.
## Installing the Keras Frontend Package
At the root of this project (`/projects/keras/`) install the Keras frontend pip package as:
```
pip3 install -e ./
```
**NOTE:** If you are using the conda environment, activate it prior to this step.
## Keras Benchmarks
Keras benchmarks can be found [here](https://gitlab.engr.illinois.edu/llvm/hpvm/-/tree/approx_hpvm_reorg_keras/hpvm/test/dnn_benchmarks/keras)
## Suppported Operations
List of supported operations and limitations detailed in https://gitlab.engr.illinois.edu/llvm/hpvm/-/blob/approx_hpvm_reorg_keras/hpvm/projects/keras/docs/Support.md
# Keras Frontend
Instructions on installing and using the Keras Frontend can be found [**here**](../../docs/KerasFrontend.md)
hpvm/projects/keras/docs/Support.md
+ 17
− 3
View file @ 4d501f3c
## Supported Keras Operators
The Keras frontend supports `Sequential()` Keras models.
......@@ -27,14 +26,29 @@ The list of supported operations is as follows:
* Softmax operator should be the last operation in the CNN pipeline
* Softmax operation must be a separate operator (not specified as activation to another type of Keras operator). Example of what works:
```
```python
Activation ("softmax")
```
Example of what is NOT supported:
```
```python
Dense(num_classes, activation="softmax")
```
* For convolutions with stride > 1 `same` convolution is NOT supported. Explicitly add `ZeroPadding2D` layer before `Conv2D` or `DepthwiseConv2D` operators. Example of what does NOT work:
```python
Conv2D(num_filters, kernel_size = (3,3), strides = (2,2), padding = `same`)
```
Example of what works instead:
```python
# NOTE: Amount of padding varies with kernel sizes and strides
ZeroPadding2D(padding=(1,1), data_format = `channels_first`) # only support NCHW
Conv2D(num_filters, kernel_size = (3,3), strides = (2,2), padding = `valid`)
```
hpvm/test/dnn_benchmarks/keras/README.md
+ 1
− 190
View file @ 4d501f3c
# Keras Frontend
Install Keras Frontend after moving to directory `/hpvm/hpvm/projects/keras`
## Requirements
* python == 3.6.x
* pip >= 18
If your system uses a different Python version, we recommend using the conda environment `keras_python36.yml`. Install this using:
```
conda env create -f keras_python36.yml --name keras_python36
```
Activate the conda environment before installing the pip package (below) using:
```
conda activate keras_python36
```
**NOTE:** This step must be performed each time (for each shell process) the frontend is to be used.
## Installing the Keras Frontend Package
At the root of this project (`/projects/keras/`) install the Keras frontend pip package as:
```
pip3 install -e ./
```
**NOTE:** If you are using the conda environment, activate it prior to this step.
## Suppported Operations
List of supported operations and limitations detailed in https://gitlab.engr.illinois.edu/llvm/hpvm/-/blob/approx_hpvm_reorg_keras/hpvm/projects/keras/docs/Support.md
# Keras Benchmarks
Run the Keras benchmarks under `hpvm/hpvm/test/dnn_benchmarks/keras`
## Download CNN Model Files
Prior to running the benchmarks, ensure you download the CNN model data (inputs and weights) if not done in automatic build script.
```
wget https://databank.illinois.edu/datafiles/o3izd/download -O model_params.tar.gz
tar -xf model_params.tar.gz
```
Move extracted `model_params` directory to `/test/dnn_benchmarks/model_params` (Benchmarks expect data at this location)
## Running Benchmaks
List of benchmarks and the expected accuracies:
| Benchmark | Accuracy |
| ----------- | ----------- |
| alexnet.py | 79.28 |
| alexnet2.py | 84.98 |
| alexnet_imagenet.py | 56.30 |
| lenet.py | 98.70 |
| mobilenet_cifar10.py | 84.42 |
| resnet18_cifar10.py | 89.56 |
| resnet50_imagenet.py | 75.10 |
| vgg16_cifar10.py | 89.96 |
| vgg16_cifar100.py | 66.50 |
| vgg16_imagenet.py | 69.46 |
### Synopsis
```
python3 ${BENCH_NAME}.py [hpvm_reload|keras_reload] [frontend] [compile]
```
**Command-line Parameters**
`hpvm_reload` : Reloads HPVM weights ('.bin' binary format used in `model_params` found here: https://gitlab.engr.illinois.edu/llvm/hpvm/-/tree/approx_hpvm_reorg_keras/hpvm/test/dnn_benchmarks/model_params) from directory path specified in the `reload_dir` parameter set in code - this is described in "Parameters to Change in Code" (below).
`keras_reload`: Alternatively, reload weights in Keras `.h5` file format with path to file specified in `keras_model_file` described in "Parameters to Change in Code" (below).
`frontend`: Invokes the HPVM frontend and dumps weights (in HPVM `.bin` format) in the output directory specified. The parameters that control where data and source files are dumped are specified by parameters `data_dir` and `src_dir`, respectively. These are described below.
`compile`: Optional Parameter. When specified, it compiles the HPVM-C code generated by the frontend into an HPVM binary under the directory specified by `src_dir` (described below). If `src_dir` path exists, a unique directory (which appends a unique ID) is created.
The binary is built with the name `HPVM_binary`.
**NOTE:** Before running `HPVM_binary` necessary to set CUDA and CUDNN paths with:
```
source ${PATH_TO_YOUR_HPVM_ROOT}/hpvm/set_paths.sh
```
**Parameters to Change in Code**
The AlexNet source is commented with explanations on how to use the Keras frontend interface. AlexNet source is [here](https://gitlab.engr.illinois.edu/llvm/hpvm/-/blob/approx_hpvm_reorg_keras/hpvm/projects/keras/src/alexnet.py).
* `NAME`: Benchmark Name - Can be set to any desired value
* `reload_dir`: Path to directory from where to reload weights in HPVM format. This directory is used to reload weights if `hpvm_reload` command-line option is used.
* `keras_model_file`: Path to Keras .h5 model file to reload weigths from. Either of `reload_dir` or `keras_model_file` can be used.
`keras_model_file` is used when `keras_reload` commad-line parameter is used with the Benchmark script.
* `data_dir`: Directory to dump weights specified specified in [constructor](https://gitlab.engr.illinois.edu/llvm/hpvm/-/blob/approx_hpvm_reorg_keras/hpvm/projects/keras/src/Benchmark.py#L21)
* `src_dir`: Directory to dump ApproxHPVM sources in HPVM-C (C with HPVM compiler intrinsics) specified in [constructor](https://gitlab.engr.illinois.edu/llvm/hpvm/-/blob/approx_hpvm_reorg_keras/hpvm/projects/keras/src/Benchmark.py#L22)
* `num_classes`: number of output classes - dependent on the dataset used. For CIFAR10, `num_classes` is 10, CIFAR100 has 100 classes,
for ImageNet, number of classes is 1000.
* `batch_size`: This parameter controls the size of each batch that is processed in HPVM. The batch size should be kept as large as the GPU memory
can support. This parameter should be adapted according to the memory size of the deployed device.
### Using the Frontend with Custom (New) Benchmarks
Any new benchmarks must inherit from the commom parent `Benchmark` class
and override the virtual functions for building the model, training,
and data preprocessing. These methods are described below:
`def buildModel(self)`:
Constructs and returns a keras model
`def data_preprocess(self)`:
returns X_train, y_train, X_test, y_test, X_tuner, and y_tuner data (in that order):
These are described here:
* `X_train:` Training data (fp32) in NCHW format
* `y_train:` Training labels (int32)
* `X_test:` Testing/Evaluation data in NCHW format
* `y_test:` Testing/Evaluation labels
* `X_tuner:` Data to be used for autotuning
* `y_tuner:` Labels corresponding to tuning data
`def trainModel(self, model, X_train, y_train, X_test, y_test)`:
Trains the Keras model constructed in `buildModel` and is expected to return the
trained keras model - training parameters should be tuned here.
### Directly using Keras Frontend API
Alternate to extending the `Benchmark` class, users may directly invoke the Keras Frontend API. This can be done as:
```python
from keras_frontend.approxhpvm_translator import translate_to_approxhpvm
# Construct and train your Keras Model (or load pre-trained weights)
translate_to_approxhpvm(model, data_dir, src_dir, test_data, test_labels, tune_data, tune_labels, batch_size, num_classes)
```
## Running HPVM Binary
Run the `HPVM_binary` generated under the directory specified by `src_dir` (described above). Usage:
```
./HPVM_binary -t {test|tune} -c ${config_file_path}
```
`test|tune`: Runs with either tune (autotuning data) or test set (for evaluation)
`config_file_path`: Path to an HPVM tensor configuration file (includes approximation settings)
## Automated Tests
`scripts/test_benchmarks.py` is an automated test script that evaluates the accuracy of each Benchmark in Keras and HPVM (after comilation using HPVM Compiler) and compares the accuracy of each binary to the known correct accuracy. Run from root of `/test/dnn_benchmarks/keras`:
```
python test_benchmarks.py
```
Instructions on using the Keras benchmarks and the Keras Frontend can be found [**here**](../../../docs/KerasFrontend.md)
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment