congrads 0.1.0__py3-none-any.whl

congrads/descriptor.py

@@ -0,0 +1,65 @@
+class Descriptor:
+    """
+    A class to manage the mapping of neurons to layers and their properties
+    (e.g., output, constant, or variable) in a neural network.
+
+    This class enables the organization and description of network elements,
+    such as associating neurons with specific layers and categorizing layers
+    as outputs, constants, or variables.
+
+    This allows users to easily place constraints on parts of the network by
+    referencing the name that is configured in this class.
+    """
+
+    def __init__(
+        self,
+    ):
+        """
+        Initialize the Descriptor class with empty mappings for neurons and layers.
+
+        This includes:
+            - `neuron_to_layer`: A dictionary mapping neuron names to their corresponding layer names.
+            - `neuron_to_index`: A dictionary mapping neuron names to their corresponding index within a layer.
+            - `output_layers`: A set that holds the names of layers marked as output layers.
+            - `constant_layers`: A set that holds the names of layers marked as constant layers.
+            - `variable_layers`: A set that holds the names of layers marked as variable layers.
+        """
+
+        # Define dictionaries that will translate neuron names to layer and index
+        self.neuron_to_layer: dict[str, str] = {}
+        self.neuron_to_index: dict[str, int] = {}
+
+        # Define sets that will hold the layers based on which type
+        self.output_layers: set[str] = set()
+        self.constant_layers: set[str] = set()
+        self.variable_layers: set[str] = set()
+
+    def add(
+        self,
+        layer_name: str,
+        neuron_names: list[str],
+        output: bool = False,
+        constant: bool = False,
+    ):
+        """
+        Add a layer to the descriptor, associating it with neurons and marking it
+        as an output or constant layer.
+
+        Args:
+            layer_name (str): The name of the layer to be added.
+            neuron_names (list[str]): A list of neuron names that belong to the layer.
+            output (bool, optional): If True, mark this layer as an output layer. Defaults to False.
+            constant (bool, optional): If True, mark this layer as a constant layer. Defaults to False.
+        """
+
+        if output:
+            self.output_layers.add(layer_name)
+
+        if constant:
+            self.constant_layers.add(layer_name)
+        else:
+            self.variable_layers.add(layer_name)
+
+        for index, neuron_name in enumerate(neuron_names):
+            self.neuron_to_layer[neuron_name] = layer_name
+            self.neuron_to_index[neuron_name] = index

congrads/learners.py

@@ -0,0 +1,233 @@
+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/metrics.py

@@ -0,0 +1,64 @@
+from torch import Tensor, tensor, sum, numel
+from torchmetrics import Metric
+
+# NOTE
+
+
+class ConstraintSatisfactionRatio(Metric):
+    """
+    A custom metric to calculate the ratio of satisfied constraints in a neural network model.
+    It computes the proportion of constraints that have been satisfied,
+    where satisfaction is determined based on the provided constraint results.
+
+    This metric tracks the number of unsatisfied constraints and the total number of constraints
+    during the training process, and computes the ratio of satisfied constraints once all updates
+    have been made.
+
+    Attributes:
+        unsatisfied (Tensor): Tracks the number of unsatisfied constraints.
+        total (Tensor): Tracks the total number of constraints processed.
+
+    Note:
+        For more information about custom metrics, we refer to the Pytorch Lightning documentation
+        at https://lightning.ai/docs/torchmetrics/stable/pages/implement.html
+    """
+
+    def __init__(self, **kwargs):
+        """
+        Initializes the ConstraintSatisfactionRatio metric by setting up the
+        state variables to track the number of unsatisfied and total constraints.
+
+        Args:
+            **kwargs: Additional arguments to pass to the base Metric class constructor.
+        """
+
+        # Init parent class
+        super().__init__(**kwargs)
+
+        # Init scalar tensors that will hold metric values
+        self.add_state("unsatisfied", default=tensor(0), dist_reduce_fx="sum")
+        self.add_state("total", default=tensor(0), dist_reduce_fx="sum")
+
+    def update(self, constraint_result: Tensor) -> None:
+        """
+        Updates the state of the metric with the latest constraint results.
+
+        Args:
+            constraint_result (Tensor): A tensor representing the result of
+                                         the constraint checks, where each
+                                         element indicates whether a constraint
+                                         is satisfied (e.g., 0 for satisfied,
+                                         1 for unsatisfied).
+        """
+        self.unsatisfied += sum(constraint_result)
+        self.total += numel(constraint_result)
+
+    def compute(self) -> Tensor:
+        """
+        Computes the constraint satisfaction ratio, defined as:
+        1 - (number of unsatisfied constraints / total constraints).
+
+        Returns:
+            Tensor: The satisfaction ratio as a scalar tensor.
+        """
+        return 1 - (self.unsatisfied.float() / self.total)

