PySCIPOpt-ML

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.

Documentation

The latest user manual is available on readthedocs.

Contact us

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

Installation

Dependencies

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).

Pip installation

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.

Installation from source

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 git@github.com: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 .

Development

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 frameworks:

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

Source code

You can clone the latest sources with the command:

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

Documentation

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

Testing

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

How to cite this work

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

Funding Acknowledgements

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).