TL;DR: Dockerized SCIP + Python + jupyter + extras for teaching. The no-hassle setup.

Marc Pfetsch and Sebastian Pokutta • Last revised: May 30, 2020

If you want to use SCIP for teaching then our dockerized SCIP container might be just for you. Zero installation except for the docker service; see below. The container comes with:

  1. SCIP 7.0.2
  2. PySCIPOpt 3.0.0
  3. Python 3.7
  4. Jupyter
  5. Pandas
  6. Numpy
  7. Scipy
  8. Matplotlib
  9. …

Additional packages can be also installed easily. Once the container is started you can simply copy-and-paste the url into your web browser and you are good to go; see further below.

Note. The container is primarily meant for teaching and evaluation purposes and if you want to use SCIP etc. at scale you might want to consider a local installation or a more streamlined container. Note we also provide a container template with only SCIP under scipoptsuite/scipoptsuite:7.0.2 that you can use as a starting point; for example this teaching-centric container was derived from that.

If you have questions use stackoverflow and tag your questions with scip.

Why Docker

Docker allows to bundle and package software etc. into a single container, a lightweight virtual machine. This alleviates installation issues, ensures that installations cannot be broken, and basically all differences between platforms etc. go away. Containerization has become standard for web apps etc. as scalability is almost automatic (through, e.g., kubernetes like mechanisms).

We however here rely on Docker to provide a hassle-free setup of SCIP in a container specifically for evaluation and teaching requiring no compilation, setup etc.

Check out this Docker tutorial if you want to learn more.

Installation

The installation of the Docker engine is very straighforward:

  1. Windows/Mac users: Head to Docker Desktop and install the Docker app.
  2. Linux users: Most distributions provide Docker packages through their package manager; see the Docker install section and pick your distribution.

For Linux Users only

You probably do not want to run containers as root, therefore you might want to follow the post-install instructions:

Create the docker group.

sudo groupadd docker

Add your user to the docker group.

sudo usermod -aG docker $USER

and make the changes to the groups available.

newgrp docker

For Windows 10 Home Users only

Docker is not officially supported on Windows 10 Home however through WSL2 (Microsoft’s native linux support for Windows) you can run Docker; see this blog post for the installation.

Starting the container

Once the Docker engine is running you can start the SCIP container with a simple command from your console. On windows you might want to use the powershell on Mac OS X the terminal:

docker run --rm -p 9001:9001 scipoptsuite/scipoptsuite:7.0.2-teach

The very first time Docker will automatically download the image of the container. For example, on Windows this roughly looks like this (H/T to Kartikey Sharma for providing screenshots):

img2

Figure 1. Upon first time running the container, Docker downloads the image (that is the basis) for the container.

Once the download is complete, the container is automatically started and a jupyter instance is fired up.

img1

Figure 2. jupyter is started automatically.

Simply copy the address with the 127.0.0.1 of the form

http://127.0.0.1:9001/?token=0b2484570cef6f1011c20ec72d7ceb3aa3a1fc7163f46759

from the terminal into your web browser. You will be presented with the (familiar) jupyter interface:

img2

Figure 3. jupyter running in container.

Usage notes

In order to use the container properly a few remarks are in order.

Non-persistance

Containers are (usually) non-persistent. This means, restart or quit the container and your changes or saved code is gone. This is to make sure that the installation cannot be altered or destroyed and is not a bug but a feature. So how do we then interact with the container in a persistent fashion? Very simple: once you are done with your work in the container, you can simply download the jupyter notebook from the file menu in the notebook (the one with the .ipynb). If you later want to resume your work you simply upload the .ipynb file back into the container in the tree view (that is file browser view that jupyter starts up with).

Quitting the container properly

In order to avoid clutter from unused containers piling up in your docker setup, it is advised that you quit the jupyter instance once you are done with your work; the button is to be found in the upper right corner in the tree view. Once quit, the docker engine will remove the container automatically until you start another instance with:

docker run --rm -p 9001:9001 scipoptsuite/scipoptsuite:7.0.2-teach

