congrads 0.1.0__tar.gz

congrads-0.1.0/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/PKG-INFO

@@ -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! 🚀

congrads-0.1.0/README.md

@@ -0,0 +1,149 @@
+# 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! 🚀

congrads-0.1.0/congrads/__init__.py

@@ -0,0 +1,21 @@
+# __init__.py
+
+# Only expose the submodules, not individual classes
+from . import core
+from . import constraints
+from . import datasets
+from . import descriptor
+from . import learners
+from . import metrics
+from . import networks
+
+# Define __all__ to specify that the submodules are accessible, but not classes directly.
+__all__ = [
+    "core",
+    "constraints",
+    "datasets",
+    "descriptor",
+    "learners",
+    "metrics",
+    "networks"
+]