Gluon - Neural network building blocks¶

Gluon package is a high-level interface for MXNet designed to be easy to use while keeping most of the flexibility of low level API. Gluon supports both imperative and symbolic programming, making it easy to train complex models imperatively in Python and then deploy with symbolic graph in C++ and Scala.

# import dependencies
from __future__ import print_function
import numpy as np
import mxnet as mx
import mxnet.ndarray as F
import mxnet.gluon as gluon
from mxnet.gluon import nn
from mxnet import autograd

Neural networks (and other machine learning models) can be defined and trained with gluon.nn and gluon.rnn package. A typical training script has the following steps:

Define network
Initialize parameters
Loop over inputs
Forward input through network to get output
Compute loss with output and label
Backprop gradient
Update parameters with gradient descent.

Define Network¶

gluon.Block is the basic building block of models. You can define networks by composing and inheriting Block:

class Net(gluon.Block):
    def __init__(self, **kwargs):
        super(Net, self).__init__(**kwargs)
        with self.name_scope():
            # layers created in name_scope will inherit name space
            # from parent layer.
            self.conv1 = nn.Conv2D(6, kernel_size=5)
            self.pool1 = nn.MaxPool2D(pool_size=(2,2))
            self.conv2 = nn.Conv2D(16, kernel_size=5)
            self.pool2 = nn.MaxPool2D(pool_size=(2,2))
            self.fc1 = nn.Dense(120)
            self.fc2 = nn.Dense(84)
            self.fc3 = nn.Dense(10)

    def forward(self, x):
        x = self.pool1(F.relu(self.conv1(x)))
        x = self.pool2(F.relu(self.conv2(x)))
        # 0 means copy over size from corresponding dimension.
        # -1 means infer size from the rest of dimensions.
        x = x.reshape((0, -1))
        x = F.relu(self.fc1(x))
        x = F.relu(self.fc2(x))
        x = self.fc3(x)
        return x

Initialize Parameters¶

A network must be created and initialized before it can be used:

net = Net()
# Initialize on CPU. Replace with `mx.gpu(0)`, or `[mx.gpu(0), mx.gpu(1)]`,
# etc to use one or more GPUs.
net.initialize(mx.init.Xavier(), ctx=mx.cpu())

Note that because we didn’t specify input size to layers in Net’s constructor, the shape of parameters cannot be determined at this point. Actual initialization is deferred to the first forward pass, i.e. if you access net.fc1.weight.data() now an exception will be raised.

You can actually initialize the weights by running a forward pass:

data = mx.nd.random_normal(shape=(10, 1, 32, 32))  # dummy data
output = net(data)

Or you can specify input size when creating layers, i.e. nn.Dense(84, in_units=120) instead of nn.Dense(84).

Loss Functions¶

Loss functions take (output, label) pairs and compute a scalar loss for each sample in the mini-batch. The scalars measure how far each output is from the label.

There are many predefined loss functions in gluon.loss. Here we use softmax_cross_entropy_loss for digit classification.

To compute loss and backprop for one iteration, we do:

label = mx.nd.arange(10)  # dummy label
with autograd.record():
    output = net(data)
    L = gluon.loss.SoftmaxCrossEntropyLoss()
    loss = L(output, label)
    loss.backward()
print('loss:', loss)
print('grad:', net.fc1.weight.grad())

Updating the weights¶

Now that gradient is computed, we just need to update the weights. This is usually done with formulas like weight = weight - learning_rate * grad / batch_size. Note we divide gradient by batch_size because gradient is aggregated over the entire batch. For example,

lr = 0.01
for p in net.collect_params().values():
    p.data()[:] -= lr / data.shape[0] * p.grad()

But sometimes you want more fancy updating rules like momentum and Adam, and since this is a commonly used functionality, gluon provide a Trainer class for it:

trainer = gluon.Trainer(net.collect_params(), 'sgd', {'learning_rate': 0.01})

with autograd.record():
    output = net(data)
    L = gluon.loss.SoftmaxCrossEntropyLoss()
    loss = L(output, label)
    loss.backward()

# do the update. Trainer needs to know the batch size of data to normalize
# the gradient by 1/batch_size.
trainer.step(data.shape[0])

gluon.ipynb