A clear, concise, simple yet powerful and efficient API for deep learning.

The Gluon API Specification

The Gluon API specification is an effort to improve speed, flexibility, and accessibility of deep learning technology for all developers, regardless of their deep learning framework of choice. The Gluon API offers a flexible interface that simplifies the process of prototyping, building, and training deep learning models without sacrificing training speed. It offers four distinct advantages:

  • Simple, Easy-to-Understand Code: Gluon offers a full set of plug-and-play neural network building blocks, including predefined layers, optimizers, and initializers.
  • Flexible, Imperative Structure: Gluon does not require the neural network model to be rigidly defined, but rather brings the training algorithm and model closer together to provide flexibility in the development process.
  • Dynamic Graphs: Gluon enables developers to define neural network models that are dynamic, meaning they can be built on the fly, with any structure, and using any of Python’s native control flow.
  • High Performance: Gluon provides all of the above benefits without impacting the training speed that the underlying engine provides.

Gluon API Reference

Getting Started with the Gluon Interface

The Gluon specification has already been implemented in Apache MXNet, so you can start using the Gluon interface by following these easy steps for installing the latest master version of MXNet. We recommend using Python version 3.3 or greater and implementing this example using a Jupyter notebook. Setup of Jupyter is included in the MXNet installation instructions. For our example we’ll walk through how to build and train a simple two-layer neural network, called a multilayer perceptron.

First, import mxnet and MXNet's implementation of the gluon specification. We will also need autograd, ndarray, and numpy.

import mxnet as mx
from mxnet import gluon, autograd, ndarray
import numpy as np

Next, we use gluon.data.DataLoader, Gluon's data iterator, to hold the training and test data. Iterators are a useful object class for traversing through large datasets. We pass Gluon's DataLoader a helper, gluon.data.vision.MNIST, that will pre-process the MNIST handwriting dataset, getting into the right size and format, using parameters to tell it which is test set and which is the training set.

train_data = mx.gluon.data.DataLoader(mx.gluon.data.vision.MNIST(train=True, transform=lambda data, label: (data.astype(np.float32)/255, label)),
                                      batch_size=32, shuffle=True)
test_data = mx.gluon.data.DataLoader(mx.gluon.data.vision.MNIST(train=False, transform=lambda data, label: (data.astype(np.float32)/255, label)),
                                     batch_size=32, shuffle=False)                     

Now, we are ready to define the actual neural network, and we can do so in five simple lines of code. First, we initialize the network with net = gluon.nn.Sequential(). Then, with that net, we create three layers using gluon.nn.Dense: the first will have 128 nodes, and the second will have 64 nodes. They both incorporate the relu by passing that into the activation function parameter. The final layer for our model, gluon.nn.Dense(10), is used to set up the output layer with the number of nodes corresponding to the total number of possible outputs. In our case with MNIST, there are only 10 possible outputs because the pictures represent numerical digits of which there are only 10 (i.e., 0 to 9).

# First step is to initialize your model
net = gluon.nn.Sequential()
# Then, define your model architecture
with net.name_scope():
    net.add(gluon.nn.Dense(128, activation="relu")) # 1st layer - 128 nodes
    net.add(gluon.nn.Dense(64, activation="relu")) # 2nd layer – 64 nodes
    net.add(gluon.nn.Dense(10)) # Output layer

Prior to kicking off the model training process, we need to initialize the model’s parameters and set up the loss with gluon.loss.SoftmaxCrossEntropyLoss() and model optimizer functions with gluon.Trainer. As with creating the model, these normally complicated functions are distilled to one line of code each.

# We start with random values for all of the model’s parameters from a
# normal distribution with a standard deviation of 0.05
net.collect_params().initialize(mx.init.Normal(sigma=0.05))

# We opt to use softmax cross entropy loss function to measure how well the # model is able to predict the correct answer
softmax_cross_entropy = gluon.loss.SoftmaxCrossEntropyLoss()

