Metadata-Version: 2.4
Name: humancompatible-train
Version: 0.3.0.1
Summary: PyTorch-based package for constrained training of neural networks
Author: Gilles Bareilles, Adam Bosak, Jana Lepsova, Jakub Marecek
Author-email: Andrii Kliachkin <kliacand@fel.cvut.cz>
Maintainer-email: Andrii Kliachkin <kliacand@fel.cvut.cz>
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENCE.txt
Requires-Dist: torch
Requires-Dist: numpy
Provides-Extra: examples
Requires-Dist: ipykernel; extra == "examples"
Requires-Dist: ipympl; extra == "examples"
Requires-Dist: fairret; extra == "examples"
Requires-Dist: folktables; extra == "examples"
Requires-Dist: scikit-learn; extra == "examples"
Requires-Dist: matplotlib; extra == "examples"
Provides-Extra: benchmark
Requires-Dist: fairret; extra == "benchmark"
Requires-Dist: matplotlib; extra == "benchmark"
Requires-Dist: pandas; extra == "benchmark"
Requires-Dist: folktables; extra == "benchmark"
Requires-Dist: pot; extra == "benchmark"
Requires-Dist: hydra; extra == "benchmark"
Requires-Dist: omegaconf; extra == "benchmark"
Provides-Extra: ghost
Requires-Dist: qpsolvers; extra == "ghost"
Requires-Dist: scipy; extra == "ghost"
Dynamic: license-file

