%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
If you find this code useful, please cite our work as:
Testolin, A., Stoianov, I., De Filippo De Grazia, M. and Zorzi, M. (in preparation).
"Deep unsupervised learning on a desktop PC: A primer for cognitive scientists".
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The code is not tied to the specific benchmark task and it can be easily adapted to other learning problems.
In order to maximize portability, all implementations assume to manipulate data stored in 3-D matrices of size x*y*z, where x is the mini-batch size, y is the input size (i.e., the number of visible units) and z is the total number of mini-batches.
We also provide instructions on how to run our codes on the popular MNIST example, which we used as a benchmark task.


Octave and MPITB (MPI library routines for Octave environment; download from http://atc.ugr.es/javier-bin/mpitb) must be properly installed on the cluster (tested: Octave 3.0.5, Open-MPI 1.4.3). Network and learning parameters can be directly set inside the script “deeptrain.m”. Running the script will train a deep belief net. At the end of the learning phase, a “.mat” file containing the results will be created into the source code directory. Note that the training data must be supplied as an additional “.mat” file (e.g., “MNIST_data_n.mat” for the MNIST example).



MNIST example: data preparation

The raw MNIST dataset must be first converted into a suitable format:

1. Download the following 4 files from http://yann.lecun.com/exdb/mnist
   * train-images-idx3-ubyte.gz
   * train-labels-idx1-ubyte.gz
   * t10k-images-idx3-ubyte.gz
   * t10k-labels-idx1-ubyte.gz

2. Unzip them by executing
   * gunzip train-images-idx3-ubyte.gz
   * gunzip train-labels-idx1-ubyte.gz
   * gunzip t10k-images-idx3-ubyte.gz
   * unzip t10k-labels-idx1-ubyte.gz
Make sure the file names have not been changed during unzipping (in particular, it can happen that “-” is replaced with “.”)

3. Convert the raw images into MATLAB/Octave format by copying them into the source code directory and running the routine “converter.m”. 

4. Save the training set into a suitable 3-D matrix by running the routine “makebatches.m” (mini-batch size can be set inside that file before running it). This will produce a file called “MNIST_data_n.mat”, where n is the chosen mini-batch size. 

