learnergy 1.2.0__tar.gz → 2.0.1__tar.gz

learnergy-2.0.1/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: learnergy
+Version: 2.0.1
+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. Add it to a project managed by uv with:
+
+```bash
+uv add learnergy
+```
+
+Add the optional torchvision dependency to run the examples:
+
+```bash
+uv add "learnergy[examples]"
+```
+
+For a consumer installation in an existing Python environment, pip is also supported:
+
+```bash
+pip install learnergy
+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.
+
+### 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
+
+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.

learnergy-2.0.1/README.md

@@ -0,0 +1,131 @@
+# 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. Add it to a project managed by uv with:
+
+```bash
+uv add learnergy
+```
+
+Add the optional torchvision dependency to run the examples:
+
+```bash
+uv add "learnergy[examples]"
+```
+
+For a consumer installation in an existing Python environment, pip is also supported:
+
+```bash
+pip install learnergy
+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.
+
+### 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
+
+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.

{learnergy-1.2.0 → learnergy-2.0.1}/learnergy/__init__.py

@@ -2,4 +2,4 @@
 of several modules and sub-modules.
 """
 
-__version__ = "1.2.0"
+__version__ = "2.0.1"

{learnergy-1.2.0 → learnergy-2.0.1}/learnergy/core/__init__.py

@@ -1,5 +1,6 @@
-"""A core package for all common learnergy modules.
-"""
+"""Core model primitives."""
 
 from learnergy.core.dataset import Dataset
 from learnergy.core.model import Model
+
+__all__ = ["Dataset", "Model"]

learnergy-2.0.1/learnergy/core/dataset.py

@@ -0,0 +1,48 @@
+"""Dataset helpers."""
+
+from collections.abc import Callable
+
+import torch
+
+import learnergy.utils.exception as e
+from learnergy.core.model import _validated_property
+from learnergy.utils import logging
+
+logger = logging.get_logger(__name__)
+
+
+class Dataset(torch.utils.data.Dataset):
+    """Wrap samples and targets with an optional sample transform."""
+
+    data = _validated_property("data")
+    targets = _validated_property("targets")
+    transform = _validated_property(
+        "transform",
+        lambda _, value: value is None or callable(value),
+        e.TypeError,
+        "`transform` should be a callable or None",
+    )
+
+    def __init__(
+        self,
+        data,
+        targets,
+        transform: Callable | None = None,
+        show_log: bool = True,
+    ) -> None:
+        self.data = data
+        self.targets = targets
+        self.transform = transform
+
+        if show_log:
+            logger.info("Creating class: Dataset.")
+            logger.info("Class created.")
+
+    def __getitem__(self, idx: int):
+        sample = self.data[idx]
+        if self.transform:
+            sample = self.transform(sample)
+        return sample, self.targets[idx]
+
+    def __len__(self) -> int:
+        return len(self.data)

learnergy-2.0.1/learnergy/core/model.py

@@ -0,0 +1,58 @@
+"""Standard model-related implementation."""
+
+from collections.abc import Callable
+from typing import Any
+
+import torch
+
+import learnergy.utils.exception as e
+
+
+def _validated_property(
+    name: str,
+    validator: Callable[[Any, Any], bool] | None = None,
+    error: type[Exception] = ValueError,
+    message: str = "invalid value",
+) -> property:
+    storage_name = f"_{name}"
+
+    def getter(instance):
+        return getattr(instance, storage_name)
+
+    def setter(instance, value):
+        if validator is not None and not validator(instance, value):
+            raise error(message)
+        setattr(instance, storage_name, value)
+
+    return property(getter, setter)
+
+
+class Model(torch.nn.Module):
+    """Base class for Learnergy models."""
+
+    device = _validated_property(
+        "device",
+        lambda _, value: value in ("cpu", "cuda"),
+        e.TypeError,
+        "`device` should be `cpu` or `cuda`",
+    )
+    history = _validated_property("history")
+
+    def __init__(self, use_gpu: bool = False) -> None:
+        """Initialization method.
+
+        Args:
+            use_gpu: Whether GPU should be used or not.
+
+        """
+
+        super().__init__()
+        torch.set_default_dtype(torch.float32)
+        self.device = "cuda" if use_gpu and torch.cuda.is_available() else "cpu"
+        self.history = {}
+
+    def dump(self, **kwargs) -> None:
+        """Dumps any amount of keyword documents to lists in the history property."""
+
+        for k, v in kwargs.items():
+            self.history.setdefault(k, []).append(v)

learnergy-2.0.1/learnergy/math/__init__.py

@@ -0,0 +1 @@
+"""Mathematical helpers."""

learnergy-2.0.1/learnergy/math/metrics.py

@@ -0,0 +1,30 @@
+"""Image similarity metrics."""
+
+import torch
+from skimage.metrics import structural_similarity
+
+
+def calculate_ssim(v: torch.Tensor, x: torch.Tensor) -> float:
+    """Calculate the mean structural similarity of reconstructed images.
+
+    Args:
+        v: Reconstructed images, with each image flattened or shaped like its original.
+        x: Original grayscale images with shape (batch, height, width).
+
+    Raises:
+        ValueError: The batches contain different numbers of images.
+
+    """
+
+    originals = x.detach().cpu().numpy()
+    reconstructed = v.detach().cpu().numpy()
+    height, width = originals.shape[1:3]
+
+    return sum(
+        structural_similarity(
+            original,
+            rebuilt.reshape(height, width),
+            data_range=original.max() - original.min(),
+        )
+        for original, rebuilt in zip(originals, reconstructed, strict=True)
+    ) / len(reconstructed)

learnergy-2.0.1/learnergy/math/scale.py

@@ -0,0 +1,14 @@
+"""Scaling helpers."""
+
+import numpy as np
+
+from learnergy.utils.constants import EPSILON
+
+
+def unitary_scale(x: np.ndarray) -> np.ndarray:
+    """Scale an array to the interval from zero to one."""
+
+    scaled = x.astype("float32")
+    scaled -= scaled.min()
+    scaled /= scaled.max() + EPSILON
+    return scaled

{learnergy-1.2.0 → learnergy-2.0.1}/learnergy/models/__init__.py

@@ -1,2 +1 @@
-"""A package contaning subpackages of models for all common learnergy modules.
-"""
+"""A package contaning subpackages of models for all common learnergy modules."""

{learnergy-1.2.0 → learnergy-2.0.1}/learnergy/models/bernoulli/__init__.py

@@ -1,7 +1,5 @@
-"""A package contaning bernoulli-based models (networks) for all common learnergy modules.
-"""
+"""Bernoulli-valued RBM variants."""
 
-from learnergy.models.bernoulli.rbm import RBM
 from learnergy.models.bernoulli.conv_rbm import ConvRBM
 from learnergy.models.bernoulli.discriminative_rbm import (
     DiscriminativeRBM,
@@ -9,3 +7,14 @@ from learnergy.models.bernoulli.discriminative_rbm import (
 )
 from learnergy.models.bernoulli.dropout_rbm import DropConnectRBM, DropoutRBM
 from learnergy.models.bernoulli.e_dropout_rbm import EDropoutRBM
+from learnergy.models.bernoulli.rbm import RBM
+
+__all__ = [
+    "ConvRBM",
+    "DiscriminativeRBM",
+    "DropConnectRBM",
+    "DropoutRBM",
+    "EDropoutRBM",
+    "HybridDiscriminativeRBM",
+    "RBM",
+]