# humancompatible-train: a package for constrained machine learning

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Setup](https://github.com/humancompatible/train/actions/workflows/setup.yml/badge.svg)](https://github.com/humancompatible/train/actions/workflows/setup.yml)

The toolkit implements algorithms for constrained training of neural networks based on PyTorch, and inspired by PyTorch's API.
<!-- , as well as a tool to compare stochastic-constrained stochastic optimization algorithms on a _fair learning_ task in the `experiments` folder. -->

## Table of Contents

1. [Basic installation instructions](#basic-installation-instructions)
2. [Using the toolkit](#using-the-toolkit)
3. [Extending the toolkit](#extending-the-toolkit)
4. [License and terms of use](#license-and-terms-of-use)
5. [References](#references)

humancompatible-train is still under active development! If you find bugs or have feature
requests, please file a
[Github issue](https://github.com/humancompatible/train/issues).

## Installation

Use

```bash
pip install humancompatible-train
```

The only dependencies of this package are `numpy` and `torch`.

## Using the toolkit

The toolkit implements algorithms for constrained training of neural networks based on PyTorch.

The algorithms are intended for use in tandem with classic PyTorch optimizers, calculating the Lagrangian and keeping track of the dual variables.

<!-- The algorithms follow the `dual_step()` - `step()` framework: taking inspiration from PyTorch, the `dual_step()` does updates related to the dual parameters and prepares for the primal update (by, e.g., saving constraint gradients), and `step()` updates the primal parameters. -->

In general, your code using `humancompatible-train` would look something like this:

```python
optimizer = torch.optim.Adam(model.parameters(), ...)
dual_optimizer = humancompatible.train.dual_optim.ALM(...)

for inputs, labels in dataloader:
  # evaluate objective
  outputs = model(inputs)
  loss = criterion(outputs, labels)
  # evaluate tensor of constraints
  constraints = <eval_your_constraints>(inputs, labels) 
  # evaluate lagrangian and update dual variables
  lgr = dual_optimizer.forward_update(loss, constraints)
  # backward pass and step
  lgr.backward()
  optimizer.step()
  optimizer.zero_grad()
```

The key difference is calculating the lagrangian using **`lgr = forward_update(loss, constraints)`**, and then running **`lgr.backward()`** instead of `loss.backward()`.

Our idea is to

1. Deviate minimally from the usual PyTorch workflow
2. Make different stochastic-constrained stochastic optimization algorithms nearly interchangable in the code.

### Code examples

You are invited to check out our new API presented in notebooks in the `examples` folder.

The example notebooks have additional dependencies for data and plotting, such as `fairret`. To install those, run

```
pip install humancompatible-train[examples]
```

## Extending the toolkit

**To add a new algorithm**, you can subclass the PyTorch ```Optimizer``` class and proceed following the API guideline presented above.

## Reproducing the Benchmark

The code for benchmarking constrained regularization algorithms is available in the `benchmark` directory.

### Installation instructions

1. Create a virtual environment

**bash** (Linux)

```
python3.11 -m venv fairbenchenv
source fairbenchenv/bin/activate
```

**cmd** (Windows)

```
python -m venv fairbenchenv
fairbenchenv\Scripts\activate.bat
```

2. Install from source.

```
git clone https://github.com/humancompatible/train.git
cd train
pip install -r requirements.txt
pip install .
```

### Usage instructions

The benchmark offers two families of datasets: Folktables and Dutch, several pre-defined constraints, and several constrained optimization algorithms: `ALM` (smoothed and non-smoothed), `SPBM`, and Switching Subgradient; we are currently working to add Stochastic Ghost within the new framework as well.

To run an experiment, run:

```
python run_benchmark.py --dataset <DATASET> [folktables, dutch] --task <TYPE OF CONSTRAINT> [loss, equalized_odds_pairwise, equalized_odds_vec, weight_norm] --n_runs <NUMBER OF RUNS OF EACH METHOD> --n_epochs <NUMBER OF EPOCHS PER RUN>
```

The constraint options are:

- `loss`: constraint(s) on the absolute difference between the classification loss on each group and the overall classification loss;
- `equalized_odds_pairwise`: constraint(s) on the absolute difference between the positive rate between each group;
- `equalized_odds_vec`: constraint on the Positive Rate of each group as defined by `fairret.NormLoss`;
- `weight_norm`: constraint on the Frobenius norm of the weights and biases of each layer of the neural network.

The benchmarking code (all of which is contained in the `benchmark` directory) is easy to parse and extend with other datasets and constraints.


<!-- 
## Reproducing the Benchmark

The code used in [our benchmark paper](https://arxiv.org/abs/2507.04033) is not migrated to the new API yet (WIP).

### Basic installation instructions

The code requires Python version ```3.11```.

1. Create a virtual environment

**bash** (Linux)

```
python3.11 -m venv fairbenchenv
source fairbenchenv/bin/activate
```

**cmd** (Windows)

```
python -m venv fairbenchenv
fairbenchenv\Scripts\activate.bat
```

2. Install from source.

```
git clone https://github.com/humancompatible/train.git
cd train
pip install -r requirements.txt
pip install .
```

If you wish to edit the code of the algorithms, install as an editable package:

```
pip install -e .
```

**Warning**: it is recommended to use Stochastic Ghost with the mkl-accelerated version of the scipy package with Stochastic Ghost; to install it, run

```pip install --force-reinstall -i https://software.repos.intel.com/python/pypi scipy```

after installing requirements.txt; otherwise, the algorithm will run slower. However, this is not supported on MacOS and may fail on some Windows devices.

### Running the algorithms

The benchmark comprises the following algorithms:

- Stochastic Ghost [[2]](#2),
- SSL-ALM [[3]](#3),
- Stochastic Switching Subgradient [[4]](#4).

To reproduce the experiments of the paper, run the following:

```
cd experiments
python run_folktables.py data=folktables alg=sslalm
python run_folktables.py data=folktables alg=alm
python run_folktables.py data=folktables alg=ghost
python run_folktables.py data=folktables alg=ssg
python run_folktables.py data=folktables alg=sgd     # baseline, no fairness
python run_folktables.py data=folktables alg=fairret # baseline, fairness with regularizer
```

Each command will start 10 runs of the `alg`, 30 seconds each.
The results will be saved to `experiments/utils/saved_models` and `experiments/utils/exp_results`.
### Producing plots

The plots and tables like the ones in the paper can be produced using the two notebooks. `experiments/algo_plots.ipynb` houses the convergence plots, and `experiments/model_plots.ipynb` - all the others.

## License and terms of use

humancompatible-train is provided under the Apache 2.0 Licence.

The benchmark part of the package relies on the Folktables package, provided under MIT Licence.
It provides code to download data from the American Community Survey
(ACS) Public Use Microdata Sample (PUMS) files managed by the US Census Bureau.
The data itself is governed by the terms of use provided by the Census Bureau.
For more information, see <https://www.census.gov/data/developers/about/terms-of-service.html>

-->



## Future work

- Add more algorithms
- Add more examples from different fields where constrained training of DNNs is employed

## References

If you use this work, we encourage you to cite [our paper](https://arxiv.org/abs/2509.21254),

```bibtex
@inproceedings{kliachkin2026benchmarking,
  title={Benchmarking Stochastic Approximation Algorithms for Fairness-Constrained Training of Deep Neural Networks},
  author={Kliachkin, Andrii and Lep{\v{s}}ov{\'a}, Jana and Bareilles, Gilles and Mare{\v{c}}ek, Jakub},
  booktitle={14th International Conference on Learning Representations},
  url={https://arxiv.org/abs/2507.04033},
  year={2026}
}

@inproceedings{kliachkin2025humancompatible,
  title={humancompatible.train: Implementing Optimization Algorithms for Stochastically-Constrained Stochastic Optimization Problems},
  author={Kliachkin, Andrii and Lep{\v{s}}ov{\'a}, Jana and Bareilles, Gilles and Mare{\v{c}}ek, Jakub},
  booktitle={NeurIPS Workshop on Constrained Optimization for Machine Learning},
  year={2025}
}
```

<a id="1">[1]</a>
Ding, Hardt & Miller et al. (2021) Retiring Adult: New Datasets for Fair Machine Learning, Curran Associates, Inc..

<a id="2">[2]</a>
Facchinei & Kungurtsev (2023) Stochastic Approximation for Expectation Objective and Expectation Inequality-Constrained Nonconvex Optimization, arXiv.

<a id="3">[3]</a>
Huang, Zhang & Alacaoglu (2025) Stochastic Smoothed Primal-Dual Algorithms for Nonconvex Optimization with Linear Inequality Constraints, arXiv.

<a id="4">[4]</a>
Huang & Lin (2023) Oracle Complexity of Single-Loop Switching Subgradient Methods for Non-Smooth Weakly Convex Functional Constrained Optimization, Curran Associates Inc..
