Installation

Table of Contents

1. Install Keras with MXNet backend
   1. CPU Setup
   2. GPU Setup
2. Configure Keras backend
3. Validate the Installation
4. Train a simple handwritten digit recognition model
5. Next Steps

1 Install Keras with MXNet backend

Warning Keras with MXNet backend is still in experimental Beta phase. You can view the detailed list of known issues and unsupported functionalities in the release notes here.

Steps involved

1. Install Keras dependencies - Numpy and Nose
2. Install CUDA and cuDNN - This is required only if you are installing on a GPU machine.
3. Install MXNet - https://github.com/apache/incubator-mxnet
4. Install Keras with MXNet backend - https://github.com/dmlc/keras

Note: The following installation instructions are tested on Ubuntu 14.04/16.04 and Mac OS EL Capitan and Sierra.

1.1 CPU Setup

Install dependencies

    $ pip install numpy --user
    $ pip install nose --user
    $ pip install nose-parameterized --user

Install MXNet

    $ pip install mxnet --user

Install Keras with MXNet backend

    $ pip install keras-mxnet --user

1.2 GPU Setup

Install dependencies

    $ pip install numpy --user
    $ pip install nose --user
    $ pip install nose-parameterized --user

Install CUDA and cuDNN

Install the following NVIDIA libraries to setup with GPU support:

1. Install CUDA 8.0 following the NVIDIA's installation guide.
2. Install cuDNN 5 for CUDA 8.0 following the NVIDIA's installation guide. You may need to register with NVIDIA for downloading the cuDNN library.

Note: Make sure to add CUDA install path to LD_LIBRARY_PATH.

For Example on Ubuntu machine, if you have downloaded CUDA debian package (cuda-repo-ubuntu1604_8.0.61-1_amd64.deb) and cuDNN 5.1 library (cudnn-8.0-linux-x64-v5.1.tgz), below are set of commands you run to setup CUDA and cuDNN.

#  Setup CUDA 8.0.
$  sudo apt-get update
$  sudo apt-get install build-essential
$  sudo apt-get install linux-headers-$(uname -r)
#  Assuming you have downloaded CUDA deb package from https://developer.nvidia.com/cuda-downloads
$  sudo dpkg -i cuda-repo-ubuntu1604_8.0.61-1_amd64.deb
$  sudo apt-get update
$  sudo apt-get install cuda

$  export CUDA_HOME=/usr/local/cuda-8.0
$  PATH=${CUDA_HOME}/bin:${PATH}
$  export PATH
$  export LD_LIBRARY_PATH=/usr/local/cuda/lib64/:$LD_LIBRARY_PATH

#  Setup cuDNN 5.1 for CUDA 8.0.
#  Assuming you have registered with NVIDA and downloaded cuDNN 5.1 for CUDA 8 from https://developer.nvidia.com/cudnn
$  tar -xvzf cudnn-8.0-linux-x64-v5.1.tgz
$  sudo cp cuda/include/cudnn.h /usr/local/cuda/include/
$  sudo cp cuda/lib64/* /usr/local/cuda/lib64/

You can verify your CUDA setup with following commands.

$  nvcc --version
$  nvidia-smi

Install MXNet

    # If you use CUDA8. If CUDA9, use, mxnet-cu90
    $ pip install mxnet-cu80

Install Keras with MXNet backend

    $ pip install keras-mxnet --user

2 Configure Keras backend

You should set Keras backend to 'mxnet' to run your Keras code with MXNet backend. You can either set the environment variable or edit the keras config file.

Option 1 Set the environment variable

    $ export KERAS_BACKEND=mxnet

Option 2 Edit the keras config file

Open "~/.keras/keras.json" file and set "backend=mxnet".

3 Validate the Installation

You can validate the installation by trying to import Keras in Python terminal and verifying that Keras is using mxnet backend.

    $ python
    >>> import keras as k
        Using mxnet backend

Next, get hands-on by training a simple Multi Layer Perceptron (MLP) model for handwritten digit recognition using MNIST dataset.

4 Train a simple handwritten digit recognition model

In this section, to verify the installation, let us get more hands on training a simple Multi Layer Perceptron (MLP) model for handwritten digit recognition using MNIST dataset.

dmlc/keras repository already consists of code to train the model. For simplicity, we only submit the model training job as a black box to see the training in action and do not focus on teaching what the model does.

    # Download the dmlc/keras code base.
    $ git clone --recursive https://github.com/dmlc/keras

    # Launch the model training job.
    $ python keras/examples/mnist_mlp.py

Your output should look something like below.

    Using MXNet backend.
    60000 train samples
    10000 test samples
    ____________________________________________________________________________________________________
    Layer (type)                     Output Shape          Param #     Connected to                     
    ====================================================================================================
    dense_1 (Dense)                  (None, 512)           401920      dense_input_1[0][0]              
    ____________________________________________________________________________________________________
    activation_1 (Activation)        (None, 512)           0           dense_1[0][0]                    
    ____________________________________________________________________________________________________
    dropout_1 (Dropout)              (None, 512)           0           activation_1[0][0]               
    ____________________________________________________________________________________________________
    dense_2 (Dense)                  (None, 512)           262656      dropout_1[0][0]                  
    ____________________________________________________________________________________________________
    activation_2 (Activation)        (None, 512)           0           dense_2[0][0]                    
    ____________________________________________________________________________________________________
    dropout_2 (Dropout)              (None, 512)           0           activation_2[0][0]               
    ____________________________________________________________________________________________________
    dense_3 (Dense)                  (None, 10)            5130        dropout_2[0][0]                  
    ____________________________________________________________________________________________________
    activation_3 (Activation)        (None, 10)            0           dense_3[0][0]                    
    ====================================================================================================
    Total params: 669,706
    Trainable params: 669,706
    Non-trainable params: 0
    ____________________________________________________________________________________________________
    Train on 60000 samples, validate on 10000 samples
    Epoch 1/20
    /home/ubuntu/.local/lib/python2.7/site-packages/mxnet/module/bucketing_module.py:368: UserWarning: Optimizer created manually outside Module but rescale_grad is not normalized to 1.0/batch_size/num_workers (1.0 vs. 0.0078125). Is this intended?
      force_init=force_init)
    60000/60000 [==============================] - 98s - loss: 1.2175 - acc: 0.6823 - val_loss: 0.5459 - val_acc: 0.8675
    Epoch 2/20
    43136/60000 [====================>.........] - ETA: 25s - loss: 0.5554 - acc: 0.8458 

Congratulations! You have successfully installed MXNet, Keras with MXNet backend and trained your first model!

5 Next Steps

• Read the Keras documentation at Keras.io.
• For more examples explore keras/examples directory.
• Tutorial on how to use multiple GPUs with MXNet backend - Multi GPU training with Keras and MXNet