Learnergy: Energy-based Machine Learners

Learnergy provides PyTorch implementations of Restricted Boltzmann Machines (RBMs) and Deep Belief Networks (DBNs) for unsupervised feature learning, generative modeling, and classification. It also includes dataset adapters, image-quality metrics, and visualization helpers.

Installation

Learnergy requires Python 3.11 or newer. Add it to a project managed by uv with:

uv add learnergy

Add the optional torchvision dependency to run the examples:

uv add "learnergy[examples]"

For a consumer installation in an existing Python environment, pip is also supported:

pip install learnergy
pip install "learnergy[examples]"

Quick start

import torch
from torch.utils.data import TensorDataset

from learnergy.models.bernoulli import RBM

samples = torch.bernoulli(torch.rand(1_024, 784))
targets = torch.zeros(1_024)
dataset = TensorDataset(samples, targets)

model = RBM(n_visible=784, n_hidden=128, learning_rate=0.1)
mse, pseudo_likelihood = model.fit(dataset, batch_size=128, epochs=5)
reconstruction_mse, reconstructed = model.reconstruct(dataset)

Stack RBMs into a DBN:

from learnergy.models.deep import DBN

model = DBN(
    model=("gaussian", "sigmoid"),
    n_visible=784,
    n_hidden=(256, 128),
    steps=(1, 1),
    learning_rate=(0.01, 0.01),
    momentum=(0, 0),
    decay=(0, 0),
    temperature=(1, 1),
)
model.fit(dataset, batch_size=128, epochs=(5, 5))

Available models

The learnergy.core.Dataset, learnergy.math, and learnergy.visual modules remain available for array-backed datasets, SSIM/scaling helpers, convergence plots, image mosaics, and tensor rendering.

See examples/applications for complete training and classification programs.

Numerical behavior

When enabled, Gaussian normalization uses statistics from the current batch, not stored training statistics. Batches of two or more samples use sample standard deviation; a singleton batch is centered to zero. Representations therefore depend on batch composition. Disable the corresponding normalization flags when supplying externally standardized features.

VarianceGaussianRBM.sigma is a learnable scale: the effective visible variance is sigma**2 plus a dtype-dependent epsilon. Its visible_sampling method returns conditional means followed by sampled states, and Gibbs sampling uses those states.

Gaussian convolutional representations support gradient-based fine-tuning. Use torch.no_grad() when extracting frozen features without an autograd graph.

The corrected variance-Gaussian sampling and stabilized likelihood calculations can change training trajectories, including with a fixed random seed.

Development

Follow the coding conventions when changing the library or its examples.

The repository uses uv for reproducible environments and packaging:

uv sync --locked
uv run pytest
uv build

Citation

@misc{roder2020learnergy,
    title={Learnergy: Energy-based Machine Learners},
    author={Mateus Roder and Gustavo Henrique de Rosa and João Paulo Papa},
    year={2020},
    eprint={2003.07443},
    archivePrefix={arXiv},
    primaryClass={cs.LG}
}

Support

Open an issue for bug reports and questions.