Welcome to Congrads’ documentation!
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.
Note
The Congrads toolbox is currently under active development. Feedback, issue reports and pull requests are appreciated to further improve the toolbox and suit your needs.
Why should I use Congrads?
The Congrads toolbox provides an easy-to-use interface while remaining highly flexible and modular. You can seamlessly adapt your existing projects to integrate constraints into your network while maintaining performance and stability.
Unlike traditional methods that enforce constraints through post-processing or penalty (regularization) functions, Congrads takes a different approach. The algorithm does not interfere with the update step if the defined constraints are satisfied, ensuring that training progresses optimally. However, if constraints are violated, Congrads adjusts the optimization process dynamically to steer the solution back into the feasible region, where all constraints are satisfied, helping maintain compliance without sacrificing convergence speed.
Possible applications include the following:
Training models that obey real-world physical and operational limits.
Embedding constraints that respect domain-specific restrictions.
Integrate your own governing equations into the training of a deep learning model
Example problem
The animation above illustrates a simple example that makes use of the CGGD algorithm. The objective here is to find the minimum of the function L, while enforcing that the solution must lay in certain intervals (marked in green), the so called feasible region.
As can be seen in the animation, both the approach without constraints and the approach with regularization fail to find a solution that satisfies the constraints and converge to a local minimum. The CGGD algorithm on the other hand, does find an optimum that also satisfies the constraints.
Our approach has some advantages:
Using Congrads you will always converge to points where all the constraints are satisfied and you can’t get stuck in saddle points, local minima or maxima.
This is in contrast to regularization approaches that can get stuck in points where not all constraints are satisfied or the loss is not minimal.
Congrads uses no hyperparameters, which simplifies finding the optimal training settings.
Where to start
Research
If you make use of this package or it’s concepts in your research, please consider citing the following papers:
Theoretical works
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, bibtex]
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, bibtex]
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, bibtex]
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, bibtex]
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.
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 | github profile]
Quinten Van Baelen [email | github profile]
—