Learnergy: Energy-based Machine Learners

03/16/2020 ∙ by Mateus Roder, et al. ∙ unesp 56

Throughout the last years, machine learning techniques have been broadly encouraged in the context of deep learning architectures. An interesting algorithm denoted as Restricted Boltzmann Machine relies on energy- and probabilistic-based nature to tackle with the most diverse applications, such as classification, reconstruction, and generation of images and signals. Nevertheless, one can see they are not adequately renowned when compared to other well-known deep learning techniques, e.g., Convolutional Neural Networks. Such behavior promotes the lack of researches and implementations around the literature, coping with the challenge of sufficiently comprehending these energy-based systems. Therefore, in this paper, we propose a Python-inspired framework in the context of energy-based architectures, denoted as Learnergy. Essentially, Learnergy is built upon PyTorch for providing a more friendly environment and a faster prototyping workspace, as well as, possibility the usage of CUDA computations, speeding up their computational time.



There are no comments yet.


page 9

page 10

page 11

This week in AI

Get the week's most popular data science and artificial intelligence research sent straight to your inbox every Saturday.

1 Introduction

Artificial Intelligence (AI) has achieved considerable attention in the last years, mainly due to its capacity to explore and solve previously unsolvable problems. Pattern Recognition, Computer Vision, Natural Language Processing are some areas that have benefited from the advancements in AI and were able to achieve state-of-the-art results in a wide variety of tasks.

Another interesting topic denoted as Machine Learning deals explicitly with the design of algorithms that solve AI problems. The advancement of machine learning research enabled the resolution of common-daily issues, such as image classification, object recognition, text summarization, autonomous cars, biometric identification, among others. Furthermore, the compulsion of creating human alike models and solving computer-vision related tasks enhanced traditional machine learning methods into more sophisticated techniques, known as deep learning 


Nevertheless, machine learning and deep learning are highly susceptible to the data that it is feed with, being only reasonable when the dataset is accurately modeled, representing the real possibilities of the problem [Schmidt:18]. An additional problem regards when the dataset is not balanced, providing more samples that pertain to one class than another(s). Such a problem may vitiate the learning process and prompt the technique to better learn the most common class instead of adequately learning the whole dataset.

A recent technique that has attracted considerable spotlight is the Restricted Boltzmann Machine [Hinton:02]

(RBM), mainly due to its simple architecture and vast learning capability. The Restricted Boltzmann Machine is a stochastic network that deals with probabilities and physical concepts, such as entropy and energy. Moreover, it is capable of learning real data distributions and reconstructing the original data in different latent spaces 


, i.e., acting as an auto encoder-decoder and extracting new features from the data distribution. Notwithstanding, energy-based systems usually suffer from overfitting under the lack of data, causing premature convergence and poor generalization over unseen data. In order to overcome such a problem, different approaches can be highlighted, such as regularization, data augmentation, and hyperparameter fine-tuning.

One can perceive that there is a lack of energy-based open-sourced frameworks in the literature. There are only a few implementations that deal with RBMs, but none of them in a framework format. Moreover, they are inconsistent among themselves, implementing distinct learning algorithms from the one provided by Hinton et al. 

[Hinton:02]. Therefore, in this paper, we propose an open-source energy-based Machine Learning framework, called Learnergy111https://github.com/gugarosa/learnergy. Essentially, the idea is to provide a user-friendly environment to work with energy-based architectures by creating high-level methods and classes, removing from the user the burden of programming at a mathematical level. The main contributions of this paper are threefold: (i) to introduce an energy-based machine learning library in the Python language, (ii) to provide an easy-to-go implementation and user-friendly framework, and (iii) to fill the lack of research regarding energy-based machine learning techniques.