# We opt to use the stochastic gradient descent (sgd) training algorithm
# and set the learning rate hyperparameter to .1
trainer = gluon.Trainer(net.collect_params(), 'sgd', {'learning_rate': .1})

Running the training is fairly typical and all the while using Gluon's functionality to make the process simple and seamless. There are four steps: (1) pass in a batch of data; (2) calculate the difference between the output generated by the neural network model and the actual truth (i.e., the loss); (3) use Gluon's autograd to calculate the derivatives of the model’s parameters with respect to their impact on the loss; and (4) use the Gluon's trainer method to optimize the parameters in a way that will decrease the loss. We set the number of epochs at 10, meaning that we will cycle through the entire training dataset 10 times.

epochs = 10
for e in range(epochs):
    for i, (data, label) in enumerate(train_data):
        data = data.as_in_context(mx.cpu()).reshape((-1, 784))
        label = label.as_in_context(mx.cpu())
        with autograd.record(): # Start recording the derivatives
            output = net(data) # the forward iteration
            loss = softmax_cross_entropy(output, label)
            loss.backward()
        trainer.step(data.shape[0])
        # Provide stats on the improvement of the model over each epoch
        curr_loss = ndarray.mean(loss).asscalar()
    print("Epoch {}. Current Loss: {}.".format(e, curr_loss))

We now have a trained neural network model, and can see how the accuracy improves over each epoch.

A Jupyter notebook of this code has been provided for your convenience.

To learn more about the Gluon interface and deep learning, you can reference this comprehensive set of tutorials, which covers everything from an introduction to deep learning to how to implement cutting-edge neural network models.

License

Apache 2.0

