learnergy 2.0.1__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.1 → learnergy-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learnergy
-Version: 2.0.1
+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
@@ -140,6 +140,8 @@ 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.1 → learnergy-2.0.2}/README.md

@@ -103,6 +103,8 @@ 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.1 → 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.1 → learnergy-2.0.2}/learnergy/math/metrics.py

@@ -1,4 +1,7 @@
-"""Image similarity metrics."""
+# 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
@@ -7,12 +10,18 @@ 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: The batches contain different numbers of images.
+        ValueError: Batch lengths, image shapes, or SSIM window requirements are incompatible.
 
     """
 

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.1 → 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