Merge pull request #70 from nextsimhub/issue69_docker

Adds a docker image for the domain decomp tool

Dockerfile

@@ -0,0 +1,52 @@
+# Build stage with Spack pre-installed and ready to be used
+FROM spack/ubuntu-jammy:0.21 AS builder
+
+# Install software from spack_devenv.yaml
+RUN mkdir /opt/spack-environment
+COPY spack.yaml /opt/spack-environment/spack.yaml
+RUN cd /opt/spack-environment \
+    && spack env activate . \
+    && spack install --fail-fast \
+    && spack gc -y
+
+# Strip all the binaries
+RUN find -L /opt/views/view/* -type f -exec readlink -f '{}' \; | \
+    xargs file -i | \
+    grep 'charset=binary' | \
+    grep 'x-executable\|x-archive\|x-sharedlib' | \
+    awk -F: '{print $1}' | xargs strip
+
+# Modifications to the environment that are necessary to run
+RUN cd /opt/spack-environment && \
+    spack env activate --sh -d . > activate.sh
+
+# Copy and compile domain_decomp
+COPY . /decomp
+RUN spack env activate /opt/spack-environment \
+    && cd /decomp \
+    && BUILD_DIR=`mktemp -d` \
+    && cmake -G "Unix Makefiles" -B$BUILD_DIR -S. \
+    && cmake --build $BUILD_DIR --config Release \
+    && cp $BUILD_DIR/decomp /usr/bin/
+
+# Bare OS image to run the installed executables
+FROM ubuntu:22.04
+
+# Copy necessary files from the builder stage
+COPY --from=builder /opt/spack-environment /opt/spack-environment
+COPY --from=builder /opt/software /opt/software
+COPY --from=builder /decomp /decomp
+COPY --from=builder /usr /usr
+# paths.view is a symlink, so copy the parent to avoid dereferencing and duplicating it
+COPY --from=builder /opt/views /opt/views
+RUN ln -s /opt/views/view /opt/view
+
+# Copy and set entrypoint
+COPY entrypoint.sh /
+RUN chmod a+x /entrypoint.sh
+ENTRYPOINT [ "/entrypoint.sh" ]
+
+# Set volume mount point for I/O
+RUN mkdir /io
+VOLUME /io
+WORKDIR /io

README.md

@@ -23,6 +23,7 @@ The proposed approach is based on the Recursive Coordinate Bisection (RCB) geome
 ## Getting Started
 
 ### Requirements
+A local installation requires:
 * A Unix-like operating system (e.g., Linux or Mac OS X)
 * ANSI C++ compiler
 * MPI library for message passing (e.g., MPICH or OpenMPI)
@@ -32,6 +33,8 @@ The proposed approach is based on the Recursive Coordinate Bisection (RCB) geome
 * [doctest](https://github.com/doctest/doctest) for unit testing
 * [Boost](https://www.boost.org/) program_options library
 
+Alternatively, the partitioning tool can be used via a Docker image, in which case only a Docker installation is required. See section on Docker below.
+
 #### Building Zoltan from source
 
 ```
@@ -289,3 +292,33 @@ for each MPI process. The file also defines the variables `X_neighbours(P)`, `X_
 `X_neighbour_halos(X_dim)`, where `X` is `top/bottom/left/right`, which correspond to the number of neighbours per process, the
 neighbour IDs and halo sizes of each process sorted from lower to higher MPI rank. Note that `top/bottom/left/right` refer to
 the orientation as shown in Fig. 2 (ASCII diagram).
+
+### How to run using Docker
+
+First, build the docker image, e.g.
+
+```
+$ docker build . -t decomp
+```
+
+This builds a Docker image with the tag `decomp`. The build process takes substantial amount of time (about half an hour on a recent laptop), as it requires building all the prerequsites, as well as the partitioning tool itself.
+
+Once built, the Docker image can be used to partition a given grid using the syntax
+
+```
+$ docker run --rm -v $DATADIR:/io decomp $NPART -g $GRIDIN [other options]
+```
+
+where $DATADIR is the directory containing the input grid file, $NPART is the number of partitions and $GRIDIN is the input grid file name and path relative to $DATADIR. The output will be written to $DATADIR. The `--rm` flag to `docker run` is optional, but it's use is recommended as the docker container which `docker run` creates is not needed afterwards and `--rm` removes this. The online help can also be envoked using
+
+```
+$ docker run --rm decomp -h
+```
+
+A typical use case is to run the program from the same directory the input grid file is in, in which case the command above can be given as
+
+```
+$ docker run --rm -v $PWD:/io decomp $NPART -g $GRIDIN [other options]
+```
+
+and $GRIDIN is simply the file name for the input fill.

entrypoint.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+#
+# Entry point script for a docker image that simply runs the domain decomposition tool, e.g
+# docker build . -t domain_decomp && docker run --rm -v $PWD:/io domain_decomp 8 -g testgrid.nc
+
+. /opt/spack-environment/activate.sh
+
+NP=$1; shift
+
+case $NP in
+    ''|*[!0-9]*)
+        echo "Provide the number of domains before any options"
+        exec decomp --help
+        exit 15
+        ;;
+    *) mpirun --allow-run-as-root -n $NP --oversubscribe decomp "$@" ;;
+esac

spack.yaml

@@ -0,0 +1,17 @@
+spack:
+  packages:
+    all:
+      compiler: [[email protected]]
+  specs:
+  - [email protected]+log+program_options
+  - '[email protected]:'
+  - gmake
+  - [email protected]+mpi+parallel-netcdf
+  - [email protected]
+  - zoltan
+  concretizer:
+    unify: true
+  config:
+    install_missing_compilers: true
+    install_tree: /opt/software
+  view: /opt/views/view