Comments
  • RuntimeError when initializing parameters for GPU

    RuntimeError when initializing parameters for GPU

    Following docs from here: https://mxnet.incubator.apache.org/tutorials/gluon/gluon.html

    When initializing the parameters for the Net, switching to GPU context

    net = Net()
    net.collect_params().initialize(mx.init.Xavier(), ctx = mx.gpu(0))  #Xavier initialization
    data = mx.nd.random_normal(shape=(10,1,32,32)) #dummy data
    output = net(data)
    

    produces the following error:

    ---------------------------------------------------------------------------
    DeferredInitializationError               Traceback (most recent call last)
    /usr/local/lib/python3.5/dist-packages/mxnet-0.11.0-py3.5.egg/mxnet/gluon/block.py in forward(self, x, *args)
        403                 try:
    --> 404                     params = {i: j.data(ctx) for i, j in self._reg_params.items()}
        405                 except DeferredInitializationError:
    
    /usr/local/lib/python3.5/dist-packages/mxnet-0.11.0-py3.5.egg/mxnet/gluon/block.py in <dictcomp>(.0)
        403                 try:
    --> 404                     params = {i: j.data(ctx) for i, j in self._reg_params.items()}
        405                 except DeferredInitializationError:
    
    /usr/local/lib/python3.5/dist-packages/mxnet-0.11.0-py3.5.egg/mxnet/gluon/parameter.py in data(self, ctx)
        335                 ctx = context.current_context()
    --> 336         self._check_initialized(ctx)
        337         return self._data[ctx]
    
    /usr/local/lib/python3.5/dist-packages/mxnet-0.11.0-py3.5.egg/mxnet/gluon/parameter.py in _check_initialized(self, ctx)
        140         if self._deferred_init:
    --> 141             raise DeferredInitializationError
        142         raise RuntimeError(
    
    DeferredInitializationError: 
    
    During handling of the above exception, another exception occurred:
    
    RuntimeError                              Traceback (most recent call last)
    <ipython-input-5-f0503266db82> in <module>()
          3 
          4 data = mx.nd.random_normal(shape=(10,1,32,32)) #dummy data
    ----> 5 output = net(data)
    
    /usr/local/lib/python3.5/dist-packages/mxnet-0.11.0-py3.5.egg/mxnet/gluon/block.py in __call__(self, *args)
        266     def __call__(self, *args):
        267         """Calls forward. Only accepts positional arguments."""
    --> 268         return self.forward(*args)
        269 
        270     def forward(self, *args):
    
    <ipython-input-2-b23301fead94> in forward(self, x)
         11             self.fc3 = nn.Dense(10)
         12     def forward(self, x):
    ---> 13         x = self.pool1(F.relu(self.conv1(x)))
         14         x = self.pool2(F.relu(self.conv2(x)))
         15 
    
    /usr/local/lib/python3.5/dist-packages/mxnet-0.11.0-py3.5.egg/mxnet/gluon/block.py in __call__(self, *args)
        266     def __call__(self, *args):
        267         """Calls forward. Only accepts positional arguments."""
    --> 268         return self.forward(*args)
        269 
        270     def forward(self, *args):
    
    /usr/local/lib/python3.5/dist-packages/mxnet-0.11.0-py3.5.egg/mxnet/gluon/block.py in forward(self, x, *args)
        407                     for i in self.collect_params().values():
        408                         i._finish_deferred_init()
    --> 409                     params = {i: j.data(ctx) for i, j in self._reg_params.items()}
        410                 return self.hybrid_forward(ndarray, x, *args, **params)
        411 
    
    /usr/local/lib/python3.5/dist-packages/mxnet-0.11.0-py3.5.egg/mxnet/gluon/block.py in <dictcomp>(.0)
        407                     for i in self.collect_params().values():
        408                         i._finish_deferred_init()
    --> 409                     params = {i: j.data(ctx) for i, j in self._reg_params.items()}
        410                 return self.hybrid_forward(ndarray, x, *args, **params)
        411 
    
    /usr/local/lib/python3.5/dist-packages/mxnet-0.11.0-py3.5.egg/mxnet/gluon/parameter.py in data(self, ctx)
        334             else:
        335                 ctx = context.current_context()
    --> 336         self._check_initialized(ctx)
        337         return self._data[ctx]
        338 
    
    /usr/local/lib/python3.5/dist-packages/mxnet-0.11.0-py3.5.egg/mxnet/gluon/parameter.py in _check_initialized(self, ctx)
        136                     "Parameter %s was not initialized on context %s. "
        137                     "It was only initialized on %s."%(
    --> 138                         self.name, str(ctx), str(self.list_ctx())))
        139             return
        140         if self._deferred_init:
    
    RuntimeError: Parameter net2_conv0_weight was not initialized on context cpu(0). It was only initialized on [gpu(0)].
    
  • Gluon vs Keras comparison request

    Gluon vs Keras comparison request

    Why not Keras? Does MXNet even support Keras 2? Is there a comparison between Keras and Gluon? It's pretty obvious this is political and not a technological decision.

  • Can't find gluon.image.color_normalize() or gluon.nd.array()

    Can't find gluon.image.color_normalize() or gluon.nd.array()

    Hi folks,

    I'm using MXNet version 0.12.0 on Ubuntu and trying to follow the advice in docs/model_zoo.rst on image normalization:

    You can use gluon.image.color_normalize for such transformation:

    image = image/255
    normalized = gluon.image.color_normalize(image,
                                             mean=gluon.nd.array([0.485, 0.456, 0.406]),
                                             std=gluon.nd.array([0.229, 0.224, 0.225]))
    

    Unfortunately, I get errors such as the following:

    >>> from mxnet import gluon
    >>> test = gluon.nd.array([0.485, 0.456, 0.406])
    AttributeError: module 'mxnet.gluon' has no attribute 'nd'
    

    What am I doing wrong here? Thanks in advance!

  • Getting error in gluon model after training for 20 epochs

    Getting error in gluon model after training for 20 epochs

    Hi,

    I am using MXNet gluon module for implementing seq2seq attention based neural language correction. The model is training for 10 epochs and after that I am getting the following error:

    **"MXNetError: [19:12:27] include/mxnet/././tensor_blob.h:257: Check failed: this->shape_.Size() == shape.Size() (201 vs. 200) TBlob.get_with_shape: new and old shape do not match total elements **

    I am getting this error while printing the loss: l_sum += l.asscalar()

    Full stack trace:

    Stack trace returned 10 entries: [bt] (0) /usr/local/lib/python3.5/dist-packages/mxnet/libmxnet.so(+0x308362) [0x7efc4ffc0362] [bt] (1) /usr/local/lib/python3.5/dist-packages/mxnet/libmxnet.so(+0x308938) [0x7efc4ffc0938] [bt] (2) /usr/local/lib/python3.5/dist-packages/mxnet/libmxnet.so(+0x36ef49) [0x7efc50026f49] [bt] (3) /usr/local/lib/python3.5/dist-packages/mxnet/libmxnet.so(+0x280babc) [0x7efc524c3abc] [bt] (4) /usr/local/lib/python3.5/dist-packages/mxnet/libmxnet.so(+0x29c0926) [0x7efc52678926] [bt] (5) /usr/local/lib/python3.5/dist-packages/mxnet/libmxnet.so(+0x293e123) [0x7efc525f6123] [bt] (6) /usr/local/lib/python3.5/dist-packages/mxnet/libmxnet.so(+0x2946524) [0x7efc525fe524] [bt] (7) /usr/local/lib/python3.5/dist-packages/mxnet/libmxnet.so(+0x294a071) [0x7efc52602071] [bt] (8) /usr/local/lib/python3.5/dist-packages/mxnet/libmxnet.so(+0x2946beb) [0x7efc525febeb] [bt] (9) /usr/lib/x86_64-linux-gnu/libstdc++.so.6(+0xb8c80) [0x7efcc834cc80]

    I thought that one of the reason may be the memory issue. How to resolve this error.

    Model summary: Encoder has 2 LSTM layers with hidden size 200 Attention mechanism Decoder has 2 LSTM layers with hidden size 200 Maximum_Sequence_length = 200 Total training sentences: 12500

    Any suggestions on how to resolve this error…

    Thanks in advance, Harathi

  • proposal: enable gitter community for gluon-api repo?

    proposal: enable gitter community for gluon-api repo?

    It would be great to enable the 'gitter' feature for the gluon-api repo, similar to how mxnet has done here.

    To do this, you can:

    • sign into gitter.im with you github creds.
    • depending on what screen you are presented with, choose either the '+' icon in the bottom left, or the green 'create your own community' button
    • choose the green text link in 'do you want to start a community for one of your github projects?'
    • choose 'my repo' (or org if you want to do it for the whole gluon-api org account)
    • choose gluon-api repo
    • click through the rest of the process
  • Tried to run a CNN, but got exit code 132

    Tried to run a CNN, but got exit code 132

    I copied the code from the CNN tutorial and tried running it in PyCharm Community Version 2018.3.2, however I got this response in the console:

    Process finished with exit code 132 (interrupted by signal 4: SIGILL)
    

    Edit: I am using ctx = mx.cpu() and not gpu.

    I am running: Ubuntu 18.04 Python 3.6.7 PyCharm Community Version 2018.3.2

  • Not able to load MNIST Dataset

    Not able to load MNIST Dataset

    I am trying to run the example model on the readme, but I am getting an error when it hits the line that loads in the MNIST dataset. I tried loading in the dataset without any parameters from the python shell as well, but still no progress.

    >>> x = mx.gluon.data.vision.MNIST()
    Downloading /Users/IbrahimShaikh/.mxnet/datasets/train-images-idx3-ubyte.gz from http://data.mxnet.io/data/mnist/train-images-idx3-ubyte.gz...
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
      File "/usr/local/lib/python2.7/site-packages/mxnet/gluon/data/vision.py", line 75, in __init__
        super(MNIST, self).__init__(root, train, transform)
      File "/usr/local/lib/python2.7/site-packages/mxnet/gluon/data/vision.py", line 43, in __init__
        self._get_data()
      File "/usr/local/lib/python2.7/site-packages/mxnet/gluon/data/vision.py", line 83, in _get_data
        sha1_hash='6c95f4b05d2bf285e1bfb0e7960c31bd3b3f8a7d')
      File "/usr/local/lib/python2.7/site-packages/mxnet/gluon/utils.py", line 200, in download
        r = requests.get(url, stream=True)
    AttributeError: type object 'requests_failed_to_import' has no attribute 'get'
    
  • no attribute 'data'

    no attribute 'data'

    I am using the latest MXNet, and running the code in README.md, but get some error.

    pip list --format=legacy | grep mxnet
    mxnet (0.11.1b20171012)
    
    In [3]: train_data = mx.gluon.data.DataLoader(mx.gluon.data.vision.MNIST(train=True, transform=lambda data, label: (data.astype(np.float32)/255, label)),
       ...:                                       batch_size=32, shuffle=True)
       ...: test_data = mx.gluon.data.DataLoader(mx.gluon.data.vision.MNIST(train=False, transform=lambda data, label: (data.astype(np.float32)/255, label)),
       ...:                                      batch_size=32, shuffle=False)                     
       ...: 
    ---------------------------------------------------------------------------
    AttributeError                            Traceback (most recent call last)
    <ipython-input-3-03cccca34755> in <module>()
    ----> 1 train_data = mx.gluon.data.DataLoader(mx.gluon.data.vision.MNIST(train=True, transform=lambda data, label: (data.astype(np.float32)/255, label)),
          2                                       batch_size=32, shuffle=True)
          3 test_data = mx.gluon.data.DataLoader(mx.gluon.data.vision.MNIST(train=False, transform=lambda data, label: (data.astype(np.float32)/255, label)),
          4                                      batch_size=32, shuffle=False)                     
    
    AttributeError: 'module' object has no attribute 'data'
    
  • Typo in example

    Typo in example

    Hello. Just letting you know about a little typo in the "Getting Started with the Gluon Interface" example. The following line of code for i, batch in enumerate(train_data): from the README.md file example should be for i, (data, label) in enumerate(train_data): as shown in the Jupyter notebook.

  • How to read custom COCO annotations json?

    How to read custom COCO annotations json?

    I have a json file (with appropriate images) containing 'annotations' and 'images'. 'annotations' contains elements like this:

    {'area': 266.5, 'bbox': [306.0, 176.0, 22.0, 16.0], 'category_id': 1, 'id': 1, 'image_id': 1, 'iscrowd': 0, 'segmentation': [[306, 179
    , 311, 177, 320, 176, 326, 176, 328, 183, 323, 190, 319, 192, 307, 188]]}
    

    Is there a class in gluon to read this file and create a training dataset?

  • Added MNIST CNN notebook with Gluon

    Added MNIST CNN notebook with Gluon

    This pull request is for adding a Jupyter notebook, which shows the user how to implement a CNN using Gluon. This is taken from the Gluon documentation, and transferred to a runnable format.

  • Minor spelling correction

    Minor spelling correction

    Issue #, if available:

    Description of changes:

    By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