The remnant of this work is presented as follows. Section 2 discusses a revision over the literature, as well as some relevant frameworks in the context of energy-based machine learning techniques. Section 3 presents a theoretical background concerning Restricted Boltzmann Machines, Dropout-based Restricted Boltzmann Machines, and Deep Belief Networks. Section 4 introduces an overview of the Learnergy library, such as its architecture and included packages. Section 5 introduces more thorough concepts regarding Learnergy usage, such as installation, documentation, included examples, and unitary tests. Additionally, Section 6 presents an outline on how to work with the library, i.e., how to run predefined examples, and how to model a new learning procedure. Finally, Section 7 describes conclusions and future works.

2 Literature Review and Related Frameworks

Restricted Boltzmann Machines are fruitful approaches that attempt to tackle supervised and unsupervised problems. They offer an energy-based architecture inspired by probabilistic concepts that are capable of learning the probabilistic distribution of the training data and further interpreting unseen data. They are employed in a wide range of applications, such as collaborative filtering [Salakhutdinov:07], image reconstruction [Nair:10], classification [Larochelle:08], denoising [Tang:12], data generation [Ranzato:10], among others. For instance, Srivastava et al. [Srivastava:12] found out that RBMs are capable of learning real data distributions and reconstructing the original data in different latent spaces, i.e., acting as an auto encoder-decoder and extracting new features from the data distribution. Yosinski and Lipson [Yosinski:12]

highlighted some approaches for visualizing the behavior of a Restricted Boltzmann Machine during its learning procedure and provided an overview concerning its complexities comprehension. Thornton et al. proposed to address the RBM complexity using auto-learning tools, which combine parameter fine-tuning with feature selection techniques 

[Thornton:13]. Moreover, Li et al. [Li:16]

proposed an improved version of the RBM, the so-called “temperature-based RBM" (T-RBM), which employs a new temperature parameter during the learning process to manipulate the neurons’ activation.

Although some works in the literature foster the Restricted Boltzmann Machines, one might find it challenging to search for open-sourced frameworks. There are only a few implementations, such as https://github.com/yell/boltzmann-machines, https://github.com/echen/restricted-boltzmann-machines, https://github.com/artem-oppermann/Restricted-Boltzmann-Machine, and https://github.com/GabrielBianconi/pytorch-rbm, but none of them seems to be in a framework format, only loosely code that implements the RBMs. Additionally, there is some inconsistency between these packages, especially throughout the learning algorithm, where some of them use distinct versions from the one provided by Hinton et al. [Hinton:02]. Moreover, they lack documentation and test cases, which are useful in assisting users to understand the code and implement new methods and classes. Apart from that, we could find a C-based framework, denoted as LibDEEP222https://github.com/jppbsi/LibDEEP. Nevertheless, as the library is implemented in C language, it is not very easy to integrate with other frameworks or packages, as well as to use CUDA-based operations.

Therefore, Learnergy attempts to fill the gaps concerning energy-based machine learning frameworks. It is completely implemented in Python and PyTorch, providing optimized performance, CUDA-capable operations, and several gimmicks that help the computational burden. Furthermore, it has comprehensive documentation, test cases, several pre-loaded examples, commented lines, continuous integration, full-time maintenance, and support.

3 Theoretical Background

Before plunging into Learnergy’s library, we present a theoretical background about the Restricted Boltzmann Machines, Dropout Restricted Boltzmann Machines, and Deep Belief Networks.

3.1 Restricted Boltzmann Machines

Restricted Boltzmann Machines are stochastic neural networks based on energy principles guided by physical laws and characterized by energy, entropy, and temperature factors. Most of the time, these networks learn in an unsupervised fashion and are applicable to a wide variety of problems that range from image reconstruction, collaborative filtering, and feature extraction to pre-training deeper networks.

In terms of architecture, RBM contain a visible layer with units and a hidden layer with units. Additionally, a real-valued matrix models the weights between the visible and hidden neurons, where represents the connection between the visible unit and the hidden unit . Figure 1 describes the well-know vanilla RBM architecture.

Figure 1: Typical RBM network.

Let and be the binary visible and hidden units, respectively. The RBM energy function can be formulated as follows:


