congrads 1.0.6__tar.gz → 1.1.0__tar.gz

{congrads-1.0.6 → congrads-1.1.0}/PKG-INFO

@@ -1,44 +1,45 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.3
 Name: congrads
-Version: 1.0.6
+Version: 1.1.0
 Summary: A toolbox for using Constraint Guided Gradient Descent when training neural networks.
+Author: Wout Rombouts, Quinten Van Baelen, Peter Karsmakers
 Author-email: Wout Rombouts <wout.rombouts@kuleuven.be>, Quinten Van Baelen <quinten.vanbaelen@kuleuven.be>, Peter Karsmakers <peter.karsmakers@kuleuven.be>
 License: Copyright 2024 DTAI - KU Leuven
-        
-        Redistribution and use in source and binary forms, with or without modification, 
-        are permitted provided that the following conditions are met:
-        
-        1. Redistributions of source code must retain the above copyright notice, 
-        this list of conditions and the following disclaimer.
-        
-        2. Redistributions in binary form must reproduce the above copyright notice, 
-        this list of conditions and the following disclaimer in the documentation 
-        and/or other materials provided with the distribution.
-        
-        3. Neither the name of the copyright holder nor the names of its 
-        contributors may be used to endorse or promote products derived from 
-        this software without specific prior written permission.
-        
-        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” 
-        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
-        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
-        ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 
-        LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
-        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
-        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
-        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
-        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
-        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-        
-Requires-Python: >=3.9
+         
+         Redistribution and use in source and binary forms, with or without modification, 
+         are permitted provided that the following conditions are met:
+         
+         1. Redistributions of source code must retain the above copyright notice, 
+         this list of conditions and the following disclaimer.
+         
+         2. Redistributions in binary form must reproduce the above copyright notice, 
+         this list of conditions and the following disclaimer in the documentation 
+         and/or other materials provided with the distribution.
+         
+         3. Neither the name of the copyright holder nor the names of its 
+         contributors may be used to endorse or promote products derived from 
+         this software without specific prior written permission.
+         
+         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” 
+         AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+         IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
+         ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 
+         LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
+         DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
+         SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
+         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
+         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
+         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: torch>=2.0.0
+Requires-Dist: torchvision>=0.15.1
+Requires-Dist: tqdm>=4.65.0
+Requires-Dist: matplotlib>=3.7.0 ; extra == 'examples'
+Requires-Dist: tensorboard>=2.12.0 ; extra == 'examples'
+Requires-Python: >=3.11
+Provides-Extra: examples
 Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy>=1.26.4
-Requires-Dist: pandas>=2.2.2
-Requires-Dist: torch>=2.5.0
-Requires-Dist: torchvision>=0.20.0
-Requires-Dist: tensorboard>=2.18.0
-Requires-Dist: tqdm>=4.66.5
 
 <div align="center">
 	<img src="https://github.com/ML-KULeuven/congrads/blob/main/docs/_static/congrads_export.png?raw=true" height="200">
