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

congrads-0.3.0.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.3
+Name: congrads
+Version: 0.3.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-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.18.0 ; extra == 'examples'
+Requires-Python: >=3.11
+Provides-Extra: examples
+Description-Content-Type: text/markdown
+
+<div align="center">
+	<img src="https://github.com/ML-KULeuven/congrads/blob/main/docs/_static/congrads_export.png?raw=true" 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.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)
+
+<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.
+
+
+> **Notice:** All previous `v1.x` releases are **yanked**.  
+> The library is still in active development, and backwards compatibility is not guaranteed.  
+> Please use the new `v0.x` series for ongoing updates.
+
+## 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
+```
+
+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.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`)
+- Optional: **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/tree/main/examples) and [notebooks](https://github.com/ML-KULeuven/congrads/tree/main/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.
+
+## Planned changes / Roadmap
+
+- [ ] Add ODE/PDE constraints to support PINNs
+- [x] Rework callback system
+- [ ] Add support for constraint parser that can interpret equations
+
+## 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.
+
+## Contacts
+
+Feel free to contact any of the below contact persons for more information or details about the project. Companies interested in a collaboration, or to set up joint research projects are also encouraged to get in touch with us.
+
+- Peter Karsmakers [ [email](mailto:peter.karsmakers@kuleuven.be) | [website](https://www.kuleuven.be/wieiswie/en/person/00047893) ]
+- Quinten Van Baelen [ [email](mailto:quinten.vanbaelen@kuleuven.be) | [website](https://www.kuleuven.be/wieiswie/en/person/00125540) ]
+
+## Contributors
+
+Below you find a list of people who contributed in making the toolbox. Feel free to contact them for any repository- or code-specific questions, suggestions or remarks.
+
+- Wout Rombouts [ [email](mailto:wout.rombouts@kuleuven.be) | [github profile](https://github.com/rombie18) ]
+- Quinten Van Baelen [ [email](mailto:quinten.vanbaelen@kuleuven.be) | [github profile](https://github.com/quinten-vb) ]
+
+---
+
+Elevate your neural networks with Congrads! 🚀

congrads-0.3.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+congrads/__init__.py,sha256=XJKWRteSvmTYawgS1Pon8kWhhd3haKo4RGAsyjEGS8Q,383
+congrads/callbacks/base.py,sha256=OChXls-tndgJQOXNfqavnPywHZHn3N87yLKD4kbHDHk,13714
+congrads/callbacks/registry.py,sha256=KkzjDqMS3CkE__PpGrmAEYwRngqGSdQNE8NVWl7ogeA,3898
+congrads/checkpoints.py,sha256=V79n3mqjB48nbNkBELqKDg9iou0b1vc5eRrlcu8aIA4,7228
+congrads/constraints/base.py,sha256=k9OyPS2A4bP3fSEAEANGuw7zofiWlGIxqb5ows1LQWs,10105
+congrads/constraints/registry.py,sha256=k__RfcXle-qDL9OJ-nfwgL9zeM6-ISwgQyIzmx-lsgc,52302
+congrads/core/batch_runner.py,sha256=emc7smJLDHq0J8_J9t9X0RtqrXaYwOP9mmhlX_M78e4,6967
+congrads/core/congradscore.py,sha256=9ZKUVMB9RbmudtuC-MQcNColBYUjb6XLqb0eISzfrGk,12070
+congrads/core/constraint_engine.py,sha256=UEt-tmtJeJX0Wu3ol17Z0A9hacL0F8oouJUwHgIIoDE,8994
+congrads/core/epoch_runner.py,sha256=l0x3uLXQ5I5o1C63wXgL4_QkhFmXxW-jeejNJK6sf18,4093
+congrads/datasets/registry.py,sha256=RfffRiA7Qijc69cJTBJhItTZ8x9B-p1kXMjvcfEC_nA,31102
+congrads/descriptor.py,sha256=tUHF4vvyNzJP5vpq1xn0uhKnOlAkElwG2R9gG4glHvQ,6914
+congrads/metrics.py,sha256=e52QC8yNKsxAndjC3U4WMUnQ_0GmiSlExKtxRRShHao,4625
+congrads/networks/registry.py,sha256=UPzPDU0wI2zoOEvi697QBSDOtaa3Rc0rgCb-tCxbjak,2252
+congrads/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+congrads/transformations/base.py,sha256=KZQkloaDGcqAp8EhlUnHL8VfZqSq8OCqp_Iy_a2Nfns,900
+congrads/transformations/registry.py,sha256=p2cLnt3X1bspEPfR7IVd31qPXQimVe_bRu2VhUOIZj0,2607
+congrads/utils/preprocessors.py,sha256=oqW3hV_yoUd-6I-NSoE61e_JDNEPnBJvvvdsuKd9Ekg,18190
+congrads/utils/utility.py,sha256=zvOAVjQjtmsvyuJm0rF0cy_jApR6qluQsFxk9ItalzE,18893
+congrads/utils/validation.py,sha256=Jj8ZJGJrrH9B02cIaScsQpne3zjyarkPldDdT1pejVA,6208
+congrads-0.3.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+congrads-0.3.0.dist-info/METADATA,sha256=UCutFzaiD6CaeSr9BqtfiyMS-LsDs6Iwpw8QcXSS2jc,10748
+congrads-0.3.0.dist-info/RECORD,,

congrads-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.24
+Root-Is-Purelib: true
+Tag: py3-none-any