where and are the biases of visible and hidden units, respectively. Furthermore, one can compute the probability of a configuration as follows:


where the denominator normalizes the equation, standing for all possible configurations involving the visible and hidden units. Also, the probabilities of these units are updated as follows:





stands for the well-known sigmoid function. Essentially, an RBM learning algorithm pursues in estimating the values of

, and .

3.2 Dropout Restricted Boltzmann Machines

Considering the RBM model described in Section 3.1

, it is possible to extend it in a Dropout RBM with a simple binary random vector

. In this new architecture, stands for the activation of neurons in the hidden layer, where each variable contains the value (zero) with probability , independent of other variables , where . If equals to (zero), the hidden unit is temporarily dropped along with its connections, otherwise it is held. Figure 2 illustrates this procedure, where unit is shutoff.

Figure 2: The Dropout-based RBM architecture.

Notice that

is sampled from a Bernoulli distribution 

[Srivastava:14], which is re-sampled for every training batch. Therefore, a Dropout RBM network can be seen as a blend of several RBMs, each one using distinct subsets of their hidden layers.

As units were dropped from the hidden layer, Equation 3 can be rewritten as:


As we are training our model with different subsets, our weight matrix needs to be scaled at testing time, being multiplied by in order to adjust its weights. In short, after learning its parameters, the new weight matrix is obtained as:


3.3 Deep Belief Networks

Restricted Boltzmann Machines can be used as building blocks to create the so-called Deep Belief Networks [Hinton:06]. In short, they are composed of a group of stacked RBMs and trained greedily, i.e., each RBM does not acknowledge others throughout its learning process. Figure 3 describes a DBN architecture, where each RBM at a specific layer is the one portrayed in Figure 1.

One can observe that the DBN is a model composed of a visible and hidden layers, being the weight matrix of an RBM at layer . Additionally, the hidden units at layer are converted to input units in the layer . Although Figure 3 does not illustrate, there are also bias units for the visible and hidden layers.

Figure 3: The standard DBN architecture.

The learning method introduced by Hinton et al. [Hinton:06]

uses a fine-tuning procedure after training each RBM independently. Such optimization can be accomplished through Gradient Descent or Backpropagation algorithms. The optimization algorithm minimizes a fitness function, which is usually an error measure based on the output of an extra layer on top of the DBN’s architecture. Such a layer can be formed by logistic or softmax units in a classification task.

4 Learnergy

Learnergy’s structure is split into several packages, where each implements specific methods and classes. Figure 4 represents a summary of Learnergy’s architecture, while the next sections present each one of its packages within more details.

Figure 4: Flowchart of Learnergy’s architecture.

4.1 Core

The core package implements all of Learnergy’s parent classes. In other words, it serves as a building block for other classes, which may be needed when creating more complex structures. As portrayed in Figure 5, two modules compose the core package, as follows:

  • Dataset: The dataset is an extension of PyTorch’s class to deal with every possible input to the energy-based architectures;

  • Model: The model is an extension of PyTorch’s class with additional features, such as saving an object containing the history of the training.

Figure 5: Flowchart of Learnergy’s core package.

4.2 Math

Learnergy also offers a mathematical package in an attempt to facilitate the user’s prototype. It contains low-level implementations, such as the ones illustrated by Figure 6. Typically, some repeated functions that re-used throughout the library can be found in this package, such as:

  • Scale: Common-use scaling functions are defined in this module.

Figure 6: Flowchart of Learnergy’s math package.

4.3 Models

There are several approaches to be conducted when designing an energy-based architecture. Therefore, the models’ package provides the necessary blocks that compose these high-level abstractions. Currently, Learnergy offers seven types of energy-based architectures, which are illustrated by Figure 7 and described as follows:

  • DBN: Deep Belief Networks [Hinton:06];

  • DropoutRBM: Dropout Restricted Boltzmann Machines [Srivastava:14];

  • EDropoutRBM: Energy-based Dropout Restricted Boltzmann Machines;

  • GaussianRBM: Gaussian-Bernoulli Restricted Boltzmann Machines [Hinton:02];

  • RBM: Bernoulli-Bernoulli Restricted Boltzmann Machines [Hinton:02];

  • SigmoidRBM: Sigmoid-Bernoulli Restricted Boltzmann Machines;

  • VarianceGaussianRBM:

    Gaussian-Bernoulli Restricted Boltzmann Machines with Adaptive Variance 


