congrads

KO | EN

gitlite — search

#react #ai #typescript #go #machine-learning #rust #deep-learning #nodejs #macos #java #windows #kubernetes #pytorch #open-source

(★ 9)

Incorporate constraints into neural network training for more reliable and robust models.

congrads 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
	<img src="https://github.com/ML-KULeuven/congrads/blob/main/docs/_static/congrads_export.png?raw=true" height="200">
	
	Incorporate constraints into neural network training for more reliable and robust models.

[![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)

</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_layer("output")
descriptor.add("Tmax", "output", 0)
descriptor.add("Tmin", "output", 1)
```

#### 6. Define your constraints on the network.

```python
Constraint.descriptor = descriptor
Constraint.device = device
constraints = [
 ScalarConstraint("Tmin", ">=", 0),
 ScalarConstraint("Tmin", "<=", 1),
 ScalarConstraint("Tmax", ">=", 0),
 ScalarConstraint("Tmax", "<=", 1),
 BinaryConstraint("Tmax", ">", "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.

### Theoretical works

- 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 [ [pdf](https://www.sciencedirect.com/science/article/abs/pii/S0925231223007592) | [bibtex](https://raw.githubusercontent.com/ML-KULeuven/congrads/main/docs/_static/VanBaelen2023.bib) ]

### Applied works

- Meire, M., Van Baelen, Q., Ooijevaar, T., Karsmakers, P. (2026). **Constraint Guided Recurrent Convolutional AutoEncoders for Condition Indicator Estimation.** In: Proceedings of ESANN. Presented at the European Symposium on Artificial Neural Networks, Computational Intelligence and Machine Learning, Bruges, Belgium.

- Rombouts, W., Van Baelen, Q., Karsmakers, P. with Rombouts, W. (corresp. author) (2025). **Constraint-Guided PINNs: A Constrained Optimization Approach.** In: CEUR Workshop Proceedings: vol. 4125, (124-130). Presented at the ECAI workshop ANSyA, Bologna, Italy, 25 Oct 2025-30 Oct 2025. [ [pdf](https://ceur-ws.org/Vol-4125/paper_30.pdf) | [bibtex](https://raw.githubusercontent.com/ML-KULeuven/congrads/main/docs/_static/Rombouts2025.bib) ]

- Tefera, Y., Van Baelen, Q., Meire, M., Luca, S., Karsmakers, P. with Tefera, Y. (corresp. author) (2025). **Constraint-Guided Learning of Data-Driven Health Indicator Models: An Application on Bearings.** INTERNATIONAL JOURNAL OF PROGNOSTICS AND HEALTH MANAGEMENT, 16 (2), Art.No. ARTN 4268. doi: 10.36001/IJPHM.2025.v16i2.4268 [ [pdf](http://dx.doi.org/10.36001/IJPHM.2025.v16i2.4268) | [bibtex](https://raw.githubusercontent.com/ML-KULeuven/congrads/main/docs/_static/Tefera2025.bib) ]

- Meire, M., Van Baelen, Q., Ooijevaar, T., Karsmakers, P. with Meire, M. (corresp. author) (2025). **Constraint guided autoencoders for joint optimization of condition indicator estimation and anomaly detection in machine condition monitoring.** MACHINE LEARNING, 114 (7), Art.No. ARTN 153. doi: 10.1007/s10994-025-06779-0 [ [pdf](http://dx.doi.org/10.1007/s10994-025-06779-0) | [bibtex](https://raw.githubusercontent.com/ML-KULeuven/congrads/main/docs/_static/Meire2025.bib) ]

- Meire, M., Van Baelen, Q., Ooijevaar, T., Karsmakers, P. (2023). **Constraint-Guided Autoencoders to Enforce a Predefined Threshold on Anomaly Scores: An Application in Machine Condition Monitoring.** Journal of Dynamics, Monitoring and Diagnostics, 2 (2), 144-154. doi: 10.37965/jdmd.2023.234 [ [pdf](http://dx.doi.org/10.37965/jdmd.2023.234) | [bibtex](https://raw.githubusercontent.com/ML-KULeuven/congrads/main/docs/_static/Meire2023.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

congrads 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

congrads

congrads 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README