congrads/networks.py

@@ -0,0 +1,91 @@
+from torch.nn import Linear, Sequential, ReLU, Module
+
+
+class MLPNetwork(Module):
+    """
+    A multi-layer perceptron (MLP) neural network model consisting of
+    an input layer, multiple hidden layers, and an output layer.
+
+    This class constructs an MLP with configurable hyperparameters such as the
+    number of input features, output features, number of hidden layers, and
+    the dimensionality of hidden layers. It provides methods for both
+    building the model and performing a forward pass through the network.
+
+    Attributes:
+        n_inputs (int): The number of input features.
+        n_outputs (int): The number of output features.
+        n_hidden_layers (int): The number of hidden layers in the network.
+        hidden_dim (int): The dimensionality of the hidden layers.
+        input (nn.Module): The input layer (linear transformation followed by ReLU).
+        hidden (nn.Module): The sequential hidden layers (each consisting of
+                             a linear transformation followed by ReLU).
+        out (nn.Module): The output layer (linear transformation).
+    """
+
+    def __init__(
+        self,
+        n_inputs=25,
+        n_outputs=2,
+        n_hidden_layers=2,
+        hidden_dim=35,
+    ):
+        """
+        Initializes the MLP network with the given hyperparameters.
+
+        Args:
+            n_inputs (int, optional): The number of input features. Defaults to 25.
+            n_outputs (int, optional): The number of output features. Defaults to 2.
+            n_hidden_layers (int, optional): The number of hidden layers. Defaults to 2.
+            hidden_dim (int, optional): The dimensionality of the hidden layers. Defaults to 35.
+        """
+        super().__init__()
+
+        # Init object variables
+        self.n_inputs = n_inputs
+        self.n_outputs = n_outputs
+        self.n_hidden_layers = n_hidden_layers
+        self.hidden_dim = hidden_dim
+
+        # Set up the components of our model
+        self.input = self.linear(self.n_inputs, self.hidden_dim)
+        self.hidden = Sequential(
+            *(
+                self.linear(self.hidden_dim, self.hidden_dim)
+                for _ in range(n_hidden_layers)
+            )
+        )
+        self.out = Linear(self.hidden_dim, self.n_outputs)
+
+    def forward(self, X):
+        """
+        Performs a forward pass through the network.
+
+        Args:
+            X (Tensor): The input tensor to be passed through the network.
+
+        Returns:
+            dict: A dictionary containing the 'input' (original input) and
+                  'output' (predicted output) of the network.
+        """
+        input = X
+        output = self.out(self.hidden(self.input(X)))
+
+        return {"input": input, "output": output}
+
+    @staticmethod
+    def linear(in_features, out_features):
+        """
+        Creates a basic linear block with a linear transformation followed
+        by a ReLU activation function.
+
+        Args:
+            in_features (int): The number of input features.
+            out_features (int): The number of output features.
+
+        Returns:
+            nn.Module: A sequential module consisting of a Linear layer and ReLU activation.
+        """
+        return Sequential(
+            Linear(in_features, out_features),
+            ReLU(),
+        )

congrads-0.1.0.dist-info/LICENSE

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