Figure 7: Flowchart of Learnergy’s models package.

4.4 Utils

This package offers common functions that are shared across the library, as shown in Figure 8. The following modules are implemented in this package:

  • Constants: Constants are fixed values that do not alter across the library;

  • Exception: An exception module implements common errors and exceptions that might happen when invalid arguments are used;

  • Logging: Every invoked method is saved into a log file. The log helps detect potential errors, warnings, or even success messages.

Figure 8: Flowchart of Learnergy’s utils package.

4.5 Visual

Finally, we provide a visual-related package where one can plot mosaics, reconstructed images, or furnish convergence graphics. The visual package implements the following modules, which are also portrayed in Figure 9:

  • Image: Provides image-based methods for creating mosaics from the model’s weights;

  • Metrics: Allows users to input their history object in order to furnish metrics convergence graphics;

  • Tensor:

    Inspects a tensor and re-creates an image of it.

Figure 9: Flowchart of Learnergy’s visual package.

5 Using the Library

In this section, we explain how to install the Learnergy library, as well as the first actions to start working with it. Mainly, one can read its documentation or make usage of the already-included examples. Furthermore, there are implemented methods that handle unitary tests and assess if everything is running as expected.

5.1 Installation

First of all, we understand that things should be smooth instead of complicated. Therefore, Learnergy will eternally be the one-to-go package, from the very first installation to its future usage. Just perform the following command under the most favored Python environment (standard, conda, virtualenv):

pip install learnergy

As a matter of choice, it is possible to use the bleeding-edge version by cloning its repository and installing it:

pip install .

Learnergy’s single dependency is the PyTorch package, making it possible to be installed everywhere, despite the machine’s operational system.

5.2 Documentation

We present a fully documented reference333https://learnergy.readthedocs.io, including everything the library offers, to fulfill the desire for additional comprehension. One can understand within more depth the thoughts and policies behind Learnergy, such as its elementary classes, methods, and more. Therefore, Learnergy’s documentation is the absolute source to study how the library was produced or even learn how to improve it with contributions.

5.3 Available Examples

In the examples/ folder, we present example scripts for every package the library implements, as follows:

  • Core: create_dataset.py, create_model.py;

  • Math: unitary_scaling.py;

  • Models: create_dbn.py, create_dropout_rbm.py, create_e_dropout_rbm.py,
    create_gaussian_rbm.py, create_rbm.py, create_sigmoid_rbm.py,

  • Visual: create_weights_mosaic.py, plot_metrics.py, show_reconstructed_sample.py.

Each example presents high-level descriptions of predefined classes and methods. In other words, there are conventional explanations regarding how to instantiate each class and choose the most proper arguments.

5.4 Test Engines

Tests are designed to provide a robust analysis of the code. Therefore, Learnergy implements a variety of tests in an attempt to verify whether everything is running as required or not. Currently, we offer two ways to conduct the tests:

  • PyTest: By running the command pytest tests/, it performs the implemented tests and returns a log showing whether they succeeded or failed, as portrayed by Figure 10;

  • Coverage:, An additional extension to PyTest is the coverage module. Despite being almost identical to PyTest, it also outputs a report stating the code coverage, as represented by Figure 11. Its utilization is simple: coverage run -m pytest tests/ and coverage report -m.

Figure 10: Example of outputs generated by a PyTest running.
Figure 11: Example of code coverage by a Coverage running.

6 Practical Applications

In this section, we demonstrate how to perform an energy-based learning task with Learnergy, as well as quickly define the eight pre-loaded applications that are incorporated within the library.

