learnergy 2.0.0__tar.gz → 2.0.1__tar.gz

{learnergy-2.0.0 → learnergy-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learnergy
-Version: 2.0.0
+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
@@ -49,15 +49,22 @@ image-quality metrics, and visualization helpers.
 
 ## Installation
 
-Learnergy requires Python 3.11 or newer.
+Learnergy requires Python 3.11 or newer. Add it to a project managed by uv with:
 
 ```bash
-pip install learnergy
+uv add learnergy
+```
+
+Add the optional torchvision dependency to run the examples:
+
+```bash
+uv add "learnergy[examples]"
 ```
 
-Install the optional torchvision dependency to run the examples:
+For a consumer installation in an existing Python environment, pip is also supported:
 
 ```bash
+pip install learnergy
 pip install "learnergy[examples]"
 ```
 
@@ -112,6 +119,25 @@ 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

{learnergy-2.0.0 → learnergy-2.0.1}/README.md

@@ -12,15 +12,22 @@ image-quality metrics, and visualization helpers.
 
 ## Installation
 
-Learnergy requires Python 3.11 or newer.
+Learnergy requires Python 3.11 or newer. Add it to a project managed by uv with:
 
 ```bash
-pip install learnergy
+uv add learnergy
+```
+
+Add the optional torchvision dependency to run the examples:
+
+```bash
+uv add "learnergy[examples]"
 ```
 
-Install the optional torchvision dependency to run the examples:
+For a consumer installation in an existing Python environment, pip is also supported:
 
 ```bash
+pip install learnergy
 pip install "learnergy[examples]"
 ```
 
@@ -75,6 +82,25 @@ 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

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

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

{learnergy-2.0.0 → learnergy-2.0.1}/learnergy/math/metrics.py

@@ -5,17 +5,26 @@ from skimage.metrics import structural_similarity
 
 
 def calculate_ssim(v: torch.Tensor, x: torch.Tensor) -> float:
-    """Calculate the mean structural similarity of reconstructed images."""
+    """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()
-    width, height = originals.shape[1:3]
+    height, width = originals.shape[1:3]
 
     return sum(
         structural_similarity(
             original,
-            rebuilt.reshape(width, height),
+            rebuilt.reshape(height, width),
             data_range=original.max() - original.min(),
         )
-        for original, rebuilt in zip(originals, reconstructed)
+        for original, rebuilt in zip(originals, reconstructed, strict=True)
     ) / len(reconstructed)

{learnergy-2.0.0 → learnergy-2.0.1}/learnergy/models/bernoulli/discriminative_rbm.py

@@ -288,8 +288,7 @@ class HybridDiscriminativeRBM(DiscriminativeRBM):
 
         """
 
-        activations = torch.exp(F.linear(h, self.U, self.c))
-        probs = torch.div(activations, torch.sum(activations, dim=1).unsqueeze(1))
+        probs = F.softmax(F.linear(h, self.U, self.c), dim=1)
         states = torch.nn.functional.one_hot(
             torch.argmax(probs, dim=1), num_classes=self.n_classes
         ).float()

{learnergy-2.0.0 → learnergy-2.0.1}/learnergy/models/bernoulli/dropout_rbm.py

@@ -4,7 +4,6 @@ from typing import Tuple
 
 import torch
 import torch.nn.functional as F
-from torch.utils.data import DataLoader
 
 import learnergy.utils.exception as e
 from learnergy.core.model import _validated_property
@@ -115,35 +114,12 @@ class DropoutRBM(RBM):
 
         """
 
-        mse = 0
-        batch_size = len(dataset)
-
-        # Saving dropout rate to an auxiliary variable
-        # and temporarily disabling dropout
         p = self.p
         self.p = 0
-
-        batches = DataLoader(
-            dataset, batch_size=batch_size, shuffle=False, num_workers=0
-        )
-
-        for samples, _ in batches:
-            samples = samples.reshape(len(samples), self.n_visible).to(self.device)
-
-            _, pos_hidden_states = self.hidden_sampling(samples)
-            visible_probs, visible_states = self.visible_sampling(pos_hidden_states)
-
-            batch_mse = torch.div(
-                torch.sum(torch.pow(samples - visible_states, 2)), batch_size
-            )
-            mse += batch_mse
-
-        mse /= len(batches)
-
-        # Recovering initial dropout rate
-        self.p = p
-
-        return mse, visible_probs
+        try:
+            return super().reconstruct(dataset)
+        finally:
+            self.p = p
 
 
 class DropConnectRBM(DropoutRBM):

{learnergy-2.0.0 → learnergy-2.0.1}/learnergy/models/bernoulli/rbm.py

@@ -247,12 +247,7 @@ class RBM(Model):
         energy1 = self.energy(samples_binary)
 
         # Calculate the logarithm of the pseudo-likelihood
-        pl = torch.mean(
-            self.n_visible
-            * torch.log(
-                torch.sigmoid(energy1 - energy) + torch.finfo(samples.dtype).eps
-            )
-        )
+        pl = torch.mean(self.n_visible * F.logsigmoid(energy1 - energy))
 
         return pl
 

learnergy-2.0.1/learnergy/models/gaussian/_normalization.py

@@ -0,0 +1,13 @@
+"""Batch standardization shared by Gaussian models."""
+
+import torch
+
+
+def standardize(samples: torch.Tensor) -> torch.Tensor:
+    """Use sample variance for full batches and center singleton batches at zero."""
+
+    correction = 1 if len(samples) > 1 else 0
+    std = samples.std(dim=0, correction=correction, keepdim=True)
+    return (samples - samples.mean(dim=0, keepdim=True)) / (
+        std + torch.finfo(samples.dtype).eps
+    )

{learnergy-2.0.0 → learnergy-2.0.1}/learnergy/models/gaussian/gaussian_conv_rbm.py

@@ -8,6 +8,7 @@ from torch.utils.data import DataLoader
 
 from learnergy.core.model import _validated_property
 from learnergy.models.bernoulli.conv_rbm import ConvRBM
+from learnergy.models.gaussian._normalization import standardize
 
 
 class GaussianConvRBM(ConvRBM):
@@ -51,7 +52,7 @@ class GaussianConvRBM(ConvRBM):
         """Compute hidden probabilities and activations."""
 
         activations = F.conv2d(v, self.W, bias=self.b)
-        return F.relu6(activations).detach(), activations
+        return F.relu6(activations), activations
 
     def visible_sampling(self, h: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
         """Compute visible probabilities and activations."""
@@ -86,10 +87,7 @@ class GaussianConvRBM(ConvRBM):
                 ).to(self.device)
 
                 if self.normalize:
-                    eps = torch.finfo(samples.dtype).eps
-                    samples = (samples - samples.mean(0, True)) / (
-                        samples.std(0, True) + eps
-                    )
+                    samples = standardize(samples)
 
                 _, _, _, _, visible_states = self.gibbs_sampling(samples)
                 visible_states = visible_states.detach()
@@ -110,8 +108,7 @@ class GaussianConvRBM(ConvRBM):
         """Return hidden activations, optionally pooled."""
 
         if self.normalize:
-            eps = torch.finfo(x.dtype).eps
-            x = (x - x.mean(0, True)) / (x.std(0, True) + eps)
+            x = standardize(x)
 
         x, _ = self.hidden_sampling(x)
         if self.maxpooling:

{learnergy-2.0.0 → learnergy-2.0.1}/learnergy/models/gaussian/gaussian_rbm.py

@@ -10,6 +10,7 @@ from torch.utils.data import DataLoader
 
 from learnergy.core.model import _validated_property
 from learnergy.models.bernoulli.rbm import RBM
+from learnergy.models.gaussian._normalization import standardize
 
 
 class GaussianRBM(RBM):
@@ -150,10 +151,7 @@ class GaussianRBM(RBM):
 
             for samples, _ in batches:
                 if self.normalize:
-                    samples = (
-                        (samples - torch.mean(samples, 0, True))
-                        / (torch.std(samples, 0, True) + torch.finfo(samples.dtype).eps)
-                    ).detach()
+                    samples = standardize(samples).detach()
 
                 samples = samples.reshape(len(samples), self.n_visible).to(self.device)
 
@@ -210,10 +208,7 @@ class GaussianRBM(RBM):
 
         for samples, _ in batches:
             if self.normalize:
-                samples = (
-                    (samples - torch.mean(samples, 0, True))
-                    / (torch.std(samples, 0, True) + torch.finfo(samples.dtype).eps)
-                ).detach()
+                samples = standardize(samples).detach()
 
             samples = samples.reshape(len(samples), self.n_visible).to(self.device)
 
@@ -241,10 +236,7 @@ class GaussianRBM(RBM):
         """
 
         if self.input_normalize:
-            x = (
-                (x - torch.mean(x, 0, True))
-                / (torch.std(x, 0, True) + torch.finfo(x.dtype).eps)
-            ).detach()
+            x = standardize(x).detach()
 
         x, _ = self.hidden_sampling(x)
 
@@ -421,8 +413,9 @@ class VarianceGaussianRBM(RBM):
     """A VarianceGaussianRBM class provides the basic implementation for
     Gaussian-Bernoulli Restricted Boltzmann Machines (without standardization).
 
-    Note that this class implements a new cost function that takes in account
-    a new learning parameter: variance (sigma).
+    The learnable scale parameter ``sigma`` defines the visible variance as
+    ``sigma**2 + torch.finfo(dtype).eps``. The same variance is used by the
+    free energy and the visible conditional distribution.
 
     Therefore, there is no need to standardize the data, as the variance
     will be trained throughout the learning procedure.
@@ -490,8 +483,8 @@ class VarianceGaussianRBM(RBM):
 
         """
 
-        sigma = torch.pow(self.sigma, 2) + torch.finfo(v.dtype).eps
-        activations = F.linear(torch.div(v, sigma), self.W.t(), self.b)
+        variance = self.sigma.square() + torch.finfo(v.dtype).eps
+        activations = F.linear(v / variance, self.W.t(), self.b)
 
         if scale:
             probs = torch.sigmoid(torch.div(activations, self.T))
@@ -512,22 +505,16 @@ class VarianceGaussianRBM(RBM):
             scale: A boolean to decide whether temperature should be used or not.
 
         Returns:
-            The probabilities and states of the visible layer sampling.
+            The conditional means and sampled visible states, respectively.
 
         """
 
         activations = F.linear(h, self.W, self.a)
+        variance = self.sigma.square() + torch.finfo(activations.dtype).eps
+        std = variance.sqrt().expand_as(activations)
+        states = torch.normal(activations, std)
 
-        if self.device == "cpu":
-            # Variance needs to have size equal to (batch_size, n_visible)
-            sigma = self.sigma.unsqueeze(0).expand(activations.size(0), -1)
-        else:
-            # Variance needs to have size equal to (n_visible)
-            sigma = self.sigma
-
-        states = torch.normal(activations, torch.pow(sigma, 2))
-
-        return states, activations
+        return activations, states
 
     def energy(self, samples: torch.Tensor) -> torch.Tensor:
         """Calculates and frees the system's energy.
@@ -540,13 +527,13 @@ class VarianceGaussianRBM(RBM):
 
         """
 
-        sigma = torch.pow(self.sigma, 2) + torch.finfo(samples.dtype).eps
-        activations = F.linear(torch.div(samples, sigma), self.W.t(), self.b)
+        variance = self.sigma.square() + torch.finfo(samples.dtype).eps
+        activations = F.linear(samples / variance, self.W.t(), self.b)
 
         h = torch.sum(F.softplus(activations), dim=1)
-        v = torch.sum(torch.div(torch.pow(samples - self.a, 2), 2 * sigma), dim=1)
+        v = torch.sum((samples - self.a).square() / (2 * variance), dim=1)
 
-        energy = -v - h
+        energy = v - h
 
         return energy
 

learnergy-2.0.1/learnergy/visual/tensor.py

@@ -0,0 +1,38 @@
+"""Tensor visualization."""
+
+import matplotlib.pyplot as plt
+import torch
+
+
+def _show(tensor: torch.Tensor) -> None:
+    image = tensor
+    if tensor.ndim == 3:
+        image = tensor.permute(1, 2, 0) if tensor.size(0) == 3 else tensor.squeeze(0)
+    plt.imshow(
+        image.detach().cpu().numpy(),
+        cmap=None if image.ndim == 3 else "gray",
+    )
+    plt.xticks([])
+    plt.yticks([])
+
+
+def save_tensor(tensor: torch.Tensor, output_path: str) -> None:
+    """Save an (H, W), (1, H, W), or (3, H, W) image tensor."""
+
+    figure = plt.figure()
+    try:
+        _show(tensor)
+        figure.savefig(output_path)
+    finally:
+        plt.close(figure)
+
+
+def show_tensor(tensor: torch.Tensor) -> None:
+    """Display an (H, W), (1, H, W), or (3, H, W) image tensor."""
+
+    figure = plt.figure()
+    try:
+        _show(tensor)
+        plt.show()
+    finally:
+        plt.close(figure)

{learnergy-2.0.0 → learnergy-2.0.1}/learnergy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learnergy
-Version: 2.0.0
+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
@@ -49,15 +49,22 @@ image-quality metrics, and visualization helpers.
 
 ## Installation
 
-Learnergy requires Python 3.11 or newer.
+Learnergy requires Python 3.11 or newer. Add it to a project managed by uv with:
 
 ```bash
-pip install learnergy
+uv add learnergy
+```
+
+Add the optional torchvision dependency to run the examples:
+
+```bash
+uv add "learnergy[examples]"
 ```
 
-Install the optional torchvision dependency to run the examples:
+For a consumer installation in an existing Python environment, pip is also supported:
 
 ```bash
+pip install learnergy
 pip install "learnergy[examples]"
 ```
 
@@ -112,6 +119,25 @@ 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

{learnergy-2.0.0 → learnergy-2.0.1}/learnergy.egg-info/SOURCES.txt

@@ -27,6 +27,7 @@ learnergy/models/deep/residual_dbn.py
 learnergy/models/extra/__init__.py
 learnergy/models/extra/sigmoid_rbm.py
 learnergy/models/gaussian/__init__.py
+learnergy/models/gaussian/_normalization.py
 learnergy/models/gaussian/gaussian_conv_rbm.py
 learnergy/models/gaussian/gaussian_rbm.py
 learnergy/utils/__init__.py

{learnergy-2.0.0 → learnergy-2.0.1}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=77"]
+requires = ["setuptools>=84.0.0"]
 build-backend = "setuptools.build_meta"
 
 [project]

{learnergy-2.0.0 → learnergy-2.0.1}/tests/test_bernoulli.py

@@ -1,3 +1,5 @@
+import math
+
 import pytest
 import torch
 from torch.utils.data import TensorDataset
@@ -171,3 +173,62 @@ def test_model_initialization_restores_float32_default():
         assert model.W.dtype == torch.float32
     finally:
         torch.set_default_dtype(torch.float32)
+
+
+@pytest.mark.parametrize("bias", [-100.0, 0.0, 100.0])
+def test_rbm_pseudo_likelihood_uses_stable_log_probabilities(bias):
+    model = RBM(n_visible=1, n_hidden=1)
+    with torch.no_grad():
+        model.W.zero_()
+        model.a.fill_(bias)
+
+    log_probability = model.pseudo_likelihood(torch.zeros(1, 1))
+
+    assert log_probability.item() == pytest.approx(-math.log1p(math.exp(bias)))
+    assert log_probability <= 0
+    log_probability.backward()
+    assert model.a.grad.item() == pytest.approx(-1 / (1 + math.exp(-bias)))
+
+
+@pytest.mark.parametrize("offset", [-1000.0, 0.0, 1000.0])
+def test_hybrid_class_sampling_handles_large_logits(offset):
+    model = HybridDiscriminativeRBM(n_visible=2, n_hidden=1, n_classes=3)
+    with torch.no_grad():
+        model.U.zero_()
+        model.c.copy_(torch.tensor([offset, offset + 1, offset - 1]))
+
+    probabilities, states = model.class_sampling(torch.zeros(2, 1))
+    weights = torch.tensor([1.0, math.e, 1 / math.e])
+    expected = (weights / weights.sum()).expand(2, -1)
+
+    torch.testing.assert_close(probabilities, expected)
+    torch.testing.assert_close(states, torch.tensor([[0.0, 1.0, 0.0]]).repeat(2, 1))
+
+
+@pytest.mark.parametrize("model_class", [DropoutRBM, DropConnectRBM])
+@pytest.mark.parametrize("shape, error", [((0, 4), ValueError), ((1, 3), RuntimeError)])
+def test_dropout_restores_rate_after_reconstruction_failure(model_class, shape, error):
+    model = model_class(n_visible=4, n_hidden=2, dropout=0.5)
+    dataset = TensorDataset(torch.zeros(shape), torch.zeros(shape[0]))
+
+    with pytest.raises(error):
+        model.reconstruct(dataset)
+
+    assert model.p == 0.5
+
+
+@pytest.mark.parametrize("model_class", [DropoutRBM, DropConnectRBM])
+def test_dropout_reconstruction_matches_disabled_dropout(model_class):
+    model = model_class(n_visible=4, n_hidden=2, dropout=0.5)
+    reference = model_class(n_visible=4, n_hidden=2, dropout=0)
+    reference.load_state_dict(model.state_dict())
+    dataset = TensorDataset(torch.rand(3, 4), torch.zeros(3))
+
+    torch.manual_seed(12)
+    expected_mse, expected_reconstruction = reference.reconstruct(dataset)
+    torch.manual_seed(12)
+    mse, reconstruction = model.reconstruct(dataset)
+
+    torch.testing.assert_close(mse, expected_mse, rtol=0, atol=0)
+    torch.testing.assert_close(reconstruction, expected_reconstruction, rtol=0, atol=0)
+    assert model.p == 0.5

{learnergy-2.0.0 → learnergy-2.0.1}/tests/test_core.py

@@ -6,7 +6,7 @@ from learnergy.core import Model
 
 
 def test_package_version():
-    assert learnergy.__version__ == "2.0.0"
+    assert learnergy.__version__ == "2.0.1"
 
 
 def test_model_tracks_device_and_history():

{learnergy-2.0.0 → learnergy-2.0.1}/tests/test_deep.py

@@ -111,8 +111,9 @@ def test_residual_dbn_validates_weights():
         ResidualDBN(zetta2=-1)
 
 
-def test_conv_dbn_builds_trains_and_reconstructs():
-    dataset = TensorDataset(torch.rand(8, 1, 8, 8), torch.zeros(8))
+@pytest.mark.parametrize("n_samples", [8, 5])
+def test_conv_dbn_builds_trains_and_reconstructs(n_samples):
+    dataset = TensorDataset(torch.rand(n_samples, 1, 8, 8), torch.zeros(n_samples))
     model = ConvDBN(
         visible_shape=(8, 8),
         filter_shape=((3, 3), (3, 3)),
@@ -128,7 +129,7 @@ def test_conv_dbn_builds_trains_and_reconstructs():
 
     assert len(mse) == 2
     assert reconstruction_mse >= 0
-    assert reconstruction.shape == (8, 1, 8, 8)
+    assert reconstruction.shape == (n_samples, 1, 8, 8)
     assert model(dataset.tensors[0][:2]).shape == (2, 3, 4, 4)
 
 
@@ -149,6 +150,7 @@ def test_conv_dbn_pooling_configuration():
     assert len(model.maxpol2d) == 2
     samples = torch.rand(2, 1, 8, 8)
     output = model(samples)
+    assert output.shape == (2, 3, 3, 3)
     expected, _ = model.models[0].hidden_sampling(samples)
     expected = model.models[0].maxpol2d(expected)
     expected, _ = model.models[1].hidden_sampling(expected)
@@ -160,3 +162,46 @@ def test_conv_dbn_accepts_legacy_defaults():
     assert model.maxpooling == (False,)
     assert model.pooling_kernel == (2,)
     assert signature(ConvDBN.fit).parameters["epochs"].default == (10, 10)
+
+
+def test_gaussian_dbn_training_handles_singleton_batches():
+    model = DBN(
+        model=("gaussian", "gaussian"),
+        n_visible=4,
+        n_hidden=(3, 2),
+        steps=(1, 1),
+        learning_rate=(0.01, 0.01),
+        momentum=(0, 0),
+        decay=(0, 0),
+        temperature=(1, 1),
+    )
+    dataset = TensorDataset(torch.rand(5, 4), torch.zeros(5))
+
+    mse, pl = model.fit(dataset, batch_size=2, epochs=(1, 1))
+
+    assert all(torch.isfinite(value) for value in mse + pl)
+    assert all(torch.isfinite(parameter).all() for parameter in model.parameters())
+
+
+def test_conv_dbn_forward_preserves_gradient_flow():
+    model = ConvDBN(
+        visible_shape=(8, 8),
+        filter_shape=((3, 3), (2, 2)),
+        n_filters=(2, 3),
+        steps=(1, 1),
+        learning_rate=(0.1, 0.1),
+        momentum=(0, 0),
+        decay=(0, 0),
+        maxpooling=(True, False),
+    )
+    with torch.no_grad():
+        for layer in model.models:
+            layer.W.fill_(0.05)
+            layer.b.fill_(0.1)
+
+    model(torch.ones(2, 1, 8, 8)).sum().backward()
+
+    for layer in model.models:
+        assert layer.W.grad is not None
+        assert torch.isfinite(layer.W.grad).all()
+        assert torch.count_nonzero(layer.W.grad) > 0

learnergy-2.0.1/tests/test_gaussian.py

@@ -0,0 +1,226 @@
+import pytest
+import torch
+from torch.utils.data import TensorDataset
+
+from learnergy.models.gaussian import (
+    GaussianConvRBM,
+    GaussianConvRBM4Deep,
+    GaussianRBM,
+    GaussianRBM4deep,
+    GaussianReluRBM,
+    GaussianReluRBM4deep,
+    GaussianSeluRBM,
+    VarianceGaussianRBM,
+)
+
+
+def test_gaussian_rbm_end_to_end():
+    torch.manual_seed(0)
+    dataset = TensorDataset(torch.rand(12, 16), torch.zeros(12))
+    model = GaussianRBM(n_visible=16, n_hidden=8)
+
+    mse, pl = model.fit(dataset, batch_size=4, epochs=1)
+    reconstruction_mse, reconstruction = model.reconstruct(dataset)
+
+    assert mse >= 0
+    assert torch.isfinite(pl)
+    assert reconstruction_mse >= 0
+    assert reconstruction.shape == (12, 16)
+    assert model(torch.rand(2, 16)).shape == (2, 8)
+
+
+@pytest.mark.parametrize("model_class", [GaussianReluRBM, GaussianSeluRBM])
+def test_gaussian_activation_variants(model_class):
+    model = model_class(n_visible=16, n_hidden=8)
+    probs, states = model.hidden_sampling(torch.rand(2, 16), scale=True)
+
+    assert probs.shape == states.shape == (2, 8)
+    assert torch.equal(probs, states)
+
+
+def test_deep_model_names_remain_available():
+    assert issubclass(GaussianRBM4deep, GaussianRBM)
+    assert issubclass(GaussianReluRBM4deep, GaussianReluRBM)
+    assert issubclass(GaussianConvRBM4Deep, GaussianConvRBM)
+
+
+def test_variance_gaussian_rbm_sampling_is_finite():
+    model = VarianceGaussianRBM(n_visible=16, n_hidden=8)
+    with torch.no_grad():
+        model.sigma.fill_(1e-12)
+
+    samples = torch.rand(2, 16)
+    hidden_probs, hidden_states = model.hidden_sampling(samples)
+    visible_probs, visible_states = model.visible_sampling(hidden_states)
+
+    assert torch.isfinite(hidden_probs).all()
+    assert torch.isfinite(model.energy(samples)).all()
+    assert visible_probs.shape == visible_states.shape == (2, 16)
+    assert "sigma" in model.state_dict()
+    assert len(model.optimizer.param_groups) == 2
+
+
+def test_gaussian_conv_rbm_end_to_end():
+    dataset = TensorDataset(torch.rand(8, 1, 8, 8), torch.zeros(8))
+    model = GaussianConvRBM(
+        visible_shape=(8, 8),
+        filter_shape=(3, 3),
+        n_filters=2,
+        n_channels=1,
+    )
+
+    assert model.fit(dataset, batch_size=4, epochs=1) >= 0
+    assert model(dataset.tensors[0][:2]).shape == (2, 2, 6, 6)
+
+
+@pytest.mark.parametrize("model_class", [GaussianRBM, GaussianReluRBM4deep])
+@pytest.mark.parametrize("batch_size", [1, 3])
+def test_gaussian_forward_standardizes_batches(model_class, batch_size):
+    model = model_class(n_visible=4, n_hidden=2)
+    samples = torch.arange(batch_size * 4, dtype=torch.float32).reshape(batch_size, 4)
+    if batch_size == 1:
+        standardized = torch.zeros_like(samples)
+    else:
+        standardized = (samples - samples.mean(0, True)) / (
+            samples.std(0) + torch.finfo(samples.dtype).eps
+        )
+    expected, _ = model.hidden_sampling(standardized)
+
+    torch.testing.assert_close(model(samples), expected, rtol=0, atol=0)
+
+
+@pytest.mark.parametrize("model_class", [GaussianRBM, GaussianReluRBM4deep])
+def test_gaussian_handles_singleton_training_batch_and_reconstruction(model_class):
+    torch.manual_seed(0)
+    model = model_class(n_visible=4, n_hidden=2)
+    dataset = TensorDataset(torch.rand(5, 4), torch.zeros(5))
+
+    mse, pl = model.fit(dataset, batch_size=2, epochs=1)
+    reconstruction_mse, reconstruction = model.reconstruct(
+        TensorDataset(dataset.tensors[0][:1], dataset.tensors[1][:1])
+    )
+
+    assert torch.isfinite(mse) and torch.isfinite(pl)
+    assert torch.isfinite(reconstruction_mse)
+    assert torch.isfinite(reconstruction).all()
+    assert all(torch.isfinite(parameter).all() for parameter in model.parameters())
+
+
+@pytest.mark.parametrize("model_class", [GaussianConvRBM, GaussianConvRBM4Deep])
+@pytest.mark.parametrize("batch_size", [1, 3])
+def test_gaussian_conv_forward_standardizes_batches(model_class, batch_size):
+    model = model_class(
+        visible_shape=(4, 4), filter_shape=(2, 2), n_filters=2, maxpooling=True
+    )
+    samples = torch.arange(batch_size * 16, dtype=torch.float32).reshape(
+        batch_size, 1, 4, 4
+    )
+    if batch_size == 1:
+        standardized = torch.zeros_like(samples)
+    else:
+        standardized = (samples - samples.mean(0, True)) / (
+            samples.std(0) + torch.finfo(samples.dtype).eps
+        )
+    expected, _ = model.hidden_sampling(standardized)
+    expected = model.maxpol2d(expected)
+
+    torch.testing.assert_close(model(samples), expected, rtol=0, atol=0)
+
+
+@pytest.mark.parametrize("model_class", [GaussianConvRBM, GaussianConvRBM4Deep])
+def test_gaussian_conv_handles_singleton_training_batch(model_class):
+    torch.manual_seed(0)
+    model = model_class(visible_shape=(4, 4), filter_shape=(2, 2), n_filters=2)
+    dataset = TensorDataset(torch.rand(5, 1, 4, 4), torch.zeros(5))
+
+    mse = model.fit(dataset, batch_size=2, epochs=1)
+
+    assert torch.isfinite(mse)
+    assert all(torch.isfinite(parameter).all() for parameter in model.parameters())
+
+
+@pytest.mark.parametrize("model_class", [GaussianConvRBM, GaussianConvRBM4Deep])
+def test_gaussian_conv_forward_preserves_gradient_flow(model_class):
+    model = model_class(visible_shape=(4, 4), filter_shape=(2, 2), n_filters=2)
+    with torch.no_grad():
+        model.W.fill_(0.05)
+        model.b.fill_(1)
+    samples = torch.arange(32, dtype=torch.float32).reshape(2, 1, 4, 4)
+    head = torch.nn.Linear(18, 1, bias=False)
+    with torch.no_grad():
+        head.weight.fill_(1)
+
+    head(model(samples).flatten(1)).square().mean().backward()
+
+    assert model.W.grad is not None
+    assert torch.isfinite(model.W.grad).all()
+    assert torch.count_nonzero(model.W.grad) > 0
+
+
+def test_variance_energy_matches_marginalized_joint_distribution():
+    model = VarianceGaussianRBM(n_visible=2, n_hidden=2).double()
+    with torch.no_grad():
+        model.W.copy_(torch.tensor([[0.2, -0.1], [0.4, 0.3]]))
+        model.a.copy_(torch.tensor([0.3, -0.4]))
+        model.b.copy_(torch.tensor([-0.2, 0.1]))
+        model.sigma.copy_(torch.tensor([0.5, 2.0]))
+    samples = torch.tensor([[0.0, 1.0], [-1.0, 2.0]], dtype=torch.float64)
+    hidden = torch.tensor(
+        [[0.0, 0.0], [0.0, 1.0], [1.0, 0.0], [1.0, 1.0]], dtype=torch.float64
+    )
+    variance = model.sigma.square() + torch.finfo(samples.dtype).eps
+    quadratic = ((samples - model.a).square() / (2 * variance)).sum(1)
+    joint_energy = (
+        quadratic[:, None]
+        - hidden @ model.b
+        - (samples / variance) @ model.W @ hidden.t()
+    )
+    expected = -torch.logsumexp(-joint_energy, dim=1)
+
+    torch.testing.assert_close(model.energy(samples), expected)
+
+
+def test_variance_visible_sampling_returns_means_and_correctly_scaled_states():
+    model = VarianceGaussianRBM(n_visible=2, n_hidden=1)
+    with torch.no_grad():
+        model.W.copy_(torch.tensor([[0.1], [0.2]]))
+        model.a.copy_(torch.tensor([0.3, -0.4]))
+        model.sigma.copy_(torch.tensor([0.5, 2.0]))
+    hidden = torch.ones(20000, 1)
+
+    torch.manual_seed(0)
+    means, states = model.visible_sampling(hidden)
+    expected_means = hidden @ model.W.t() + model.a
+
+    torch.testing.assert_close(means, expected_means)
+    torch.testing.assert_close(states.mean(0), expected_means[0], rtol=0, atol=0.04)
+    torch.testing.assert_close(states.std(0), model.sigma, rtol=0.03, atol=0)
+
+
+def test_variance_gibbs_sampling_uses_random_visible_states():
+    model = VarianceGaussianRBM(n_visible=2, n_hidden=1)
+    with torch.no_grad():
+        model.W.zero_()
+        model.a.zero_()
+
+    torch.manual_seed(0)
+    visible_states = model.gibbs_sampling(torch.zeros(256, 2))[-1]
+
+    assert visible_states.std() > 0.5
+
+
+def test_variance_gaussian_rbm_end_to_end():
+    torch.manual_seed(0)
+    model = VarianceGaussianRBM(n_visible=4, n_hidden=2, learning_rate=0.001)
+    dataset = TensorDataset(torch.rand(5, 4), torch.zeros(5))
+    initial_sigma = model.sigma.detach().clone()
+
+    mse, pl = model.fit(dataset, batch_size=2, epochs=2)
+    reconstruction_mse, reconstruction = model.reconstruct(dataset)
+
+    assert torch.isfinite(mse) and torch.isfinite(pl)
+    assert torch.isfinite(reconstruction_mse)
+    assert reconstruction.shape == (5, 4)
+    assert torch.isfinite(reconstruction).all()
+    assert all(torch.isfinite(parameter).all() for parameter in model.parameters())
+    assert not torch.equal(model.sigma, initial_sigma)

{learnergy-2.0.0 → learnergy-2.0.1}/tests/test_utilities.py

@@ -1,5 +1,6 @@
 import logging as stdlib_logging
 
+import matplotlib.pyplot as plt
 import numpy as np
 import pytest
 import torch
@@ -73,3 +74,54 @@ def test_visual_helpers(tmp_path, monkeypatch):
 
 def test_deep_sigmoid_name_remains_available():
     assert issubclass(SigmoidRBM4Deep, SigmoidRBM)
+
+
+@pytest.mark.parametrize("n_originals, n_reconstructed", [(1, 2), (2, 1)])
+def test_ssim_rejects_unequal_batch_lengths(n_originals, n_reconstructed):
+    sample = torch.arange(64, dtype=torch.float32).reshape(1, 8, 8)
+    originals = sample.repeat(n_originals, 1, 1)
+    reconstructed = sample.reshape(1, 64).repeat(n_reconstructed, 1)
+
+    with pytest.raises(ValueError):
+        calculate_ssim(reconstructed, originals)
+
+
+@pytest.fixture
+def existing_figures():
+    figures = set(plt.get_fignums())
+    yield figures
+    for number in set(plt.get_fignums()) - figures:
+        plt.close(number)
+
+
+@pytest.mark.parametrize("shape", [(3, 5), (1, 5, 7), (3, 5, 7)])
+def test_tensor_render_preserves_image_layout(shape, monkeypatch, existing_figures):
+    samples = torch.rand(shape)
+    rendered = []
+
+    def capture_image():
+        rendered.append(np.asarray(plt.gca().images[0].get_array()))
+
+    monkeypatch.setattr(plt, "show", capture_image)
+    tensor.show_tensor(samples)
+
+    expected = samples.numpy()
+    if len(shape) == 3:
+        expected = np.moveaxis(expected, 0, -1) if shape[0] == 3 else expected[0]
+    np.testing.assert_array_equal(rendered[0], expected)
+    assert set(plt.get_fignums()) == existing_figures
+
+
+@pytest.mark.parametrize("operation", ["save", "show"])
+def test_tensor_render_closes_figure_after_failure(
+    operation, tmp_path, existing_figures
+):
+    samples = torch.zeros(2, 5, 7)
+
+    with pytest.raises(TypeError):
+        if operation == "save":
+            tensor.save_tensor(samples, str(tmp_path / "invalid.png"))
+        else:
+            tensor.show_tensor(samples)
+
+    assert set(plt.get_fignums()) == existing_figures

learnergy-2.0.0/learnergy/visual/tensor.py

@@ -1,32 +0,0 @@
-"""Tensor visualization."""
-
-import matplotlib.pyplot as plt
-import torch
-
-
-def _show(tensor: torch.Tensor) -> None:
-    image = tensor.permute(1, 2, 0) if tensor.size(0) == 3 else tensor
-    plt.imshow(
-        image.detach().cpu().numpy(),
-        cmap=None if tensor.size(0) == 3 else "gray",
-    )
-    plt.xticks([])
-    plt.yticks([])
-
-
-def save_tensor(tensor: torch.Tensor, output_path: str) -> None:
-    """Save a tensor as an image."""
-
-    plt.figure()
-    _show(tensor)
-    plt.savefig(output_path)
-    plt.close()
-
-
-def show_tensor(tensor: torch.Tensor) -> None:
-    """Display a tensor as an image."""
-
-    plt.figure()
-    _show(tensor)
-    plt.show()
-    plt.close()

learnergy-2.0.0/tests/test_gaussian.py

@@ -1,73 +0,0 @@
-import pytest
-import torch
-from torch.utils.data import TensorDataset
-
-from learnergy.models.gaussian import (
-    GaussianConvRBM,
-    GaussianConvRBM4Deep,
-    GaussianRBM,
-    GaussianRBM4deep,
-    GaussianReluRBM,
-    GaussianReluRBM4deep,
-    GaussianSeluRBM,
-    VarianceGaussianRBM,
-)
-
-
-def test_gaussian_rbm_end_to_end():
-    torch.manual_seed(0)
-    dataset = TensorDataset(torch.rand(12, 16), torch.zeros(12))
-    model = GaussianRBM(n_visible=16, n_hidden=8)
-
-    mse, pl = model.fit(dataset, batch_size=4, epochs=1)
-    reconstruction_mse, reconstruction = model.reconstruct(dataset)
-
-    assert mse >= 0
-    assert torch.isfinite(pl)
-    assert reconstruction_mse >= 0
-    assert reconstruction.shape == (12, 16)
-    assert model(torch.rand(2, 16)).shape == (2, 8)
-
-
-@pytest.mark.parametrize("model_class", [GaussianReluRBM, GaussianSeluRBM])
-def test_gaussian_activation_variants(model_class):
-    model = model_class(n_visible=16, n_hidden=8)
-    probs, states = model.hidden_sampling(torch.rand(2, 16), scale=True)
-
-    assert probs.shape == states.shape == (2, 8)
-    assert torch.equal(probs, states)
-
-
-def test_deep_model_names_remain_available():
-    assert issubclass(GaussianRBM4deep, GaussianRBM)
-    assert issubclass(GaussianReluRBM4deep, GaussianReluRBM)
-    assert issubclass(GaussianConvRBM4Deep, GaussianConvRBM)
-
-
-def test_variance_gaussian_rbm_sampling_is_finite():
-    model = VarianceGaussianRBM(n_visible=16, n_hidden=8)
-    with torch.no_grad():
-        model.sigma.fill_(1e-12)
-
-    samples = torch.rand(2, 16)
-    hidden_probs, hidden_states = model.hidden_sampling(samples)
-    visible_probs, visible_states = model.visible_sampling(hidden_states)
-
-    assert torch.isfinite(hidden_probs).all()
-    assert torch.isfinite(model.energy(samples)).all()
-    assert visible_probs.shape == visible_states.shape == (2, 16)
-    assert "sigma" in model.state_dict()
-    assert len(model.optimizer.param_groups) == 2
-
-
-def test_gaussian_conv_rbm_end_to_end():
-    dataset = TensorDataset(torch.rand(8, 1, 8, 8), torch.zeros(8))
-    model = GaussianConvRBM(
-        visible_shape=(8, 8),
-        filter_shape=(3, 3),
-        n_filters=2,
-        n_channels=1,
-    )
-
-    assert model.fit(dataset, batch_size=4, epochs=1) >= 0
-    assert model(dataset.tensors[0][:2]).shape == (2, 2, 6, 6)