3.1 Docker Container

3.1.1 Installing Docker and downloading the ASPECT image

Docker is a lightweight virtualization software that allows to ship applications with all their dependencies in a simple way. It is outside of the scope of this manual to explain all possible applications of Docker, and we refer to the introduction (https://www.docker.com/what-_docker) and installation and quickstart guides (https://www.docker.com/products/docker) on the Docker website for more detailed descriptions of how to set up and use the docker engine. More importantly Docker provides a marketplace for exchanging prepared docker images (called Docker Hub). After setting up the docker engine downloading a precompiled ASPECT image from Docker Hub is as simple as typing in a terminal:

Note that the transfer size of the compressed image containing ASPECT and all its dependencies is about 900 MB. When extracted the image requires about 3.2 GB of disk space.

3.1.2 Running ASPECT models

Although it is possible to use the downloaded ASPECT docker image in a number of different ways, we recommend the following workflow:

1. Create your ASPECT input file in a folder of your choice (possibly also containing any input data that is required by your model) and navigate in a terminal into that directory.
2. Run the docker image and mount the current directory as a read-only volume into the docker container⁵. This is accomplished by specifying the -v flag followed by the absolute path on the host machine, colon, absolute path within the docker container, colon, and specifying read-only permissions as in the example below.

   Make sure your parameter file specifies a model output directory other than the input directory, e.g. /home/dealii/aspect/model_output. When you have started the container run the aspect model inside the container. Note that there are two ASPECT executables in the work directory of the container: aspect and aspect-release. For a discussion of the different versions see Section 4.3, in essence: You should run aspect first to check your model for errors, then run aspect-release for a faster model run.

   To sum up, the steps you will want to execute are:

   docker run -it -v "$(pwd):/home/dealii/aspect/model_input:ro" \ 
     gassmoeller/aspect:latest bash

   Within the container, simply run your model by executing:

   ./aspect model_input/your_input_file.prm
3. After the model has finished (or during the model run if you want to check intermediate results) copy the model output out of the container into your current directory. For this you need to find the name or ID of the docker container by running docker ps -a in a separate terminal first. Look for the most recently started container to identify your current ASPECT container.

   Commands that copy the model output to the current directory could be:

   docker ps -a # Find the name of the running / recently closed container in the output 
   docker cp CONTAINER_NAME:/home/dealii/aspect/model_output .
4. The output data is saved inside your container even after the computation finishes and even when you stop the container. After you have copied the data out of the container you should therefore delete the container to avoid duplication of output data. Even after deleting you will always be able to start a new container from the downloaded image following step 2. Deleting the finished container can be achieved by the docker container prune command that removes any container that is not longer running.

   Note: If you own other finished containers that you want to keep use docker container rm CONTAINER_NAME to only remove the container named CONTAINER_NAME.

   To remove all finished containers use the following command:

   docker container prune

   Alternatively only remove a particular container:

   docker container rm CONTAINER_NAME

You are all set. Repeat steps 1-4 of this process as necessary when updating your model parameters.

3.1.3 Developing ASPECT within a container

The above given workflow does not include advice on how to modify ASPECT inside the container. We recommend a slightly different workflow for advanced users that want to modify parts of ASPECT. The ASPECT docker container itself is build on top of a deal.II container that contains all dependencies for compiling ASPECT. Therefore it is possible to run the deal.II container, mount an ASPECT source directory from your host system and compile it inside of the container. An example workflow could look as following (assuming you navigated in a terminal into the modified ASPECT source folder):

Inside of the container you now find a read-only ASPECT directory that contains your modified source code. You can compile and run a model inside the container, e.g. in the following way:

To avoid repeated recompilations of the ASPECT source folder we recommend to reuse the so prepared container instead of starting new containers based on the deal.II image. This can be achieved by the following commands outside of the container:

For more information on the differences between using images and containers, and how to attach additional terminals to a running container, we refer to the docker documentation (e.g. https://docs.docker.com/engine/getstarted/step_two/).