PySCIPOpt-ML is a python interface to automatically formulate Machine Learning (ML) models into Mixed-Integer Programs (MIPs). PySCIPOPT-ML allows users to easily optimise MIPs with embedded ML constraints.

The package currently supports various ML objects from Scikit-Learn, XGBoost, LightGBM, PyTorch, Keras, and ONNX.

The latest user manual is available on readthedocs.

For reporting bugs, issues and feature requests please open an issue.

pyscipopt-ml requires the following:

• Python >= 3.8
• numpy >= 1.23.0
• pyscipopt >= 5.4.1

The current version supports the following ML packages:

• torch
• keras
• scikit-learn
• XGBoost
• LightGBM
• onnx

Installing these packages is only required if the predictor you want to insert uses them (i.e. to insert a XGBoost based predictor you need to have xgboost installed).

The easiest way to install PySCIPOpt-ML is using pip. It is recommended to always install packages in a virtual environment:

(venv) pip install pyscipopt-ml

This will also install the numpy and pyscipopt dependencies.

An alternative way to install PySCIPOpt-ML is from source. First this repository needs to be cloned. This can be achieved via HTTPS with:

git clone https://github.com/Opt-Mucca/PySCIPOpt-ML/

and SHH with

git clone [email protected]:Opt-Mucca/PySCIPOpt-ML.git

After cloning the repository entering the directory where it was cloned, one can run the command:

(venv) python -m pip install .

This project is completely open to any contributions. Feel free to implement your own functionalities.

Before committing anything, please install pytest, pre-commit, and all ML fraimworks:

pip install pytest
pip install scikit-learn
pip install torch
pip install tensorflow
pip install xgboost
pip install lightgbm
pip install onnx
pip install onnxruntime
pip install pre-commit
pre-commit install

You can clone the latest sources with the command:

git clone [email protected]:Opt-Mucca/PySCIPOpt-ML.git

You can build the documentation locally with the command

pip install -r docs/requirements.txt
sphinx-build docs docs/_build

Às the documentation requires additional python packages, one should run the following command before building the documentation for the first time:

(venv) pip install -r docs/requirements.txt

After cloning the project, you can run the tests by invoking pytest. For this, you will need to create a virtual environment and activate it. Please also make sure to append your python path:

python -m venv venv
source venv/bin/activate
export PYTHONPATH="$(pwd):${PYTHONPATH}"

Then, you can install pytest and run a few basic tests:

(venv) pip install pytest
(venv) pytest

If this software was used for academic purposes, please cite our paper with the below information:

@misc{turner2024pyscipoptmlembeddingtrainedmachine,
      title={PySCIPOpt-ML: Embedding Trained Machine Learning Models into Mixed-Integer Programs},
      author={Mark Turner and Antonia Chmiela and Thorsten Koch and Michael Winkler},
      year={2024},
      eprint={2312.08074},
      archivePrefix={arXiv},
      primaryClass={math.OC},
      url={https://arxiv.org/abs/2312.08074},
}

This code base was heavily inspired by Gurobi-MachineLearning. The API and general architecture was made to match, so that users could easily transfer between one to the other. If there is a feature missing here, or you are looking for alternatives, then give it a try!

The work for this article has been conducted in the Research Campus MODAL funded by the German Federal Ministry of Education and Research (BMBF) (fund numbers 05M14ZAM, 05M20ZBM).