# CONVOLUTIONAL KERNEL NETWORK
---
Re-implementation of Convolutional Kernel Network (CKN) from Mairal (2016)
in Python based on the TensorFlow framework ().
Authors: Ghislain Durif

Credits: Alberto Bietti, Dexiong Chen, Julien Mairal, Daan Wynen

Copyright: 2017 Inria

If you encounter any issue when installing or using the 'ckntf' package, you can
contact us at (for bug report, support, etc.).
---
The [ckntf](./ckntf) package is available under the BSD license. The additional
[miso_svm](./miso_svm), [spherical_kmeans](./spherical_kmeans) and
[whitening](./whitening) packages are available under the GPL-v3 license.
---
## Requirement:
* Python3.x
* Numpy, Scipy
* Tensorflow
* Python packages [miso_svm](./miso_svm), [spherical_kmeans](./spherical_kmeans)
and [whitening](./whitening) are required to run included tutorials and
examples. They are available in the corresponding sub-folders (and require
the MKL library that is available with the Anaconda Python distribution).
---
## Installation
You can check the dedicated [file](./doc/Install.md).

Regarding packages `miso_svm`, `spherical_kmeans` and `whitening`, you can
check the installation instructions in [miso_svm/README.md](./miso_svm/README.md),
[spherical_kmeans/README.md](./spherical_kmeans/README.md) and
[whitening/README.md](./whitening/README.md) respectively.
---
## Tutorial
**NB:** To run the tutorial, you need to download the Cifar10 data set
(either or both version):
* the pre-whitened version `cifar10_whitened.pkl` from
* the standard version `cifar10_batches` from
You can either directly put the file `cifar10_whitened.pkl` and
the directory `cifar10_batches` (after you extracted it
with the command `tar -zxvf cifar10_batches.tar.gz`) in
the `ckntf/data` sub-folder before installing the `ckntf` package
(with `python setup.py install`), or you can store them somewhere else on
your machine, and you will have to modify the tutorial examples (see
[unsupervised_example.py](./ckntf/tutorials/unsupervised_example.py) or
[supervised_example.py](./ckntf/tutorials/supervised_example.py))
to load the data with the correct path.
A tutorial is available as a sub-module [ckntf.tutorials](./ckntf/tutorials) and
a doc [page](./doc/Tutorials.md). To replicate the following results that
were presented in Mairal (2016), every details can be found on the dedicated
[page](./doc/Tutorials.md).

### Results
Reproduction of the results from Mairal (2016) with the 'ckntf' python package.
The results from the original paper (Mairal, 2016) were achieved using
some `cudnn`-based Matlab code available at
.
#### Unsupervised CKN
Here is a summary of the results regarding **unsupervised** CKN on
Cifar10 image data set, with online whitening but without data augmentation
and/or model averaging.
| Architectures | nb layers | nb filters | filter size | subsampling | sigma | Accuracy |
|:--------------|:---------:|:-------------:|:-------------:|:-----------:|:------------:|:--------:|
| (1) | 1 | 64 | 3x3 | 2 | 0.6 | ~68.0 |
| (2) | 2 | 64

256 | 3x3

2x2 | 2

6 | 0.6

0.6 | ~77.4 |
| (3) | 2 | 256

1024 | 3x3

2x2 | 2

6 | 0.6

0.6 | ~81.2 |
| (4) | 2 | 512

4096 | 3x3

2x2 | 2

6 | 0.6

0.6 | ~83.6 |
#### Supervised CKN
Regarding **supervised** CKN model training (without data augmentation),
the best results regarding prediction accuracy were achieved with a 14 layer
CKN model. Details about the architectures that were used can be found
[here](./ckntf/tutorials/supervised_example.py).
**NB:** The Matlab-based code was able to reach an accuracy of 90.5% with
the 14 layer model on the pre-whitened Cifar10 data set. For unknow reasons
(we did run extensive tests), the Tensorflow-based package 'ckntf' was only
able to reach an accuracy of 88.50%. However, for smaller architectures (such
as the 5 layer architecture defined in the tutorial), the 'ckntf' package was
able to exactly reproduce the results from the Matlab-based code (accuracy
of 81.5%).
---
## For developpers
(on GNU/Linux and MacOs only)
* To build/install/test the package, see:
```bash
./dev_command.sh help
```
---
## References
Mairal, J., 2016. End-to-end kernel learning with supervised convolutional
kernel networks, in: Advances in Neural Information Processing
Systems. pp. 1399–1407.