learnergy 2.0.0__tar.gz → 2.0.2__tar.gz

learnergy-2.0.2/AGENTS.md

@@ -0,0 +1,5 @@
+# Contributor and agent guidance
+
+Read and follow [CONVENTIONS.md](CONVENTIONS.md) before changing this repository.
+Preserve public behavior and checkpoint compatibility unless the task explicitly changes them.
+Use the existing validation tools and keep unrelated or concurrent work intact.

learnergy-2.0.2/CONVENTIONS.md

@@ -0,0 +1,75 @@
+# Learnergy conventions
+
+Learnergy adopts the applicable code-style rules from cpmux's phitrain-derived conventions.
+These rules govern new code and convention updates without authorizing unrelated algorithm or API changes.
+
+## Compatibility and scope
+
+- Keep the current Python 3.11 minimum. Use the requested modern Python idioms where they are compatible with it.
+- Preserve public imports, model names, constructor options, return values, normalization policies, and checkpoint state.
+- Keep Learnergy's domain-oriented package layout and public package exports. cpmux's empty package initializers,
+  CLI architecture, Pydantic choices, and test-layout migration are not part of this adoption.
+- Tests remain grouped by the existing model families. Runtime validation rules do not prohibit test assertions.
+
+## Code style
+
+- Use `X | None`, builtin generics such as `list[str]`, and ABCs from `collections.abc`.
+  Import only typing-specific constructs such as `Any` and `Literal` from `typing`. (R2)
+- Start every Python file with the project header:
+
+  ```python
+  # Copyright (c) 2020-2026 Mateus Roder and Gustavo de Rosa.
+  # Licensed under the Apache License, Version 2.0.
+  ```
+
+- Keep imports top-level, absolute, and grouped as standard library, third-party, then Learnergy imports.
+- Use double-quoted strings. Code formatting and readable prose use a 120-character limit. (R9)
+- Public functions, regular classes, and explicit constructors have Google-style docstrings.
+  Use a single-sentence summary and one-line `Args:`, `Returns:`, and `Raises:` entries as applicable.
+  Do not put semicolons or `defaults to ...` tails in entries. (R3, R13)
+- A regular class has a one-sentence class summary. Constructor arguments belong on `__init__`, not the class.
+  Preserve mathematical references and substantive behavioral notes in module or operation documentation.
+- Multiline docstrings have one blank line before the closing triple quotes and one blank line after them
+  before code or fields. Keep class and module summaries on one line when they need no other content,
+  matching cpmux's examples and Black's normalization.
+- Private helpers have no docstrings. Framework-dispatched overrides such as `forward`, `__getitem__`, and
+  `__len__` have no docstrings. Document their relevant contracts in public sampling methods, constructors,
+  module documentation, or the user guide instead.
+- Data classes without an explicit constructor document each field on one line in an `Attributes:` section.
+  This rule does not require introducing data classes into existing models.
+- Public contracts describe tensor shapes, tuple element order, mutation, history, normalization, gradient
+  boundaries, and failure behavior where relevant. An annotation is not runtime validation.
+- Obtain library loggers with `get_logger(__name__)` from `learnergy.utils.logging`.
+  Do not use `print()` in library code. Application examples may print their results.
+- Warning and error diagnostics identify a backticked offender and end with a period, for example
+  `` f"`name={value}` could not be loaded." ``. Info and debug messages stay plain. (R14)
+- Raised messages use `` "`name` <verb phrase>[, but got <value>]." ``.
+  Use `is None` and `is True` prose rather than comparison operators in messages. (R1)
+- Validate with `if` and a specific raised exception, never a runtime `assert`. Do not use bare `except:`.
+- Comments explain why rather than narrating the next statement. Prefer no comment or one line, with a
+  three-line maximum, no banners, and no trailing period. Copyright and license notices are exempt. (R8)
+- Separate logical phases with one blank line in function bodies of at least 12 lines. (R11)
+- Inline new single-use implementation details. Extract a helper, constant, or configurable parameter when
+  a second call-site establishes reuse. Do not delete published APIs or required callbacks by counting only
+  their internal call-sites. (R16)
+
+## Tests and review
+
+- Test functions and fixtures are plain functions without docstrings. Test functions have no type annotations.
+- Use bare assertions without failure-message strings. Names should describe the observable behavior.
+- Preserve seeded behavior when claiming a behavior-preserving refactor. Treat deliberate numerical changes
+  as separate, explicit changes rather than hiding them in a style pass.
+- Regression tests compare actual model output with an independently justified expectation and should fail
+  for the defect they claim to prevent.
+
+## Tooling
+
+Use the existing pinned Black, isort, and flake8 tools at line length 120.
+The supported interpreter range, dependencies, and build backend do not change as part of this style adoption.
+
+```text
+uv sync --locked --extra docs
+uv run pre-commit run --all-files
+uv run pytest
+uv run python -m sphinx -W -b html docs build
+```

learnergy-2.0.2/MANIFEST.in

@@ -0,0 +1 @@
+include AGENTS.md CONVENTIONS.md

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learnergy
-Version: 2.0.0
+Version: 2.0.2
 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,8 +119,29 @@ 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
 
