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:
- SCIP 7.0.2
- PySCIPOpt 3.0.0
- Python 3.7
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
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.
The installation of the Docker engine is very straighforward:
- Windows/Mac users: Head to Docker Desktop and install the Docker app.
- 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.
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
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):
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.
Figure 2. jupyter is started automatically.
Simply copy the address with the
127.0.0.1 of the form
from the terminal into your web browser. You will be presented with the (familiar) jupyter interface:
Figure 3. jupyter running in container.
In order to use the container properly a few remarks are in order.
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.
If you want to run in detached mode use
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
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
- 5/30/2020: Incorporated a fix of Felipe Serrano. Added link for running docker on Windows 10 Home.