6.1 Initial Steps

It is straightforward to use Learnergy’s packages after installation. One can find in the examples/applications folder eight rudimentary examples which show key points in the library implementations, as follows:

  • DBN training: dbn_training.py;

  • Dropout RBM training: dropout_rbm_training.py;

  • Energy-based Dropout RBM training: e_dropout_rbm_training.py;

  • Gaussian RBM training: gaussian_training.py;

  • Loading a pre-trained architecture: loading_pre_trained_model.py;

  • RBM training: rbm_training.py;

  • Sigmoid RBM training: sigmoid_rbm_training.py;

  • Variance Gaussian RBM training: variance_gaussian_rbm_training.py.

Each example is comprised of the following pipeline: loading the dataset, instantiating an architecture, fitting the training data, and reconstructing the testing data. Finally, after performing the learning process, it is possible to save the model in a disk-file for further inspection. Figure 12 illustrates the output information originated by a Learnergy execution.

Figure 12: Output logs generated by executing a Learnergy learning procedure.

The distinction between the provided scripts consists of the type of architecture. As for now, we offer seven distinct energy-based architectures, e.g., DBN, Dropout RBM, Energy-based Dropout RBM, Gaussian RBM, RBM, Sigmoid RBM, and Variance Gaussian RBM. Additionally, we offer a script for loading pre-trained models and performing further analysis.

6.2 Modeling a Learning Procedure

Some standard rules should be followed in order to model a new learning procedure. Firstly, the data should be loaded, which in this case, we will be loading a common dataset known as MNIST:

import torchvision
# Creating training and testing dataset
train = torchvision.datasets.MNIST(root=’./data’, train=True, download=True, transform=torchvision.transforms.ToTensor())
test = torchvision.datasets.MNIST(root=’./data’, train=False, download=True, transform=torchvision.transforms.ToTensor())

Afterward, we can instantiate an RBM architecture:

from learnergy.models.rbm import RBM
# Creating an RBM
model = RBM(n_visible=784, n_hidden=128, steps=1, learning_rate=0.1, momentum=0, decay=0, temperature=1, use_gpu=True)

Finally, we can fit the architecture and perform new reconstructions:

# Training an RBM
mse, pl = model.fit(train, batch_size=128, epochs=5)
# Reconstructing test set
rec_mse, v = model.reconstruct(test, batch_size=10000)

One can also persist in the model to disk using PyTorch’s saving function or even check its learning history.

import torch
# Saving model
torch.save(model, ’model.pth’)
# Checking the model’s history

7 Conclusions

In this article, we present an open-source Python-inspired library for handling energy-based machine learning architectures, known as Learnergy. Based upon an object-oriented criterion, Learnergy implements a modern yet straightforward framework, allowing users to prototype new energy-based architectures speedily.

The library implements a wide variety of energy-based architectures, such as Deep Belief Networks, Dropout Restricted Boltzmann Machines, Energy-based Dropout Restricted Boltzmann Machines, Gaussian-Bernoulli Restricted Boltzmann Machines, Bernoulli-Bernoulli Restricted Boltzmann Machines, Sigmoid-Bernoulli Restricted Boltzmann Machines, Gaussian-Bernoulli Restricted Boltzmann Machines with Adaptive Variance, as well as auxiliary classes and functions that assist the architectures’ workflow. Moreover, Learnergy provides a model-saving method, which can be used to pre-train models and retrieve knowledgeable insights about learning performance.

Concerning future works, we plan to offer more energy-based architectures, such as Deep Boltzmann Machines, as well as a more robust visual package, which will allow users to supply their saved models and furnish improved charts. Furthermore, we aim at improving our implementations by better exploring PyTorch’s mechanisms and possible bottlenecks.


The authors are grateful to São Paulo Research Foundation (FAPESP) grants #2013/07375-0, #2014/12236-1, #2019/02205-5 and #2019/07825-1, as well as CNPq grants #307066/2017-7 and #427968/2018-6.