The pure and clear PyTorch Distributed Training Framework.
The pure and clear PyTorch Distributed Training Framework.

The pure and clear PyTorch Distributed Training Framework. Introduction Requirements and Usage Dependency Dataset Basic Usage Slurm Cluster Usage Base

May 13, 2022
CLEAR algorithm for multi-view data association
CLEAR algorithm for multi-view data association

CLEAR: Consistent Lifting, Embedding, and Alignment Rectification Algorithm The Matlab, Python, and C++ implementation of the CLEAR algorithm, as desc

Apr 13, 2022
Point Cloud Denoising input segmentation output raw point-cloud valid/clear fog rain de-noised Abstract Lidar sensors are frequently used in environme
Point Cloud Denoising input segmentation output raw point-cloud valid/clear fog rain de-noised Abstract Lidar sensors are frequently used in environme

Point Cloud Denoising input segmentation output raw point-cloud valid/clear fog rain de-noised Abstract Lidar sensors are frequently used in environme

May 17, 2022
A concise but complete implementation of CLIP with various experimental improvements from recent papers
A concise but complete implementation of CLIP with various experimental improvements from recent papers

x-clip (wip) A concise but complete implementation of CLIP with various experimental improvements from recent papers Install $ pip install x-clip Usag

May 16, 2022
A concise but complete implementation of CLIP with various experimental improvements from recent papers
A concise but complete implementation of CLIP with various experimental improvements from recent papers

