Support Running AtChem2 in a docker container (AtChem#518)

* add container files

* update to run with singularity

* tidy Docker files and update README

* change mechanism location to full path

* user now provides folder containing mechanism at runtime, rather than this being hardcoded to `mcm`

* Add copyright notices to new files

* Add comments to scripts and update some directory names

* Remove hardcoding of version in Dockerfile, it will now build from whichever branch it is run in.

* update CI checkout v3 -> v4;  remove testing on macos 11

* Make entrypoint path absolute for apptainer compatibility

* Stop outputs nesting if model is rerun - now rerunning a model overwrites existing outputs as expected

Author: willdrysdale

.github/workflows/ci.yml

@@ -45,11 +45,11 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-22.04, macos-11] #, macos-12]
+        os: [ubuntu-22.04, macos-12]
         fortran: [9, 10, 11]
-        # exclude: #TODO: fortran9 does not work on macos12
-        # - os: macos-12
-        #   fortran: 9
+        exclude: #TODO: fortran9 does not work on macos12
+        - os: macos-12
+          fortran: 9
       fail-fast: false
 
     # -------------------------------------------------------------
@@ -63,7 +63,7 @@ jobs:
 
       # -------------------------------------------------------------
       # (1) Checkout the repository under $GITHUB_WORKSPACE
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 2
 

Dockerfile

@@ -0,0 +1,30 @@
+# -----------------------------------------------------------------------------
+#
+# Copyright (c) 2009 - 2012 Chris Martin, Kasia Boronska, Jenny Young,
+# Peter Jimack, Mike Pilling
+#
+# Copyright (c) 2017 Sam Cox, Roberto Sommariva
+#
+# Copyright (c) 2024 Will Drysdale, Beth Nelson
+#
+# This file is part of the AtChem2 software package.
+#
+# This file is covered by the MIT license which can be found in the file
+# LICENSE.md at the top level of the AtChem2 distribution.
+#
+# -----------------------------------------------------------------------------
+
+# get base image
+FROM rockylinux:8.9
+
+# copy the repo into the container
+COPY . /atchem/
+
+# run install script
+RUN /atchem/docker/install.sh
+
+# add lable for github container registry
+LABEL org.opencontainers.image.source=https://github.com/wacl-york/AtChem2
+
+# set entrypoint as the script that runs on `docker run`
+ENTRYPOINT [ "/atchem/docker/entrypoint.sh" ]

README.md

