Use polymake in a docker image

Starting with polymake version 3.2, nightly builds of the stable “master” code line are available as docker images on DockerHub. We offer a small starter script facilitating the usual docker-related rituals like mounting your home directory or passing environment variables to the container. All what you need to do is to download polymake-in-container.sh, make it executable (chmod +x) and run it. It will pull the most recent image and start an interactive polymake shell. It will also create a tiny configuration file POLYMAKE_USER_DIR/container.config where you can tune its behavior. The default location for POLYMAKE_USER_DIR is, as usual, ~/.polymake .

polymake-in-container.sh can also be called with any arguments recognized by polymake, like -a APP_NAME or --script FILE.

Our images are built and tested with recent Docker versions, starting with 17.06-ce. Please visit the Docker Community Edition site if you need to install it on your host. Older docker versions might work as well but we can't guarantee anything, especially regarding MacOS systems.

In fact, you'll obtain two images from the polymake repository. One is called polymake/nightly, it is based on the official ubuntu:16.04 image enhanced with a fresh build of polymake and some useful packages available from the standard Ubuntu distribution. This image is rebuilt almost every night from the most recent stable code version. The starter script will regularly poll the DockerHub repository for new images; you can steer the cadence of updates by editing the configuration file. The second image is called polymake/thirdparty, it contains a plenty of recommended software built from source code because of missing or outdated Ubuntu packages. This includes ppl, TOPCOM, latte, 4ti2, soplex, a recent snapshot of Singular, and more. To see the full list, use docker image ls and docker inspect, then look for “Labels” in the output. The thirdparty image is usually updated much more rarely, but when this happens, a fresh version will be pulled automatically unless you have switched off the automatic updates.

One of the image labels points to the git commit SHA code used for the build. When reporting bugs discovered in an image, please always tell us this code.

The images do not contain any visualization software, for reasons of size reduction and maintainability. So you would still need to have a PDF viewer, a web browser, and/or java runtime environment installed on your computer in order to view pictures produced by polymake. The starter script will populate a folder POLYMAKE_USER_DIR/resources with copies of all data files necessary for collaboration with the visualization software, because programs running directly on your computer can't access files residing within a docker image. Please do not manipulate these files and do not store your personal data in that folder, it will be overwritten with every image update.

For historical reasons we refer to the joint SPP image developed by the Priority Program “Algorithmic and Experimental Methods”; it contains also Singular, normaliz, 4ti2 and GAP. However, the polymake version in it is ancient (2.14) and it's not supported by the starter script.

The dockerized polymake is aimed primarily at end users who just need the existing functionality and don't want to mess with a lengthy process of installing numerous dependencies and compiling it from source code. However, it's much less suitable for advanced users developing own extensions or linking polymake as a callable library in their own software products. Using own extensions with polymake image should theoretically be possible but has not been tested yet. The callable library is included in the image as well, but for obvious reasons it can only be linked in products compiled for the same base image, currently being ubuntu:16.04. Debugging perl code is possible, just add PERL5OPT=-d to the list of environment variables in the script configuration file. Debugging C++ code while running in a container is tricky, it requires a second container with installed gdb or lldb and sharing all namespaces with the polymake container. This seems too burdensome for the daily use.

The dockerized polymake can be used parallel to a locally installed polymake release or a system package. It will share all generic settings like custom variables, preferences and interactive shell input history. However, you should be aware of the data file compatibility issue. Since the image closely tracks the further development of polymake, at some point it will start producing data files (XML) with a higher version number which the statically installed polymake might not be able to consume any longer. Also, using brand new features not matured long enough by daily use can be adversary for the stability, despite of all the tests every nightly build has passed through.

Docker on Mac currently does not support shared memory exchange between the host system and containers. Due to this limitation, Schlegel diagrams and graph visualization in jReality and JavaView are presented as static pictures, without possibility to drag vertices. On Linux, however, the full functionality is available.

It is possible to stick to a stable release image instead of regular pulling nightly builds. To this end, change the following variables in the configuration file POLYMAKE_USER_DIR/container.config

• image_name=polymake/release
• image_tag=RELEASE.NUMBER (e.g. 3.2)

The same way you can switch back to the nightly builds later:

• image_name=polymake/nightly
• image_tag=latest

The thirdparty image contains an up-to-date JavaView release which will be used when you call the javaview function or set it as your default visualization preference. However, you should register at www.javaview.de and obtain a valid license file on your own. Before the first use of JavaView, please set the custom variable $JavaView::Viewer::license_file to the location of your license file. Otherwise you will be reminded to do so both by polymake and JavaView.

Should you decide to stop using the dockerized polymake, run polymake-in-container.sh --uninstall . It will remove the images and the resource copies from ~/.polymake. The script won't remove itself, however, for the case you change your mind later.