@@ -49,7 +50,7 @@ Requires-Dist: tqdm>=4.66.5
 
 [![PyPi](https://img.shields.io/pypi/v/congrads.svg)](https://pypi.org/project/congrads)
 [![Read the Docs](https://img.shields.io/readthedocs/congrads/latest.svg?label=Read%20the%20Docs)](https://congrads.readthedocs.io)
-[![Python Version: 3.9+](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://pypi.org/project/congrads)
+[![Python Version: 3.11+](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://pypi.org/project/congrads)
 [![Downloads](https://img.shields.io/pypi/dm/congrads.svg)](https://pypistats.org/packages/congrads)
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 
@@ -80,15 +81,21 @@ Next, install the Congrads toolbox. The recommended way to install it is to use
 pip install congrads
 ```
 
+You can also install Congrads together with extra packages required to run the examples:
+
+```bash
+pip install congrads[examples]
+```
+
 This should automatically install all required dependencies for you. If you would like to install dependencies manually, Congrads depends on the following:
 
-- Python 3.9 - 3.12
+- Python 3.11 - 3.13
 - **PyTorch** (install with CUDA support for GPU training, refer to [PyTorch's getting started guide](https://pytorch.org/get-started/locally/))
 - **NumPy** (install with `pip install numpy`, or refer to [NumPy's install guide](https://numpy.org/install/).)
 - **Pandas** (install with `pip install pandas`, or refer to [Panda's install guide](https://pandas.pydata.org/docs/getting_started/install.html).)
 - **Tqdm** (install with `pip install tqdm`)
 - **Torchvision** (install with `pip install torchvision`)
-- **Tensorboard** (install with `pip install tensorboard`)
+- Optional: **Tensorboard** (install with `pip install tensorboard`)
 
 ### 2. **Core concepts**
 
@@ -182,11 +189,11 @@ core.fit(max_epochs=50)
 - **Improve Training Process**: Inject domain knowledge in the training stage, increasing learning efficiency.
 - **Physics-Informed Neural Networks (PINNs)**: Coming soon, Enforce physical laws as constraints in your models.
 
-## Roadmap
+## Planned changes / Roadmap
 
 - [ ] Add ODE/PDE constraints to support PINNs
+- [ ] Rework callback system
 - [ ] Add support for constraint parser that can interpret equations
-- [ ] Determine if it is feasible to add unit and or functional tests
 
 ## Research
 

{congrads-1.0.6 → congrads-1.1.0}/README.md

@@ -7,7 +7,7 @@
 
 [![PyPi](https://img.shields.io/pypi/v/congrads.svg)](https://pypi.org/project/congrads)
 [![Read the Docs](https://img.shields.io/readthedocs/congrads/latest.svg?label=Read%20the%20Docs)](https://congrads.readthedocs.io)
-[![Python Version: 3.9+](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://pypi.org/project/congrads)
+[![Python Version: 3.11+](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://pypi.org/project/congrads)
 [![Downloads](https://img.shields.io/pypi/dm/congrads.svg)](https://pypistats.org/packages/congrads)
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 
@@ -38,15 +38,21 @@ Next, install the Congrads toolbox. The recommended way to install it is to use
 pip install congrads
 ```
 
+You can also install Congrads together with extra packages required to run the examples:
+
+```bash
+pip install congrads[examples]
+```
+
 This should automatically install all required dependencies for you. If you would like to install dependencies manually, Congrads depends on the following:
 
-- Python 3.9 - 3.12
+- Python 3.11 - 3.13
 - **PyTorch** (install with CUDA support for GPU training, refer to [PyTorch's getting started guide](https://pytorch.org/get-started/locally/))
 - **NumPy** (install with `pip install numpy`, or refer to [NumPy's install guide](https://numpy.org/install/).)
 - **Pandas** (install with `pip install pandas`, or refer to [Panda's install guide](https://pandas.pydata.org/docs/getting_started/install.html).)
 - **Tqdm** (install with `pip install tqdm`)
 - **Torchvision** (install with `pip install torchvision`)
-- **Tensorboard** (install with `pip install tensorboard`)
+- Optional: **Tensorboard** (install with `pip install tensorboard`)
 
 ### 2. **Core concepts**
 
@@ -140,11 +146,11 @@ core.fit(max_epochs=50)
 - **Improve Training Process**: Inject domain knowledge in the training stage, increasing learning efficiency.
 - **Physics-Informed Neural Networks (PINNs)**: Coming soon, Enforce physical laws as constraints in your models.
 
-## Roadmap
+## Planned changes / Roadmap
 
 - [ ] Add ODE/PDE constraints to support PINNs
+- [ ] Rework callback system
 - [ ] Add support for constraint parser that can interpret equations
-- [ ] Determine if it is feasible to add unit and or functional tests
 
 ## Research
 

congrads-1.1.0/pyproject.toml

@@ -0,0 +1,122 @@
+[project]
+name = "congrads"
+version = "1.1.0"
+description = "A toolbox for using Constraint Guided Gradient Descent when training neural networks."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Wout Rombouts", email = "wout.rombouts@kuleuven.be" },
+    { name = "Quinten Van Baelen", email = "quinten.vanbaelen@kuleuven.be" },
+    { name = "Peter Karsmakers", email = "peter.karsmakers@kuleuven.be" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "numpy>=1.24.0",
+    "pandas>=1.5.0",
+    "torch>=2.0.0",
+    "torchvision>=0.15.1",
+    "tqdm>=4.65.0",
+]
+
+[project.optional-dependencies]
+examples = [
+    "matplotlib>=3.7.0",
+    "tensorboard>=2.12.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.13,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.13.0",
+    "sphinx>=8.2.3",
+    "sphinx-rtd-theme>=3.0.2",
+    "tox>=4.30.2",
+    "twine>=6.2.0",
+]
+
+[tool.ruff]
+# Match Black-style defaults but with a longer line length
+line-length = 100
+indent-width = 4
+target-version = "py311"  # or "py312" if needed
+
+# Where Ruff runs (exclude cache, venvs, build dirs, etc.)
+exclude = [
+    ".git",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".venv",
+    "venv",
+    "build",
+    "dist",
+    "__pypackages__",
+]
+
+# Which files to include
+include = ["pyproject.toml", "src/**/*.py", "tests/**/*.py"]
+
+[tool.ruff.lint]
+# Essentials + additional readability rules
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # import sorting
+    "B",   # bugbear
+    "UP",  # pyupgrade
+    "C4",  # comprehensions
+    "ISC", # implicit string concatenation
+    "D",   # docstring styling
+    "N",   # consistent naming
+]
+ignore = [
+    "E501", # line length (handled by formatter)
+]
+
+# Enable autofix for safe rules
+fixable = ["ALL"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D", "N"]
+
+[tool.ruff.format]
+quote-style = "double"               # enforce double quotes
+indent-style = "space"               # 4 spaces
+skip-magic-trailing-comma = false    # Black-compatible
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.tox]
+envlist = ["py{311,312,313}-{latest,minimum}"]
+
+[tool.tox.env_run_base]
+description = "Run tests with latest dependencies"
+deps = [
+    "pytest",
+    "pytest-cov"
+]
+commands = [
+    ["pytest", "--cov=src/congrads", "tests/"]
+]
+extras = [ "examples" ]
+
+[tool.tox.env.latest]
+description = "Run tests with latest dependencies"
+
+[tool.tox.env.minimum]
+description = "Run tests with minimum dependencies"
+deps = [
+    "-c constraints-min.txt",
+    "pytest",
+    "pytest-cov"
+]
+
+# Optional: ensure coverage is reported for all envs
+skip_missing_interpreters = true

{congrads-1.0.6 → congrads-1.1.0/src}/congrads/__init__.py

@@ -1,6 +1,4 @@
-# pylint: skip-file
-
-try:
+try:  # noqa: D104
     from importlib.metadata import version as get_version  # Python 3.8+
 except ImportError:
     from pkg_resources import (
@@ -25,5 +23,6 @@ __all__ = [
     "descriptor",
     "metrics",
     "networks",
+    "transformations",
     "utils",
 ]

congrads-1.1.0/src/congrads/checkpoints.py

@@ -0,0 +1,178 @@
+"""Module for managing PyTorch model checkpoints.
+
+Provides the `CheckpointManager` class to save and load model and optimizer
+states during training, track the best metric values, and optionally report
+checkpoint events.
+"""
+
+import os
+from collections.abc import Callable
+from pathlib import Path
+
+from torch import Tensor, load, save
+from torch.nn import Module
+from torch.optim import Optimizer
+
+from .metrics import MetricManager
+from .utils import validate_callable, validate_type
+
+
+class CheckpointManager:
+    """Manage saving and loading checkpoints for PyTorch models and optimizers.
+
+    Handles checkpointing based on a criteria function, restores metric
+    states, and optionally reports when a checkpoint is saved.
+    """
+
+    def __init__(
+        self,
+        criteria_function: Callable[[dict[str, Tensor], dict[str, Tensor]], bool],
+        network: Module,
+        optimizer: Optimizer,
+        metric_manager: MetricManager,
+        save_dir: str = "checkpoints",
+        create_dir: bool = False,
+        report_save: bool = False,
+    ):
+        """Initialize the CheckpointManager.
+
+        Args:
+            criteria_function (Callable[[dict[str, Tensor], dict[str, Tensor]], bool]):
+                Function that determines if the current checkpoint should be
+                saved based on the current and best metric values.
+            network (torch.nn.Module): The model to save/load.
+            optimizer (torch.optim.Optimizer): The optimizer to save/load.
+            metric_manager (MetricManager): Manages metric states for checkpointing.
+            save_dir (str, optional): Directory to save checkpoints. Defaults to 'checkpoints'.
+            create_dir (bool, optional): Whether to create `save_dir` if it does not exist.
+                Defaults to False.
+            report_save (bool, optional): Whether to report when a checkpoint is saved.
+                Defaults to False.
+
+        Raises:
+            TypeError: If any provided attribute has an incompatible type.
+            FileNotFoundError: If `save_dir` does not exist and `create_dir` is False.
+        """
+        # Type checking
+        validate_callable("criteria_function", criteria_function)
+        validate_type("network", network, Module)
+        validate_type("optimizer", optimizer, Optimizer)
+        validate_type("metric_manager", metric_manager, MetricManager)
+        validate_type("create_dir", create_dir, bool)
+        validate_type("report_save", report_save, bool)
+
+        # Create path or raise error if create_dir is not found
+        if not os.path.exists(save_dir):
+            if not create_dir:
+                raise FileNotFoundError(
+                    f"Save directory '{save_dir}' configured in checkpoint manager is not found."
+                )
+            Path(save_dir).mkdir(parents=True, exist_ok=True)
+
+        # Initialize objects variables
+        self.criteria_function = criteria_function
+        self.network = network
+        self.optimizer = optimizer
+        self.metric_manager = metric_manager
+        self.save_dir = save_dir
+        self.report_save = report_save
+
+        self.best_metric_values: dict[str, Tensor] = {}
+
+    def evaluate_criteria(self, epoch: int, metric_group: str = "during_training"):
+        """Evaluate the criteria function to determine if a better model is found.
+
+        Aggregates the current metric values during training and applies the
+        criteria function. If the criteria function indicates improvement, the
+        best metric values are updated, a checkpoint is saved, and a message is
+        optionally printed.
+
+        Args:
+            epoch (int): The current epoch number.
+            metric_group (str, optional): The metric group to evaluate. Defaults to 'during_training'.
+        """
+        current_metric_values = self.metric_manager.aggregate(metric_group)
+        if self.criteria_function is not None and self.criteria_function(
+            current_metric_values, self.best_metric_values
+        ):
+            # Print message if a new checkpoint is saved
+            if self.report_save:
+                print(f"New checkpoint saved at epoch {epoch}.")
+
+            # Update current best metric values
+            for metric_name, metric_value in current_metric_values.items():
+                self.best_metric_values[metric_name] = metric_value
+
+            # Save the current state
+            self.save(epoch)
+
+    def resume(self, filename: str = "checkpoint.pth", ignore_missing: bool = False) -> int:
+        """Resumes training from a saved checkpoint file.
+
+        Args:
+            filename (str): The name of the checkpoint file to load.
+                Defaults to "checkpoint.pth".
+            ignore_missing (bool): If True, does not raise an error if the
+                checkpoint file is missing and continues without loading,
+                starting from epoch 0. Defaults to False.
+
+        Returns:
+            int: The epoch number from the loaded checkpoint, or 0 if
+                ignore_missing is True and no checkpoint was found.
+
+        Raises:
+            TypeError: If a provided attribute has an incompatible type.
+            FileNotFoundError: If the specified checkpoint file does not exist.
+        """
+        # Type checking
+        validate_type("filename", filename, str)
+        validate_type("ignore_missing", ignore_missing, bool)
+
+        # Return starting epoch, either from checkpoint file or default
+        filepath = os.path.join(self.save_dir, filename)
+        if os.path.exists(filepath):
+            checkpoint = self.load(filename)
+            return checkpoint["epoch"]
+        elif ignore_missing:
+            return 0
+        else:
+            raise FileNotFoundError(f"A checkpoint was not found at {filepath} to resume training.")
+
+    def save(self, epoch: int, filename: str = "checkpoint.pth"):
+        """Save a checkpoint.
+
+        Args:
+            epoch (int): Current epoch number.
+            filename (str): Name of the checkpoint file. Defaults to
+                'checkpoint.pth'.
+        """
+        state = {
+            "epoch": epoch,
+            "network_state": self.network.state_dict(),
+            "optimizer_state": self.optimizer.state_dict(),
+            "best_metrics": self.best_metric_values,
+        }
+        filepath = os.path.join(self.save_dir, filename)
+        save(state, filepath)
+
+    def load(self, filename: str):
+        """Load a checkpoint and restore the training state.
+
+        Loads the checkpoint from the specified file and restores the network
+        weights, optimizer state, and best metric values.
+
+        Args:
+            filename (str): Name of the checkpoint file.
+
+        Returns:
+            dict: A dictionary containing the loaded checkpoint information,
+                including epoch, loss, and other relevant training state.
+        """
+        filepath = os.path.join(self.save_dir, filename)
+
+        checkpoint = load(filepath, weights_only=True)
+        self.network.load_state_dict(checkpoint["network_state"])
+        self.optimizer.load_state_dict(checkpoint["optimizer_state"])
+        self.best_metric_values = checkpoint["best_metrics"]
+
+        return checkpoint