This document lists the steps for setting up a solver submission for the MiniZinc Challenge 2019.
Like last year, we provide a docker image www.docker.com that the participants have to extend with their solver to take part in this year challenge.
In comparison to virtual machines as used in the previous challenges, docker provides a number of advantages:
There are two main concepts docker image and docker container. Intuitively, a docker image is a OS that cannot change its state and cannot run directly, but can be shared with other through docker hub. Opposed to an image, a docker container is an instance of an image that can be changed and run as it would be your local machine. Multiple containers of the same docker image can be created and run independently. The current state of a docker container can be stored as a docker image and then shared with others. The stored image is the image that the container was created from plus the changes made during its executing.
Docker CE (Community Edition) is available for different operation system including Ubuntu, Mac OS X, and Windows. For example, go to Docker For MacOS, Docker For Windows, and Docker For Ubuntu. Read through all instructions and requirements on the webpage before you start the installation. Follow the installation steps provided on that page. You can test your installation by executing following command.
docker run hello-world
For the submission process, you need to create an account to Docker Hub, in which you upload your submission (docker image). Docker hub provides you the facility to store your image in a repository with a tag. Note that you can create one private repository for free, which you can share with the MiniZinc Challenge Team. Note too that a repository is created via the web pages.
The docker image was created via configuration file called Dockerfile (download MiniZinc Dockerfile here) and is available at the repository
minizinc/mznc2019 with the current tag
1.0. Pull the repository via command line by this command.
docker pull minizinc/mznc2019:1.0
The image contains a minimal installation of Ubuntu 18.04 and MiniZinc 2.3.1, which is installed in the
/usr/local/bin directory. In the MiniZinc directory
/minizinc, there are the three shell scripts
mzn-exec-fd (for the FD class),
mzn-exec-free (for the FREE class), and
mzn-exec-par (for the PAR class) (these are the same as in previous MiniZinc Challenges). If you sumit a MiniZinc solver then you need to modify them accordingly. If you submit a FlatZinc solver then you may need to add, modify, or remove parameters that are used for calling your FlatZinc solver. In the case of a FlatZinc solver, there must an executable at
/entry_data/fzn-exec and the solver's MiniZinc library must be located in the folder
/entry_data/mzn-lib. You should install your solver in the directory
If you want to inspect the image via a bash shell then create a container, interactively run the container, and delete the container after execution via this command.
docker run -it --rm minizinc/mznc2019:1.0 /bin/bash
There are two ways to prepare a solver submission. One way is to use a configuration file (dockerfile), which directly creates the docker image with the solver installed and the other way is to create an instance, install the solver via command line, and then store the instance state as a docker image. The first way is preferred, because it can be re-used (with one or two modification) for a future submission and the creation is automatically via one docker command.
There are two ways to build an image from a dockerfile. The first way is to specify a folder that includes the dockerfile named
Dockerfile and any other files required for creation the image and the second way is to use standard in (stdin). In both cases, the starting point is a dockerfile. For example, we use dockerfiles to create the MiniZinc submission for Chuffed (download Chuffed dockerfile here) and Gecode (download Gecode dockerfile here).
Dockerfiles contain a sequence of statements where
ENV are the most important ones and briefly describe here. Please look at the dockerfiles that are linked above for the MiniZinc Challenge, Chuffed, and Gecode image. They contain many examples for these statements.
FROM <repository>:<tag> [AS <build stage name>]
FROM specifies from which repository and tag an image is created from, and starts a new build stage. For example, ubuntu:16.04 for the Ubuntu 16.04 LTS image. For multi-stage builds, you want to specify a build stage name that you can refer to in later build stages. The last stage is the image that will be created. All other statements will modify the build from the latest
FROM statement. The last stage statement must be
ADD <Source File> <Target File>
The statement adds a file from local directory (when image is built via folder option) or from Internet and stores it in the build as specified in Target File.
COPY --from=<build stage name> <Source Path/File> <Target Path/File>
The statement copies a path or files across from a previous build stage specified in build stage name to the current build stage.
The statement executes any command available in the build. Long lines can be broken up by ending a line with this character
ENV <Environment Command>
The statement sets up an environment variable in the build.
Build an image from a docker file with a context (folder must contain a file named
Dockerfile). In this way, you can add files in the context to your build. Choose an appropriate repository name and tag.
docker build -t <repository name>:<tag> <path Dockerfile>
Use this command in a terminal in Mac OS X or Linux distributions. You can freely chose the name of your dockerfile. Choose an appropriate repository name and tag.
docker build -t <repository name>:<tag> - < <dockerfile>
Use this command in a Powershell in Windows OS.
Get-Content <dockerfile> | docker build -t <repository name>:<tag> -
Creating the image via a docker container might be a more familiar way, because you prepare your submission by using a bash terminal for installation of the solver as you may have done for the previous MiniZinc challenges. If you chose this way then we strongly suggest that you record your command in a dockerfile, so that you can create the image from a dockerfile next time and save a lot of time.
Create and run a container from the MiniZinc Challenge image by this command. This command also names the container
docker run -it --name solver minizinc/mznc2019:1.0 /bin/bash
The container should be running now and you should have access to it via the command line. You can test it by the command
ls, which should result in the listing of all files and paths in the root directory
/ of the container.
Install your solver as you would normally do in Ubuntu. Modify the files
mzn-exec-par if needed.
Create a docker image from your container
solver by running this command. Choose an apriorate repository name and tag.
docker commit solver <repository name>:<tag>
Note that you can interrupt the installation (Step 2) at anytime by, for example, exiting the bash terminal of the container. On your local machine, use this command for listing all running containers
docker container ls
or this command for all constainers
docker container ls --all
solver should appear in the list. If the container is not running start the container in interactive mode by
docker container start -i solver
If the container is running then access it by
docker exec -it solver /bin/bash
If you want to stop a running container outside from the container use this command.
docker container stop solver
/minizinc in the MiniZinc image contains a very simple MiniZinc model (
/minizinc/test.mzn) and one DataZinc file (
/minizinc/2.dzn). To test that your solver is correctly setup for the MiniZinc Challenge execute following commands for the search classes you enter.
A successful test should return following output on the screen.
x = 2; ----------
You have finalised your solver docker image and have an account on Docker Hub. Following steps need to be performed.
You may have to rename your image to match your username at Docker Hub. Use the following command to do so if using the image id
docker tag <image id> <username>/<target image>:<tag>
if using the image id of your solver docker image, or
docker tag <repository>:<tag> <username>/<name>:<tag>
if using the repository name and tag.
Login into your account via command line if not already logged in.
Push/upload your images to your account.
docker push <username>/<name>:<tag>
If you want to make your repository private then go to Docker Hub, sign in your account, click on your repository, click on settings, and then on the button
Logout via command line.
Docker has an abundance of command-line commands, which are extensively describe in the Online Reference Manual. A short cheat sheet can be found here or a longer one at here. Below is our cheat sheet. Note that
<image id> always can be replaced by
||Show version number of docker installation.|
||Show system-wide information.|
||Login in docker hub.|
||Logout from docker hub.|
||List all images on the local machine.|
||Pull a docker image from docker hub.|
||Push a docker image to docker hub.|
||List the build history of the docker image.|
||Create an image from a dockerfile called
||Create an image from a dockerfile on Mac OS X or Linux distribution.|
||Create an image from a dockerfile using PowerShell on Windows OS.|
||Rename a local image to the image name, e.g., to the image name of your repository.|
||Create image from the current state of a container.|
||Remove docker image.|
||Creating a docker container from a image and running the container in an interactive mode using a shell terminal.|
||Same as above, but giving the container a name.|
||Creating a container, running the command
||Delete a docker container.|
||List all docker containers that are running.|
||List all docker containers.|
||List all docker containers in quiet mode.|
||Start a docker container.|
||Access a running docker container in an interactive mode using a shell terminal.|
||Stop a running docker container|