@@ -44,3 +44,49 @@ Set the initial conditions, the required outputs and the other model parameters
 The `atchem2` executable accepts several command line arguments to customize the location of the configuration, input and output directories, and of the shared library. More information on AtChem2, and detailed instructions on its installation, configuration and use can be found in the manual (`doc/AtChem2-Manual.pdf`) and in the GMD paper (see `CITATION.md`).
 
 The [AtChem2 wiki](https://github.com/AtChem/AtChem2/wiki) contains a summary of the instructions to install, compile, run and contribute to the development of Atchem2, together with additional information and a list of [known issues](https://github.com/AtChem/AtChem2/wiki/Known-Issues) with the suggested solutions or workarounds.
+
+
+Docker Container 
+---------------------------------
+
+A containerised version of `AtChem2` is available. Currently this is built for release 1.2.2. The container is built on Rocky Linux 8.9 and pre-installs the `cvode` and `openlibm` dependencies via their relevant `tools/install/install_*.sh` scripts.
+
+The image can be downloaded via:
+
+```
+docker pull ghcr.io/wacl-york/atchem2:1.2.2
+```
+
+When running the container, changes to the model (e.g. those made to configurations, constraints and mechanisms) should be in a folder that matches the AtChem2 directory structure. This folder is then mounted as a volume to the container with the name `/data_transfer/`. The mechanism to use is provided as a positional argument to the image e.g. `./model/my_mech.fac`.
+
+#### Example host file structure:
+```
+my_model_run
+└── model
+    ├── configuration
+    ├── constraints
+    └── my_mech.fac
+```
+
+#### Example Docker run command:
+
+```
+docker run -it --rm -v /path/to/my_model_run:/data_transfer ghcr.io/wacl-york/atchem2:1.2.2 ./model/my_mech.fac
+```
+
+Outputs will be copied to `my_model_run/model/output` on completion.
+
+#### Running on Singularity / Apptainer
+
+Some HPC systems use Singularity / Apptainer instead of Docker as their container engine. This image is compatible with those aswell. The image can be converted to a .sif via:
+
+```
+apptainer pull path/to/image/atchem2.sif docker://ghcr.io/wacl-york/atchem2:1.2.2
+```
+#### Example Apptainer run command:
+
+```
+apptainer run --bind /path/to/my_model_run/:/data_transfer/ path/to/image/atchem2.sif ./model/my_mech.fac
+```
+> [!Note]
+> The leading "/" is important when mounting the volume for apptainer, as the container opens in the users "~" directory whereas Docker opens at "/"

docker/entrypoint.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/bash
+# -----------------------------------------------------------------------------
+#
+# Copyright (c) 2009 - 2012 Chris Martin, Kasia Boronska, Jenny Young,
+# Peter Jimack, Mike Pilling
+#
+# Copyright (c) 2017 Sam Cox, Roberto Sommariva
+#
+# Copyright (c) 2024 Will Drysdale, Beth Nelson
+#
+# This file is part of the AtChem2 software package.
+#
+# This file is covered by the MIT license which can be found in the file
+# LICENSE.md at the top level of the AtChem2 distribution.
+#
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# This script is run everytime the container is run. 
+#
+# First it copies the /atchem/ directory that is created during the build to 
+# the home directory of the user running the container. This is for
+# compatibility with singularity, where the user running the container is not
+# root, and therefore cannot modify the model files in place. 
+#
+# Next it moves the user configuration from /data_transfer/ and copies it into
+# the ~/atchem/ directory. This /data_transfer/ directory is created when the
+# the user mounts a volume when running the container (e.g `docker run -v...`)
+#
+# We then move to the ~/atchem directory and build the model using the mechanism
+# specified by the user as a runtime argument to `docker run`. 
+#
+# Then the model is run by executing the newly built atchem2 file. 
+#
+# On completion the atchem model output directory is copied to the data_transfer
+# directory and as such onto the host filesystem
+# -----------------------------------------------------------------------------
+
+# make a copy to home to allow for compatibility with singularity 
+\command cp -rf /atchem/ ~/ 
+
+# Transfer in user config
+\command cp -rf /data_transfer/* ~/atchem/
+
+# move into atchem dir
+cd ~/atchem/
+
+# build model using user specified mechanism
+./build/build_atchem2.sh $1
+echo $1
+
+# run model
+./atchem2
+
+# copy outputs to data_transfer / host filesystem
+\command cp -rf ~/atchem/model/output /data_transfer/model/

docker/install.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# -----------------------------------------------------------------------------
+#
+# Copyright (c) 2009 - 2012 Chris Martin, Kasia Boronska, Jenny Young,
+# Peter Jimack, Mike Pilling
+#
+# Copyright (c) 2017 Sam Cox, Roberto Sommariva
+#
+# Copyright (c) 2024 Will Drysdale, Beth Nelson
+#
+# This file is part of the AtChem2 software package.
+#
+# This file is covered by the MIT license which can be found in the file
+# LICENSE.md at the top level of the AtChem2 distribution.
+#
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# This is the install script that is run when the container is built. It 
+# installs the necessary dependacies for installing AtChem2 (gcc-gfortran,
+# wget, cmake and python3.11).
+#
+# It then runs the install scripts provided with the model (install_cvode.sh 
+# and install_openlibm.sh) to install additional dependancies required to build
+# the model.
+# 
+# Next it produces the Makefile from the skeleton, and amends the dependancy 
+# paths.
+# 
+# Finally it does some housekeeping, updating the build_atchem2.sh to be able
+# to find the python installation, and makes the docker entrypoint script 
+# executable. 
+# -----------------------------------------------------------------------------
+
+# Install dependancies from package repository
+dnf install -y which gcc-gfortran wget cmake python3.11
+
+# make directories
+mkdir /atchem-lib
+# mkdir /atchem
+
+# move to /atchem so the dependacy installation scripts work correctly.
+cd atchem
+
+# Install dependancies to /atchem-lib
+./tools/install/install_cvode.sh /atchem-lib/ 
+./tools/install/install_openlibm.sh /atchem-lib/
+
+# Change atchem dependancy paths and create Makefile from skeleton
+sed 's,cvode/lib,/atchem-lib/cvode/lib,g' tools/install/Makefile.skel > ./Makefile
+sed -i 's,openlibm-0.8.1,/atchem-lib/openlibm-0.8.1,g' ./Makefile
+
+# Fix python command to match installed version
+sed -i "s/python/python3/g" ./build/build_atchem2.sh
+chmod +x docker/entrypoint.sh