gurobi-machinelearning

Gurobi Machine Learning

Gurobi Machine Learning is an open-source python package to formulate trained regression models in a gurobipy model to be solved with the Gurobi solver.

The package currently supports various scikit-learn objects. It has limited support for Keras, PyTorch and XGBoost. Only neural networks with ReLU activation can be used with Keras and PyTorch.

Documentation

The latest user manual is available on readthedocs.

Contact us

For questions related to using Gurobi Machine Learning please use Gurobi's Forum.

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

If you encounter issues with Gurobi or gurobipy please contact Gurobi Support.

Installation

Dependencies

gurobi-machinelearning requires the following:

• Python >= 3.9
• numpy >= 1.23.0
• gurobipy >= 10.0
• scipy >= 1.9.3

The current version supports the following ML packages:

• torch
• scikit-learn
• tensorflow
• XGBoost

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

The up to date supported and tested versions of each package for the last release can be found in the documentation.

Pip installation

The easiest way to install gurobi-machinelearning is using pip in a virtual environment:

(.venv) pip install gurobi-machinelearning

This will also install the numpy, scipy and gurobipy dependencies.

Please note that gurobipy is commercial software and requires a license. When installed via pip or conda, gurobipy ships with a free license which is only for testing and can only solve models of limited size.

Getting a Gurobi License

Alternatively to the bundled limited license, there are licenses that can handle models of all sizes.

As a student or staff member of an academic institution you qualify for a free, full product license. For more information, see:

• https://www.gurobi.com/academia/academic-program-and-licenses/

For a commercial evaluation, you can request an evaluation license.

Other useful resources to get started:

• https://www.gurobi.com/documentation/
• https://support.gurobi.com/hc/en-us/community/topics/

Development

We value any level of experience in using Gurobi Machine Learning and would like to encourage you to contribute directly to this project. Please see the Contributing Guide for more information.

Source code

You can clone the latest sources with the command:

git clone [e-mail]:Gurobi/gurobi-machinelearning.git

Testing

After cloning the project, you can run the tests by invoking tox. For this, you will need to create a virtual environment and activate it:

python3.10 -m venv .venv
. .venv/bin/activate

Then, you can install tox (>= 3.26.0) and run a few basic tests:

(.venv) pip install tox
(.venv) tox -e py310,pre-commit,docs

tox will install, among others, the aforementioned ML packages into a separate venv. These packages can be quite large, so this might take a while.

Running the full test set

In the above command, we only ran a subset of tests. Running the full set of tests requires having a Gurobi license installed, and is done by running just the tox command without the -e parameter:

(.venv) pip install tox
(.venv) tox

If you don't have a Gurobi license, you can still run the subset of tests, open a PR, and Github Actions will run the tests with a full Gurobi license.

Submitting a Pull Request

Before opening a Pull Request, have a look at the full Contributing page to make sure your code complies with our guidelines.