congrads-0.1.0.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.1
+Name: congrads
+Version: 0.1.0
+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>
+License: 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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=1.12.0
+Requires-Dist: pytorch-lightning>=2.0.0
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: numpy>=1.26.4
+
+# Congrads
+
+**Congrads** is a Python toolbox that brings **constraint-guided gradient descent** capabilities to your machine learning projects. Built with seamless integration into PyTorch and PyTorch Lightning, 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.
+
+> <strong>Note:</strong> The Congrads toolbox is currently in alpha phase. Expect significant changes, potential bugs, and incomplete features as we continue to develop and improve the functionality. Feedback is highly appreciated during this phase to help us refine the toolbox and ensure its reliability in later stages.
+
+## 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.
+- **PyTorch Lightning Support**: Easily plug into PyTorch Lightning projects for scalable and structured model training.
+- **Flexible and extendible**: Write your own custom networks, constraints and dataset classes to easily extend the functionality of the toolbox.
+
+## Installation
+
+Currently, the **Congrads** toolbox can only be installed using pip. We will later expand to other package managers such as conda. 
+
+```bash
+pip install congrads
+```
+
+## Getting Started
+
+### 1. **Prerequisites**
+
+Before you can use **Congrads**, make sure you have the following installed:
+
+- Python 3.7+
+- **PyTorch** (install with CUDA support for GPU training, refer to the [getting started guide](https://pytorch.org/get-started/locally/))
+- **PyTorch Lightning** (preffered version 2.4, [installation guide](https://lightning.ai/docs/pytorch/stable/starter/installation.html))
+
+### 2. **Installation**
+
+Please install **Congrads** via pip:
+
+```bash
+pip install congrads
+```
+
+### 3. **Basic Usage**
+
+#### 1. Import the toolbox
+
+```python
+from congrads.descriptor import Descriptor
+from congrads.constraints import ScalarConstraint, BinaryConstraint
+from congrads.learners import Learner
+```
+
+#### 2. Instantiate and configure descriptor
+
+The descriptor describes your specific use-case. It assigns names to specific neurons so you can easily reference them when defining constraints. By settings flags, you can specifiy if a layer is fixed or if it is an output layer.
+
+```python
+# Descriptor setup
+descriptor = Descriptor()
+descriptor.add("input", ["I1", "I2", "I3", "I4"], constant=True)
+descriptor.add("output", ["O1", "O2"], output=True)
+```
+
+#### 3. Define constraints on your network
+
+You can define constraints on your network using the names previously configured in the descriptor. A set of predefined constraint classes can be used to define inequalities on input or output data.
+
+```python
+# Constraints definition
+Constraint.descriptor = descriptor
+constraints = [
+    ScalarConstraint("O1", gt, 0),      # O1 > 0
+    BinaryConstraint("O1", le, "O2"),   # O1 <= O2
+]
+```
+
+#### 4. Adjust network
+
+Your regular Pytorch network can be used with this toolbox. We only require that the output of your model's forward pass is a dictionary of layers. The keys must match the descriptor settings.
+
+```python
+def forward(self, X):
+    input = X
+    output = self.out(self.hidden(self.input(X)))
+
+    return {"input": input, "output": output}
+```
+
+You then can use your own network and directly assign it to the learner.
+
+#### 5. Set up network and data
+
+Next, instantiate the adjusted network and the data. At the moment, we require the data to be implemented as a `LightningDataModule` class.
+
+```python
+# Data and network setup
+network = YourOwnNetwork(n_inputs=4, n_outputs=2, n_hidden_layers=3, hidden_dim=10)
+data = YourOwnData(batch_size=100)
+```
+
+#### 6. Set up learner
+
+You can specify your own loss function and optimizer with their own settings to be used for learning the model.
+
+```python
+# Learner setup
+loss_function = MSELoss()
+optimizer = Adam(network.parameters(), lr=0.001)
+
+learner = Learner(network, descriptor, constraints, loss_function, optimizer)
+```
+
+#### 7. Set up trainer
+
+Finally, set up a trainer to start the actual training of the model.
+
+```python
+# Trainer setup
+trainer = Trainer(max_epochs=100)
+
+# Train model
+trainer.fit(learner, data)
+```
+
+## Example Use Cases
+
+- **Optimization with Domain Knowledge**: Ensure outputs meet real-world restrictions or safety standards.
+- **Physics-Informed Neural Networks (PINNs)**: Enforce physical laws as constraints in your models.
+- **Improve Training Process**: Inject domain knowledge in the training stage, increasing learning efficiency.
+
+## Roadmap
+
+- [ ] Documentation and Notebook examples
+- [ ] Add support for constraint parser that can interpret equations
+- [ ] Add better handling of metric logging and visualization
+- [ ] Revise if Pytorch Lightning is preferable over plain Pytorch
+- [ ] Determine if it is feasible to add unit and or functional tests
+
+## 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 [MIT License with a Commons Clause](LICENSE). This means you are free to use, modify, and distribute the software, but you may not sell or offer it as part of a paid service without permission. We encourage companies that are interested in a collaboration for a specific topic to contact the authors for more information.
+
+---
+
+Elevate your neural networks with Congrads! 🚀