x-clip (wip) A concise but complete implementation of CLIP with various experimental improvements from recent papers Install $ pip install x-clip Usag

Dec 9, 2021
A highly efficient, fast, powerful and light-weight anime downloader and streamer for your favorite anime.
A highly efficient, fast, powerful and light-weight anime downloader and streamer for your favorite anime.

AnimDL - Download & Stream Your Favorite Anime AnimDL is an incredibly powerful tool for downloading and streaming anime. Core features Abuses the dev

May 20, 2022
AdaShare: Learning What To Share For Efficient Deep Multi-Task Learning
AdaShare: Learning What To Share For Efficient Deep Multi-Task Learning

AdaShare: Learning What To Share For Efficient Deep Multi-Task Learning (NeurIPS 2020) Introduction AdaShare is a novel and differentiable approach fo

May 2, 2022
SeqTR: A Simple yet Universal Network for Visual Grounding
SeqTR: A Simple yet Universal Network for Visual Grounding

SeqTR This is the official implementation of SeqTR: A Simple yet Universal Network for Visual Grounding, which simplifies and unifies the modelling fo

May 16, 2022
Efficient-GlobalPointer - Pytorch Efficient GlobalPointer
Efficient-GlobalPointer - Pytorch Efficient GlobalPointer

引言 感谢苏神带来的模型,原文地址:https://spaces.ac.cn/archives/8877 如何运行 对应模型EfficientGlobalPoi

