Quick Start Guide

To get started using the Congrads toolbox, we provide some basic instructions and informative explanations below to get you up-to-date. We will first elaborate on the installation procedure to then explain some core concepts in more detail. Finally, we continue with a step-by-step tutorial to build your first constraint-guided neural network.

Installation

Since Congrads is a Python toolbox, it requires Python to be installed to function. Congrads currently supports Python version 3.11 - 3.13. Get the latest version of Python at https://www.python.org/downloads/.

Congrads heavily relies on PyTorch as its main deep learning framework, leveraging its automatic differentiation and tensor computation capabilities to implement constraint-guided gradient descent. Please refer to the PyTorch’s getting started guide and follow the installation procedure. To enable GPU training, install PyTorch with CUDA support.

Next, install the Congrads package. The recommended way to install the toolbox is to use pip:

pip install congrads

You can also install Congrads together with extra packages required to run the examples:

pip install congrads[examples]

This should automatically install all required dependencies for you. If you want to manually install all dependencies, Congrads depends on the following:

  • PyTorch (install with CUDA support for GPU training, refer to PyTorch’s getting started guide)

  • NumPy (install with `pip install numpy`, or refer to NumPy’s install guide)

  • Pandas (install with `pip install pandas`, or refer to Panda’s install guide)

  • Tqdm (install with `pip install tqdm`)

  • Torchvision (install with `pip install torchvision`)

  • Optional: Tensorboard (install with `pip install tensorboard`)

Requirements and concepts

Before diving into the toolbox, it is probably a good idea to familiarize yourself with its concepts. The core concepts page provides a good starting point that explains some crucial components in the toolbox, along with examples and things to keep in mind.

Congrads requires minimal conditions to integrate your code with the toolbox. You have to structure your code to comply with the following:

  • Your data needs to be provided as a PyTorch Dataset class

  • Your dataset needs to output a dictionary having key “input” and “target”

  • Your network (model) needs to extend torch.nn.Module

  • Your network (model) needs to output a dictionary having key “output”

Example

Here, we compose an implementation for a simple regression task using Congrads. We want to predict normalized daily maximum and minimum temperatures based on 25 input features. We already know certain things in advance that the predictions must satisfy, we already have some domain knowledge. For example, we know that the daily maximum temperature must always be larger than or equal to the daily minimum temperature. By using Congrads, we can easily integrate these constraints into our training procedure to improve the model’s accuracy and reliability.

  1. First, select the device to run your code on with.

use_cuda = torch.cuda.is_available()
device = torch.device("cuda:0" if use_cuda else "cpu")

  1. Next, load your data and split it into training, validation and testing subsets.

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},
)

  1. Instantiate your neural network, make sure the dimensions match up with your data.

network = MLPNetwork(25, 2, n_hidden_layers=3, hidden_dim=35)
network = network.to(device)

  1. Choose your loss function and optimizer.

criterion = MSELoss()
optimizer = Adam(network.parameters(), lr=0.001)

  1. Then, setup the descriptor, that will attach names to specific parts of your network.

descriptor = Descriptor()
descriptor.add_layer("output")
descriptor.add_tag("Tmax", "output", 0)
descriptor.add_tag("Tmin", "output", 1)

  1. Define your constraints on the network.

Constraint.descriptor = descriptor
Constraint.device = device
constraints = [
    ScalarConstraint("Tmin", ">=", 0),
    ScalarConstraint("Tmin", "<=", 1),
    ScalarConstraint("Tmax", ">=", 0),
    ScalarConstraint("Tmax", "<=", 1),
    BinaryConstraint("Tmax", ">", "Tmin"),
]

  1. Instantiate core, and start the training.

core = CongradsCore(
    descriptor=descriptor,
    constraints=constraints,
    loaders=loaders,
    network=network,
    criterion=criterion,
    optimizer=optimizer,
    device=device,
)

core.fit(max_epochs=50)

For more examples, refer to the GitHub repository’s example folder or the notebooks folder for more examples.