congrads 0.1.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

congrads-1.0.1.dist-info/LICENSE

@@ -0,0 +1,26 @@
+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.

congrads-1.0.1.dist-info/METADATA

@@ -0,0 +1,208 @@
+Metadata-Version: 2.2
+Name: congrads
+Version: 1.0.1
+Summary: A toolbox for using Constraint Guided Gradient Descent when training neural networks.
+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
+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="docs/_static/congrads_export.png" height="200">
+	<p>
+	<b>Incorporate constraints into neural network training for more reliable and robust models.</b>
+	</p>
+	<br/>
+
+[![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)
+[![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)
+
+<br/>
+<br/>
+</div>
+
+**Congrads** is a Python toolbox that brings **constraint-guided gradient descent** capabilities to your machine learning projects. Built with seamless integration into PyTorch, Congrads empowers you to enhance the training and optimization process by incorporating constraints into your training pipeline.
+
+Whether you're working with simple inequality constraints, combinations of input-output relations, or custom constraint formulations, Congrads provides the tools and flexibility needed to build more robust and generalized models.
+
+## Key Features
+
+- **Constraint-Guided Training**: Add constraints to guide the optimization process, ensuring that your model generalizes better by trying to satisfy the constraints.
+- **Flexible Constraint Definition**: Define constraints on inputs, outputs, or combinations thereof, using an intuitive and extendable interface. Make use of pre-programmed constraint classes or write your own.
+- **Seamless PyTorch Integration**: Use Congrads within your existing PyTorch workflows with minimal setup.
+- **Flexible and extendible**: Write your own custom networks, constraints and dataset classes to easily extend the functionality of the toolbox.
+
+## Getting Started
+
+### 1. **Installation**
+
+First, make sure to install PyTorch since Congrads heavily relies on its deep learning framework. Please refer to the [PyTorch's getting started guide](https://pytorch.org/get-started/locally/). Make sure to install with CUDA support for GPU training.
+
+Next, install the Congrads toolbox. The recommended way to install it is to use pip:
+
+```bash
+pip install congrads
+```
+
+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
+- **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`)
+
+### 2. **Core concepts**
+
+Before diving into the toolbox, it is recommended to familiarize yourself with Congrads's core concept and topics.
+Please read the documentation at https://congrads.readthedocs.io/en/latest/ to get up-to-date.
+
+### 3. **Basic Usage**
+
+Below, a basic example can be found that illustrates how to work with the Congrads toolbox.
+For additional examples, refer to the [examples](https://github.com/ML-KULeuven/congrads/examples) and [notebooks](https://github.com/ML-KULeuven/congrads/notebooks) folders in the repository.
+
+#### 1. First, select the device to run your code on with.
+
+```python
+use_cuda = torch.cuda.is_available()
+device = torch.device("cuda:0" if use_cuda else "cpu")
+```
+
+#### 2. Next, load your data and split it into training, validation and testing subsets.
+
+```python
+data = BiasCorrection(
+    "./datasets", preprocess_BiasCorrection, download=True
+)
+loaders = split_data_loaders(
+    data,
+    loader_args={"batch_size": 100, "shuffle": True},
+    valid_loader_args={"shuffle": False},
+    test_loader_args={"shuffle": False},
+)
+```
+
+#### 3. Instantiate your neural network, make sure the dimensions match up with your data.
+
+```python
+network = MLPNetwork(25, 2, n_hidden_layers=3, hidden_dim=35)
+network = network.to(device)
+```
+
+#### 4. Choose your loss function and optimizer.
+
+```python
+criterion = MSELoss()
+optimizer = Adam(network.parameters(), lr=0.001)
+```
+
+#### 5. Then, setup the descriptor, that will attach names to specific parts of your network.
+
+```python
+descriptor = Descriptor()
+descriptor.add("output", 0, "Tmax")
+descriptor.add("output", 1, "Tmin")
+```
+
+#### 6. Define your constraints on the network.
+
+```python
+Constraint.descriptor = descriptor
+Constraint.device = device
+constraints = [
+    ScalarConstraint("Tmin", ge, 0),
+    ScalarConstraint("Tmin", le, 1),
+    ScalarConstraint("Tmax", ge, 0),
+    ScalarConstraint("Tmax", le, 1),
+    BinaryConstraint("Tmax", gt, "Tmin"),
+]
+```
+
+#### 7. Instantiate metric manager and core, and start the training.
+
+```python
+metric_manager = MetricManager()
+core = CongradsCore(
+    descriptor,
+    constraints,
+    loaders,
+    network,
+    criterion,
+    optimizer,
+    metric_manager,
+    device,
+    checkpoint_manager,
+)
+
+core.fit(max_epochs=50)
+```
+
+## Example Use Cases
+
+- **Optimization with Domain Knowledge**: Ensure outputs meet real-world restrictions or safety standards.
+- **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
+
+- [ ] Add ODE/PDE constraints to support PINNs
+- [ ] Add support for constraint parser that can interpret equations
+- [ ] Determine if it is feasible to add unit and or functional tests
+
+## Research
+
+If you make use of this package or it's concepts in your research, please consider citing the following papers.
+
+- Van Baelen, Q., & Karsmakers, P. (2023). **Constraint guided gradient descent: Training with inequality constraints with applications in regression and semantic segmentation.**
+  Neurocomputing, 556, 126636. doi:10.1016/j.neucom.2023.126636 <br/>[ [pdf](https://www.sciencedirect.com/science/article/abs/pii/S0925231223007592) | [bibtex](https://raw.githubusercontent.com/ML-KULeuven/congrads/main/docs/_static/VanBaelen2023.bib) ]
+
+## Contributing
+
+We welcome contributions to Congrads! Whether you want to report issues, suggest features, or contribute code via issues and pull requests.
+
+## License
+
+Congrads is licensed under the [The 3-Clause BSD License](LICENSE). We encourage companies that are interested in a collaboration for a specific topic to contact the authors for more information or to set up joint research projects.
+
+---
+
+Elevate your neural networks with Congrads! 🚀

congrads-1.0.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+congrads/__init__.py,sha256=uj36sGjM_ldPgD-0aaWh1b-HspZxqUsC2St97sg_6jg,759
+congrads/checkpoints.py,sha256=AnP5lMT94BiOpT2e0b8QvxhW8bacy_U_eGInBGND6tU,7897
+congrads/constraints.py,sha256=NjuRlquJaZHxj0K3A1wW1DQXJKUKM5jBaeSqrhjwCqg,33350
+congrads/core.py,sha256=qcoK_P95j-TY17PWlR0zYbExwe19e391LIMbxZiq5Ek,21061
+congrads/datasets.py,sha256=mfpMKfiJjc6tmeez6EPuyd94O54qZt5KFI4Gs5RAhlc,15855
+congrads/descriptor.py,sha256=ml4IRiEcnRoRYiFgIV2BKpfKjWcLpPsTf0f4l0fTt38,4829
+congrads/metrics.py,sha256=nQuOOVVUeWbxmiFHni9hHFeUd58Gm-Lo0875KG5bHgk,6774
+congrads/networks.py,sha256=fW-1YuscWGSDQwjRItcD8-6R37k1-Do6E2g0HsghB4s,3914
+congrads/requirements.txt,sha256=Cvw0YgcvHcIBeXDzopjuARE3_xEvV6rwajGO9jWOjcE,92
+congrads/transformations.py,sha256=0mbEGdanF7_nFh0lnuBVdImtj3wwIGBMsbg8mkFZ-kw,4485
+congrads/utils.py,sha256=uKOxudT0VgOQ1KCa4uXDADt7KIQISLxzwCipdlfchwo,26252
+congrads-1.0.1.dist-info/LICENSE,sha256=hDkSuSj1L5IpO9uhrag5zd29HicibbYX8tUbY3RXF40,1480
+congrads-1.0.1.dist-info/METADATA,sha256=w-_eel-hPXFmqBBdpL6ksaUTwFGm21Y3bkkxvBQSlgs,9243
+congrads-1.0.1.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+congrads-1.0.1.dist-info/top_level.txt,sha256=B8M9NmtHbmzp-3APHe4C0oo7aRIWRHWoba9FIy9XeYM,9
+congrads-1.0.1.dist-info/RECORD,,

{congrads-0.1.0.dist-info → congrads-1.0.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.6.0)
+Generator: setuptools (75.8.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

congrads/learners.py

@@ -1,233 +0,0 @@
-import logging
-from typing import Union
-from torch import Tensor
-from torch.nn import Module
-from torch.nn.modules.loss import _Loss
-from torch.optim import Optimizer
-
-from .core import CGGDModule
-from .constraints import Constraint
-from .descriptor import Descriptor
-
-
-class Learner(CGGDModule):
-    def __init__(
-        self,
-        network: Module,
-        descriptor: Descriptor,
-        constraints: list[Constraint],
-        loss_function: Union[_Loss, dict[str, _Loss]],
-        optimizer: Optimizer,
-    ):
-        """
-        A class that integrates a neural network with a training and validation loop,
-        supporting single or multi-output loss functions. The class manages the forward pass,
-        training step, and validation step while also configuring the optimizer.
-
-        Args:
-            network (Module): The neural network model to be trained.
-            descriptor (Descriptor): An object that defines the structure of the network,
-                                    including the output layers.
-            constraints (list[Constraint]): A list of constraints that can be applied during training.
-            loss_function (Union[_Loss, dict[str, _Loss]]): A loss function or a dictionary of loss functions
-                                                        for each output layer.
-            optimizer (Optimizer): The optimizer used for training the model.
-
-        Raises:
-            ValueError: If the descriptor does not contain any output layers or if the number of loss functions
-                        does not match the number of output layers when using a dictionary of loss functions.
-        """
-
-        # Init parent class
-        super().__init__(descriptor, constraints)
-
-        # Init object variables
-        self.network = network
-        self.descriptor = descriptor
-        self.loss_function = loss_function
-        self.optimizer = optimizer
-
-        # Perform checks
-        if len(self.descriptor.output_layers) == 0:
-            raise ValueError(
-                'The descriptor class must contain one or more output layers. Mark a layer as output by setting descriptor.add("layer", ..., output=True).'
-            )
-
-        if isinstance(loss_function, _Loss):
-            if len(self.descriptor.output_layers) > 1:
-                logging.warning(
-                    f"Multiple layers were marked as output, but only one loss function is defined. Only the loss of layer {list(self.descriptor.output_layers)[0]} will be calculated and used. To use the same loss function for all output layers, please specify then explicitly."
-                )
-
-        if isinstance(loss_function, dict):
-            if len(self.descriptor.output_layers) != len(loss_function):
-                raise ValueError(
-                    f"The number of marked output layers does not match the number of provided loss functions."
-                )
-
-        # Assign proper step function based on if one or multiple loss functions are assigned
-        if isinstance(loss_function, _Loss):
-            self.training_step = self.training_step_single
-            self.validation_step = self.validation_step_single
-
-        if isinstance(loss_function, dict):
-            self.training_step = self.training_step_multi
-            self.validation_step = self.validation_step_multi
-
-    def forward(self, x):
-        """
-        Perform a forward pass through the network.
-
-        Args:
-            x (Tensor): The input tensor to pass through the network.
-
-        Returns:
-            Tensor: The model's output for the given input.
-        """
-
-        return self.network(x)
-
-    def training_step_single(self, batch, batch_idx):
-        """
-        Perform a single training step using a single loss function.
-
-        Args:
-            batch (tuple): A tuple containing the input and target output tensors.
-            batch_idx (int): The index of the batch in the current epoch.
-
-        Returns:
-            Tensor: The loss value for the batch.
-        """
-
-        self.train()
-
-        inputs, outputs = batch
-        prediction: dict[str, Tensor] = self(inputs)
-
-        layer = list(self.descriptor.output_layers)[0]
-        loss = self.loss_function(prediction[layer], outputs)
-
-        self.log(
-            "train_loss",
-            loss,
-            on_step=False,
-            on_epoch=True,
-        )
-
-        return super().training_step(prediction, loss)
-
-    def training_step_multi(self, batch, batch_idx):
-        """
-        Perform a training step using multiple loss functions, one for each output layer.
-
-        Args:
-            batch (tuple): A tuple containing the input and target output tensors.
-            batch_idx (int): The index of the batch in the current epoch.
-
-        Returns:
-            Tensor: The total loss value for the batch, combining the losses from all output layers.
-        """
-
-        self.train()
-
-        inputs, outputs = batch
-        prediction: dict[str, Tensor] = self(inputs)
-
-        # TODO add hyperparameter to scale loss per function
-        loss = 0
-        for layer in self.descriptor.output_layers:
-            layer_loss = self.loss_function[layer](prediction[layer], outputs)
-            loss += layer_loss
-
-            self.log(
-                f"train_loss_{layer}",
-                layer_loss,
-                on_step=False,
-                on_epoch=True,
-            )
-
-        self.log(
-            "train_loss",
-            loss,
-            on_step=False,
-            on_epoch=True,
-        )
-
-        return super().training_step(prediction, loss)
-
-    def validation_step_single(self, batch, batch_idx):
-        """
-        Perform a single validation step using a single loss function.
-
-        Args:
-            batch (tuple): A tuple containing the input and target output tensors.
-            batch_idx (int): The index of the batch in the current epoch.
-
-        Returns:
-            Tensor: The validation loss for the batch.
-        """
-
-        self.eval()
-
-        inputs, outputs = batch
-        prediction: dict[str, Tensor] = self(inputs)
-
-        layer = list(self.descriptor.output_layers)[0]
-        loss = self.loss_function(prediction[layer], outputs)
-
-        self.log(
-            "valid_loss",
-            loss,
-            on_step=False,
-            on_epoch=True,
-        )
-
-        return super().validation_step(prediction, loss)
-
-    def validation_step_multi(self, batch, batch_idx):
-        """
-        Perform a validation step using multiple loss functions, one for each output layer.
-
-        Args:
-            batch (tuple): A tuple containing the input and target output tensors.
-            batch_idx (int): The index of the batch in the current epoch.
-
-        Returns:
-            Tensor: The total validation loss for the batch, combining the losses from all output layers.
-        """
-
-        self.eval()
-
-        inputs, outputs = batch
-        prediction: dict[str, Tensor] = self(inputs)
-
-        loss = 0
-        for layer in self.descriptor.output_layers:
-            layer_loss = self.loss_function[layer](prediction[layer], outputs)
-            loss += layer_loss
-
-            self.log(
-                f"valid_loss_{layer}",
-                layer_loss,
-                on_step=False,
-                on_epoch=True,
-            )
-
-        self.log(
-            "valid_loss",
-            loss,
-            on_step=False,
-            on_epoch=True,
-        )
-
-        return super().validation_step(prediction, loss)
-
-    def configure_optimizers(self):
-        """
-        Configure the optimizer for training.
-
-        Returns:
-            Optimizer: The optimizer used to update the model's parameters during training.
-        """
-
-        return self.optimizer

congrads-0.1.0.dist-info/LICENSE

@@ -1,34 +0,0 @@
-MIT License
-
-Copyright (c) 2024 DTAI - KU Leuven
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
-
-"Commons Clause" License Condition v1.0
-
-The Software is provided to you by the Licensor under the License, as defined below, subject to the following condition.
-
-Without limiting other conditions in the License, the grant of rights under the License will not include, and the License does not grant to you, the right to Sell the Software.
-
-For purposes of the foregoing, "Sell" means practicing any or all of the rights granted to you under the License to provide to third parties, for a fee or other consideration (including without limitation fees for hosting or consulting/ support services related to the Software), a product or service whose value derives, entirely or substantially, from the functionality of the Software. Any license notice or attribution required by the License must also include this Commons Clause License Condition notice.
-
-Software: All CGGD-Toolbox associated files.
-License: MIT
-Licensor: DTAI - KU Leuven