Python interface for the SCIP Optimization Suite

This page shows how to install the Python interface that comes with SCIP. A short usage example is shown below.

INSTALL:

Building the Python interface
=============================

The SCIP Python interface uses the shared library of the SCIP Optimization Suite.
Therefore you have to run

    make SHARED=true scipoptlib

from the root of the SCIP Optimization directory. This will result in the creation
of the directory "<path_to_scipopt/lib>" and the shared library "libscipopt.so".

From within the directory "interfaces/python", please execute the following command:

    python setup.py install

You may use the additional options "--user" or "--prefix=<custom-python-path>",
to build the interface locally.

The interface is written in Cython. If you have Cython installed on your system,
the interface will be built from scratch. Otherwise the included pre-built C-code
will be used.

TROUBLESHOOTING
===============

The installation routine tries to generate symbolic links to the "scipopt" library as
well as to the "src" directory of SCIP. In case of installation problems you should
verify the correctness of the links in the directories "lib" and "include".

Note:
-----
You cannot use the interface module from within the "interfaces/python" directory. This
is because Python will try to import the pyscipopt module locally instead of using
the installed one.

Usage information (README):

How to build a model using python-scip
======================================

There are several examples provided in the "tests" folder. These display some functionality of
the interface and can serve as an entry point for writing more complex code. The following
steps are always required when using the interface:

1) It is necessary to import python-scip in your code. This is achieved by including the line

    from pyscipopt import Model

2) Create a solver instance.

    model = Model("Example")    # the name is optional

This is equivalent to calling "SCIPcreate(&scip); SCIPcreateProbBasic(scip, "Example")" in C.

3)  Access the methods in the scip.pyx file using the solver/model instance "model", e.g.:

    x = model.addVar("x")
    y = model.addVar("y", vtype="INTEGER")
    model.setObjective(x + y)
    model.addCons(2*x - y*y >= 0)
    model.optimize()


Writing new plugins
===================

The Python interface can be used to define custom plugins to extend the functionality
of SCIP. You may write a pricer, heuristic or even constraint handler using pure Python code
and SCIP can call their methods using the callback system.
Every available plugin has a base class that you need to extend, overwriting the predefined
but empty callbacks.
Please see "test_pricer.py" and "test_heur.py" for two simple examples.


How to extend the interface
===========================

The interface python-scip already provides many of the SCIP callable library methods.
You may also extend python-scip to increase the functionality of this interface.
The following will provide some directions on how this can be achieved:

The two most important files in python-scip are the scip.pxd and scip.pyx. These two files specify
the public functions of SCIP that can be accessed from your python code.

To make python-scip aware of the public functions you would like to access, you must add them to
scip.pxd. There are two things that must be done in order to properly add the functions to
python-scip.

   1) Ensure any enums, structs or SCIP variable types are included in scip.pxd
   2) Add the prototype of the public function you wish to access to scip.pxd

After following the previous two steps, it is then possible to create functions in python that
reference the SCIP public functions included in scip.pxd. This is achieved by modifying the
scip.pyx file to add the functionality you require.