May 2, 2022
Yet Another Robotics and Reinforcement (YARR) learning framework for PyTorch.
Yet Another Robotics and Reinforcement (YARR) learning framework for PyTorch.

Yet Another Robotics and Reinforcement (YARR) learning framework for PyTorch.

Apr 19, 2022
YARR is Yet Another Robotics and Reinforcement learning framework for PyTorch.
YARR is Yet Another Robotics and Reinforcement learning framework for PyTorch.

Yet Another Robotics and Reinforcement (YARR) learning framework for PyTorch.

Aug 1, 2021
Yet Another Reinforcement Learning Tutorial

This repo contains self-contained RL implementations

May 5, 2022
A simple rest api serving a deep learning model that classifies human gender based on their faces. (vgg16 transfare learning)
A simple rest api serving a deep learning model that classifies human gender based on their faces. (vgg16 transfare learning)

this is a simple rest api serving a deep learning model that classifies human gender based on their faces. (vgg16 transfare learning)

Dec 9, 2021
DeepSpeed is a deep learning optimization library that makes distributed training easy, efficient, and effective.

DeepSpeed is a deep learning optimization library that makes distributed training easy, efficient, and effective.

May 16, 2022
A deep learning library that makes face recognition efficient and effective

Distributed Arcface Training in Pytorch This is a deep learning library that makes face recognition efficient, and effective, which can train tens of

Nov 23, 2021
An efficient and easy-to-use deep learning model compression framework
An efficient and easy-to-use deep learning model compression framework

TinyNeuralNetwork 简体中文 TinyNeuralNetwork is an efficient and easy-to-use deep learning model compression framework, which contains features like neura

May 19, 2022
Easy Parallel Library (EPL) is a general and efficient deep learning framework for distributed model training.
Easy Parallel Library (EPL) is a general and efficient deep learning framework for distributed model training.

English | 简体中文 Easy Parallel Library Overview Easy Parallel Library (EPL) is a general and efficient library for distributed model training. Usability

May 19, 2022
D2Go is a toolkit for efficient deep learning

D2Go D2Go is a production ready software system from FacebookResearch, which supports end-to-end model training and deployment for mobile platforms. W

May 18, 2022