as before. The automatic removal of the stopped container is what the --rm flag does in the docker run command string above.

Adding additional packages

Need to install additional packages? No problem. Say, you want to use autograd for automatic differentiation. Simply execute:

! pip install autograd

in a jupyter cell. You will get an output that roughly looks as follows:

Collecting autograd
  Downloading autograd-1.3.tar.gz (38 kB)
Requirement already satisfied: numpy>=1.12 in /usr/local/lib/python3.7/site-packages (from autograd) (1.18.4)
Collecting future>=0.15.2
  Downloading future-0.18.2.tar.gz (829 kB)
     |████████████████████████████████| 829 kB 4.9 MB/s eta 0:00:01     |██████▎                         | 163 kB 4.9 MB/s eta 0:00:01
Building wheels for collected packages: autograd, future
  Building wheel for autograd (setup.py) ... done
  Created wheel for autograd: filename=autograd-1.3-py3-none-any.whl size=47990 sha256=0be2bf26f918b3b7c11f93de15a725e770597cbeb6ef5aaef871e6bdd3984ef7
  Stored in directory: /root/.cache/pip/wheels/ef/32/31/0e87227cd0ca1d99ad51fbe4b54c6fa02afccf7e483d045e04
  Building wheel for future (setup.py) ... done
  Created wheel for future: filename=future-0.18.2-py3-none-any.whl size=491058 sha256=2e56f25b59becc842a1534101d6ac222b59a1ed605e93e4a4739f6d823b9a169
  Stored in directory: /root/.cache/pip/wheels/56/b0/fe/4410d17b32f1f0c3cf54cdfb2bc04d7b4b8f4ae377e2229ba0
Successfully built autograd future
Installing collected packages: future, autograd
Successfully installed autograd-1.3 future-0.18.2

From there onwards (until you restart the container), autograd will be available:

import autograd.numpy as np  # Thinly-wrapped numpy
from autograd import grad    # The only autograd function you may ever need

def tanh(x):                 # Define a function
     y = np.exp(-2.0 * x)
     return (1.0 - y) / (1.0 + y)

grad_tanh = grad(tanh)       # Obtain its gradient function
grad_tanh(1.0)

0.419974341614026

If there are routinely certain packages requested we might add those to the container directly also in the future.

For the experts

The following is meant only for those that know Docker a little better and have specific needs. The regular user can just ignore this.

Detached mode

If you want to run in detached mode use -d:

docker run --rm -d -p 9001:9001 scipoptsuite/scipoptsuite:7.0.2-teach

Note however, that you then need to get the url token from the docker log and not the console.

Mapping external directories

If you do not like to up-/download to/from the container you can also map directories into the container with the usual -v option:

docker run --rm -v /Users/xyz:/jupyter -p 9001:9001 scipoptsuite/scipoptsuite:7.0.2-teach

This will map the directory /Users/xyz from the host machine into the container’s /jupyter directory where the jupyter instance looks for its notebooks.

Running SCIP directly

Once you have started the container with docker run, you can also access SCIP or the container’s bash directly via docker exec. Assuming you have named the container with the --name tag, e.g.,

docker run --rm --name scipTeach -p 9001:9001 scipoptsuite/scipoptsuite:7.0.2-teach

we can do the following:

docker exec -it scipTeach scip

will start the SCIP main executable in the container and

docker exec -it scipTeach bash

will give you the container’s bash. Note, that you probably also want to map directories then in order to save the solver’s output etc.

Remove all containers and images

Note. The following assumes that you use Docker only for the SCIP container; otherwise you will know what to do anyways.

In order to stop all running containers:

docker stop $(docker ps -aq)

In order to remove all stop containers:

docker rm $(docker ps -aq)

In order to remove all images:

docker rmi $(docker images -q)

On newer Docker versions you can also prune all stopped containers with a single command:

docker container prune

Changelog

  • 5/30/2020: Incorporated a fix of Felipe Serrano. Added link for running docker on Windows 10 Home.