diff --git a/README.md b/README.md index 991ad4e56b1abc916b19979c3f5d17f527dbe8ad..a03d61b44bc7337fe29cfbb37d9b828ce62c2c94 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ However, note that you can still use each module independently depending on your - \[OPTIONAL] Qt4 #### Readout -- Python3 interpreter +- Python3 interpreter (3.8.10) - NumPy (1.23.4) - Numba (0.56.4) - tqdm (4.64.1) @@ -37,24 +37,31 @@ However, note that you can still use each module independently depending on your ### Installation The code has been tested on Linux Ubuntu 20.04 LTS. -We provide an installation script for APT-based Linux distros: ```./install.sh``` - -In case you get any errors with a dependency, please use the same version as ours. - -#### CSNN +We provide an installation script for APT-based Linux distros: ```./install.sh``` +The installation consists of the following steps: +1. Install the CSNN requirements ``` sudo apt install --yes gcc g++ make cmake libatlas-base-dev libblas-dev libopenblas-dev liblapack-dev liblapacke-dev +``` +2. Compile the CSNN module +``` cd csnn/ && mkdir -p build/ && cd build/ && cmake ../ -DCMAKE_BUILD_TYPE=Release && make ``` -#### Readout +3. Install the Readout Python package ``` python3 -m pip install readout/ ``` +4. \[OPTIONAL] Install the other Python packages +``` +python3 -m pip install scikit_learn requests libsvm +``` + +In case you get any errors with a package, please try to use the same version as ours. ## Usage -The CSNN and Readout are designed to operate independently. -The typical running process comprises the following steps: +The CSNN and the Readout are designed to operate independently. +The typical running process is: 1. Train the CSNN with the training set and save its parameters. 2. Load the CSNN parameters, process each set (training, validation, test) and save their extracted feature maps. 3. Train the Readout with both training and validation feature maps, and save its parameters. @@ -74,7 +81,7 @@ cp mnist/*_test.bin mnist/with-val/ ### Train and test the SNN -The file `run.py` in the `scripts/` folder is used to train and test the SNN for a given dataset and configurations. +The file `scripts/run.py` is used to train and test the SNN for a given dataset and configurations. ``` python3 run.py <INPUT_DIR> <OUTPUT_DIR> <CONFIG_CSNN> <CONFIG_READOUT> [--seed=0] ``` @@ -84,12 +91,10 @@ For example, to train and test the SNN on MNIST: ``` python3 run.py ../datasets/mnist/with-val/ logs/mnist/example/ config/MNIST/csnn-3/csnn.json config/MNIST/csnn-3/sstdp.json ``` - -Note that all the scripts and configuration files in the `scripts/` folder were used in our experiments. ### Run the Readout only -The Readout module provides the Python package `spiking_readout` that can be easily employed for training a single-layer SNN on a specified dataset. +The Readout module provides the Python package `spiking_readout` that can be easily employed for training a single-layer fully-connected SNN on a specified dataset or input features. This script loads the MNIST dataset (see [here](https://pypi.org/project/python-mnist/)) and converts it to the Readout input format, which uses `SpikingDataset` objects: ```python @@ -148,7 +153,7 @@ Some naming conventions used in the code differ from the ones used in the paper: ## Known bugs -- Depending on your machine, results on CIFAR10 can slightly differ (not a significative difference though). It comes from the download/conversion process in `datasets/get_cifar10.py`. +- Depending on your machine, results on CIFAR-10 can slightly differ (not a significative difference though). It comes from the download/conversion process in `datasets/get_cifar10.py`. ## Acknowledgments