+Follow [the coding conventions](CONVENTIONS.md) when changing the library or its examples.
+
 The repository uses [uv](https://docs.astral.sh/uv/) for reproducible
 environments and packaging:
 

{learnergy-2.0.0 → learnergy-2.0.2}/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,8 +82,29 @@ 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
 
+Follow [the coding conventions](CONVENTIONS.md) when changing the library or its examples.
+
 The repository uses [uv](https://docs.astral.sh/uv/) for reproducible
 environments and packaging:
 

learnergy-2.0.2/learnergy/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2020-2026 Mateus Roder and Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.
+
+"""Provide energy-based learning models built with PyTorch."""
+
+__version__ = "2.0.2"

{learnergy-2.0.0 → learnergy-2.0.2}/learnergy/core/__init__.py

@@ -1,3 +1,6 @@
+# Copyright (c) 2020-2026 Mateus Roder and Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.
+
 """Core model primitives."""
 
 from learnergy.core.dataset import Dataset

learnergy-2.0.2/learnergy/core/dataset.py

@@ -0,0 +1,68 @@
+# Copyright (c) 2020-2026 Mateus Roder and Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.
+
+"""Adapt array-backed samples to the PyTorch dataset interface."""
+
+from collections.abc import Callable
+from typing import Any
+
+import torch
+
+import learnergy.utils.exception as e
+from learnergy.core.model import _validated_property
+from learnergy.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class Dataset(torch.utils.data.Dataset):
+    """Expose samples and targets with an optional sample transform."""
+
+    data = _validated_property("data", doc="Backing sample collection, retained without copying.")
+    targets = _validated_property("targets", doc="Targets indexed alongside the sample collection.")
+    transform = _validated_property(
+        "transform",
+        lambda _, value: value is None or callable(value),
+        e.TypeError,
+        "`transform` should be callable or None.",
+        doc="Optional transformation applied when a sample is accessed.",
+    )
+
+    def __init__(
+        self,
+        data: Any,
+        targets: Any,
+        transform: Callable[[Any], Any] | None = None,
+        show_log: bool = True,
+    ) -> None:
+        """Store sample and target references for indexed access.
+
+        Data is not copied and transforms are applied on access rather than during initialization.
+
+        Args:
+            data: Indexable sample collection.
+            targets: Indexable target collection aligned with the samples.
+            transform: Optional callable that transforms an individual sample.
+            show_log: Whether to log dataset creation.
+
+        Raises:
+            TypeError: The transform is neither callable nor 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) -> tuple[Any, Any]:
+        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.2/learnergy/core/model.py

@@ -0,0 +1,74 @@
+# Copyright (c) 2020-2026 Mateus Roder and Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.
+
+"""Provide shared model state and validated attributes."""
+
+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 = "`value` is invalid.",
+    *,
+    doc: str | None = None,
+) -> property:
+    storage_name = f"_{name}"
+
+    def _get(instance: Any) -> Any:
+        return getattr(instance, storage_name)
+
+    def _set(instance: Any, value: Any) -> None:
+        if validator is not None and not validator(instance, value):
+            raise error(message)
+
+        setattr(instance, storage_name, value)
+
+    return property(_get, _set, doc=doc)
+
+
+class Model(torch.nn.Module):
+    """Provide device selection and metric history for energy-based models."""
+
+    device = _validated_property(
+        "device",
+        lambda _, value: value in ("cpu", "cuda"),
+        e.TypeError,
+        "`device` should be `cpu` or `cuda`.",
+        doc="Computation device selected during initialization.",
+    )
+    history = _validated_property("history", doc="Recorded values grouped into lists by metric name.")
+
+    def __init__(self, use_gpu: bool = False) -> None:
+        """Initialize device selection and an empty metric history.
+
+        Initialization sets PyTorch's process-wide default floating-point dtype to float32.
+
+        Args:
+            use_gpu: Whether to select CUDA when it is available.
+
+        """
+
+        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: Any) -> None:
+        """Append values to their per-metric history lists.
+
+        Existing history is retained and values are stored without conversion or copying.
+
+        Args:
+            **kwargs: Values keyed by the metric names to update.
+
+        """
+
+        for k, v in kwargs.items():
+            self.history.setdefault(k, []).append(v)

learnergy-2.0.2/learnergy/math/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) 2020-2026 Mateus Roder and Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.
+
+"""Mathematical helpers."""

learnergy-2.0.2/learnergy/math/metrics.py

@@ -0,0 +1,39 @@
+# Copyright (c) 2020-2026 Mateus Roder and Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.
+
+"""Calculate 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.
+
+    Tensors are detached and copied to CPU as needed before comparison.
+    Each original image supplies its own intensity range to the SSIM calculation.
+
+    Args:
+        v: Reconstructed images, with each image flattened or shaped like its original.
+        x: Original grayscale images with shape (batch, height, width).
+
+    Returns:
+        Mean SSIM over the paired images.
+
+    Raises:
+        ValueError: Batch lengths, image shapes, or SSIM window requirements are incompatible.
+
+    """
+
+    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.2/learnergy/math/scale.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2020-2026 Mateus Roder and Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.
+
+"""Normalize numerical arrays."""
+
+import numpy as np
+
+from learnergy.utils.constants import EPSILON
+
+
+def unitary_scale(x: np.ndarray) -> np.ndarray:
+    """Return a float32 copy scaled by its value range.
+
+    The input is not modified and finite constant arrays become zero arrays.
+
+    Args:
+        x: Numeric array to scale.
+
+    Returns:
+        Float32 array of the same shape, normalized with an epsilon guard.
+
+    """
+
+    scaled = x.astype("float32")
+    scaled -= scaled.min()
+    scaled /= scaled.max() + EPSILON
+    return scaled

learnergy-2.0.2/learnergy/models/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) 2020-2026 Mateus Roder and Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.
+
+"""A package contaning subpackages of models for all common learnergy modules."""

{learnergy-2.0.0 → learnergy-2.0.2}/learnergy/models/bernoulli/__init__.py

@@ -1,3 +1,6 @@
+# Copyright (c) 2020-2026 Mateus Roder and Gustavo de Rosa.
+# Licensed under the Apache License, Version 2.0.
+
 """Bernoulli-valued RBM variants."""
 
 from learnergy.models.bernoulli.conv_rbm import ConvRBM