VSALUT

This repository provides the official implementation for the paper "VSALUT: A Lightweight Low-Dimensional VSA Classifier for Efficient Inference on FPGA". It extends the MicroVSA training code to support the LUT approximation and pruning techniques proposed in the VSALUT paper. Additionally, it includes scripts to generate Verilog code for seamless deployment on FPGA hardware.

Prerequisite

• Python >=3.8
• virtualenv
• Nvidia GPU (optional but recommended for model training)

Basic Usage

1. Create a Python virtual environment and install all dependencies

   $ virtualenv -p python3 venv
   $ source venv/bin/activate
   $ pip install -r requirements_minimal.txt
   

2. Generate sourcecode for MCU/FPGA deployment (pretrained models are available only for VSALUT)

   For MCU deployment (MicroVSA)

   # run `python model_converter.py -h` to view all options
   $ python model_converter.py -i result/har_d64_1 -o result/har_d64_1 -n har -dv 8

   For FPGA deployment (VSALUT)

   # run `python model_converter.py -h` to view all options
   $ python generate_verilog.py -i pretrained_model/mnist_i -o output_verilog -n mnist_i

Train your own model

Dataset Preparation

Note

To aid in the artifact evaluation process, we temporarily made all datasets available at this link. Simply download and replace the data directory with the version in the zip file, and skip the prepare_dataset.sh script.

1. PTB Diagnostic ECG Database (A free Kagger's account is required to download this dataset)

   1. Download the dataset from link
   2. Unzip and copy the ptbdb_normal.csv and ptbdb_abnormal.csv to data/ptb_ecg

2. Qualcomm Keyword Speech Dataset (A free Qualcomm developer network's account is required to download this dataset)

   1. Download the dataset from link
   2. Unzip and copy the qualcomm_keyword_speech_dataset directory to the data/qksd directory

3. UCI Human Activity Recognition Dataset

   1. Download the dataset from link
   2. Unzip the file UCI HAR Dataset.zip and copy the text file (.txt) under UCI HAR Dataset/train and UCI HAR Dataset/test to data/ucihar

4. Free Spoken Digit Dataset

   1. Download the dataset from link
   2. Unzip and copy the free-spoken-digit-dataset-1.0.10 directory to the data/fsdd directory

5. WIreless Sensor Data Mining

   1. Download the dataset from link
   2. Unzip and copy the WISDM_ar_v1.1 directory to the data/wisdm directory

6. ST multi-zone Time-of-Flight sensors hand posture recognition

   1. Download the dataset from link
   2. Unzip and copy the ST_VL53L8CX_handposture_dataset directory to the data/st_handpose directory

7. Microsoft Scalable Noisy Speech Dataset (Use to generate negative sample to train the model on the Qualcomm Keyword Speech Dataset)

   1. Download the dataset from link
   2. Unzip and copy the dataset directory to the data directory

8. UCI Spoken letter recognition (ISOLET)

   1. Download the dataset from link
   2. Unzip and copy the file isolet1+2+3+4.data and isolet5.data to the data/isolet directory

Final data directory structure

data/
    ptb_ecg/
        ptb_abnormal.csv
        ptb_normal.csv
    qksd/
        qualcomm_keyword_speech_dataset/
            hey_snapdragon/
            ...
    ucihar/
        X_train.txt
        y_train.txt
        X_test.txt
        y_test.txt
    fsdd/
        free-spoken-digit-dataset-1.0.10/
            acquire_data/
            recordings/
            ...
    widsm/
        WISDM_ar_v1.1/
    st_handpose/
        ST_VL53L8CX_handposture_dataset/
    MS-SNSD-master/
        clean_test/
        ...

Training and code generation

1. Create a Python virtual environment and install all dependencies

   $ virtualenv -p python3 venv
   $ source venv/bin/activate
   $ ./setup.sh
   

2. Run the script to generate the training/testing dataset

   $ ./prepare_dataset.sh
   

3. Train the model

   Option 1) automatically train some representative models (N rounds for each model) and report the best accuracy

   $ ./train.sh <N>
   

   Option 2) train a model on a specific dataset with custom parameters, e.g., the following command trains five MCU-optimized LDC models (Df = 64) on the UCI Human Activity Recognition Dataset. The training script saves all trained models in the result directory and reports the best accuracy

   # run `python train.py -h` to view all options
   $ python train.py -d har -n 5 -df 64

   The result directory contains the model in npy format, the training log (log.txt), and an image of the confusion matrix (result.png)

   data/
   preprocesssing/
   result/
       har_d64_1/
           C.npy
           F.npy
           V.npy
           log.txt
           result.png
       har_d64_2/
           ...
       ...
   ...
   

4. Convert the trained model to a C source and header file for deployment on the MCU

   # run `python model_converter.py -h` to view all options
   $ python model_converter.py -i result/har_d64_1 -o result/har_d64_1 -n har -dv 8