Metadata-Version: 2.4
Name: learnergy
Version: 2.0.0
Summary: Energy-based machine learners built with PyTorch
Author-email: Mateus Roder <mateus.roder@unesp.br>, Gustavo de Rosa <gustavo.rosa@unesp.br>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/gugarosa/learnergy
Project-URL: Documentation, https://learnergy.readthedocs.io
Project-URL: Issues, https://github.com/gugarosa/learnergy/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.10.9
Requires-Dist: numpy>=2.0
Requires-Dist: Pillow>=8.1.2
Requires-Dist: scikit-image>=0.26.0
Requires-Dist: torch>=2.13.0
Provides-Extra: dev
Requires-Dist: pre-commit>=4.6.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=9; extra == "docs"
Provides-Extra: examples
Requires-Dist: torchvision>=0.9.0; extra == "examples"
Provides-Extra: tests
Requires-Dist: coverage>=7.10; extra == "tests"
Requires-Dist: pytest>=9.0.2; extra == "tests"
Dynamic: license-file

# Learnergy: Energy-based Machine Learners

[![Latest release](https://img.shields.io/github/release/gugarosa/learnergy.svg)](https://github.com/gugarosa/learnergy/releases)
[![CI](https://github.com/gugarosa/learnergy/actions/workflows/ci.yml/badge.svg)](https://github.com/gugarosa/learnergy/actions/workflows/ci.yml)
[![DOI](https://img.shields.io/badge/DOI-10.5281/zenodo.4390744-006DB9.svg)](https://doi.org/10.5281/zenodo.4390744)
[![License](https://img.shields.io/github/license/gugarosa/learnergy.svg)](LICENSE)

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.

```bash
pip install learnergy
```

Install the optional torchvision dependency to run the examples:

```bash
pip install "learnergy[examples]"
```

## Quick start

```python
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:

```python
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

| Family | Models |
|---|---|
| Bernoulli | `RBM`, `ConvRBM`, `DiscriminativeRBM`, `HybridDiscriminativeRBM`, `DropoutRBM`, `DropConnectRBM`, `EDropoutRBM` |
| Gaussian | `GaussianRBM`, `GaussianReluRBM`, `GaussianSeluRBM`, `VarianceGaussianRBM`, `GaussianConvRBM` |
| Extra | `SigmoidRBM` |
| Deep | `DBN`, `ConvDBN`, `ResidualDBN` |

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`](examples/applications) for complete training and
classification programs.

## Development

The repository uses [uv](https://docs.astral.sh/uv/) for reproducible
environments and packaging:

```bash
uv sync --locked
uv run pytest
uv build
```

## Citation

```bibtex
@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](https://github.com/gugarosa/learnergy/issues) for bug reports
and questions.
