Building and running cases

If you are unfamiliar with docker, we recommend first reviewing the Docker overview wiki page and the references provided therein.

Creating host land model build scripts

Script template

A basic template script is provided in the scripts directory of this github repo. This template includes many of the following setup examples discussed below.

Supported compilers

Currently the docker images only support the use of the gcc compilers. As such the user should make sure to include the --compiler=gnu.

Setting the machine name

When calling create_newcase in your script, the --mach option should be set to docker:

./create_newcase --mach=docker ...

The config_compiler.xml and config_machine.xml files have a docker entry to tell the host land model where to find the necessary libraries and default settings for a case run in the container.

Evaluating the machine environement variable HOSTNAME is a common method to provide build script portability between machines:

./create_newcase --mach=${HOSTNAME} ...

If your script uses this method, you must include the --hostname option for during the container run:

docker run -ti --rm --hostname docker ngeetropic/fates-ctsm-gcc650:latest

Setting up container interfaces

The fates-hlm docker images provide four empty directories by default for the user to interface with: /inputdata, /output, /scripts, and /baselines. They are located on the same directory level as the host land model in the root directory of the container:

I have no name!@docker:/$ ls -ltr
total 84
drwxr-xr-x   2 root root 4096 Jun 14  2018 boot
drwxr-xr-x   1 root root 4096 Apr 22 00:00 var
drwxr-xr-x   1 root root 4096 Apr 22 00:00 usr
drwxr-xr-x   2 root root 4096 Apr 22 00:00 srv
drwxr-xr-x   2 root root 4096 Apr 22 00:00 sbin
drwxr-xr-x   4 root root 4096 Apr 22 00:00 run
drwxr-xr-x   2 root root 4096 Apr 22 00:00 opt
drwxr-xr-x   2 root root 4096 Apr 22 00:00 mnt
drwxr-xr-x   2 root root 4096 Apr 22 00:00 media
drwxr-xr-x   2 root root 4096 Apr 22 00:00 lib64
drwxr-xr-x   1 root root 4096 Apr 23 00:57 lib
drwx------   1 root root 4096 Apr 25 01:15 root
drwxr-xr-x   1 root root 4096 May 16 01:09 bin
drwxrwxrwt   1 root root 4096 May 16 02:25 tmp
drwxr-xr-x   1 root root 4096 Sep 10 00:02 home
drwxr-xr-x   2 root root 4096 Sep 10 00:02 scripts
drwxr-xr-x   2 root root 4096 Sep 10 00:02 output
drwxr-xr-x   2 root root 4096 Sep 10 00:02 inputdata
drwxr-xr-x   2 root root 4096 Sep 10 00:02 baselines
drwxr-xr-x  14 root root 4096 Sep 10 00:02 CTSM
drwxr-xr-x   1 root root 4096 Sep 18 22:24 etc
dr-xr-xr-x 464 root root    0 Sep 18 22:24 proc
dr-xr-xr-x  13 root root    0 Sep 18 22:24 sys
drwxr-xr-x   5 root root  360 Sep 18 22:24 dev

These are provided as the default interface points for passing data back and forth between the container and the user account. Of these directories, /inputdata, /output, and /baselines have been defined in the cime configuration files as the default locations for <DIN_LOC_ROOT>, <CIME_OUTPUT_ROOT>, and <BASELINE_ROOT>. Reference information for machine definitions variables can be found in the CIME documentation.

To interface with these directories the user must provide access to account directories external to the container for reading and writing data as necessary. This is facilitated by the use of docker volume mounts. An example of using the default mount points is below:

docker run -ti --hostname=docker --u $(id -u):$(id -g) \
    -v <external-inputdata-directory>:/inputdata   \
    -v <external-output-scratch-directory>:/output \
    -v <external-baselines-directory>:/baselines   \
    ngeetropics\fates-ctsm-gcc650:latest

Note the use of the -u option. As discusses in the docker overview wiki page, this is necessary to use in conjunction with the -v option to provide the files created by the container the same user id and group id as your account.

Also note that if the script call is not generating or comparing against baselines, the mounting of /baselines is not necessary

Alternatively, Docker can create directories within the container on the fly the user does not wish to use the defaults. To do so the user must make sure to use the ./xmlchange command in your script to override the cime configuration defaults as well as set the correct output directory location for create_newcase:

Override defaults in script example:

# Set the correct output directory for create_newcase
./create_newcase --case=<container-output-directory>/<new-case-name> ...

...

cd <container-output-directory>/<new-case-name>

# Override the .cime configuration default to match the argument for dir locations
./xmlchange CIME_OUTPUT_ROOT=<container-output-directory>
./xmlchange DIN_LOC_ROOT=<container-inputdata-directory>
./xmlchange DIN_LOC_ROOT_CLMFORC=<container-inputdata-directory>/atm/datm7

Corresponding template script section

Corresponding docker run command

docker run -ti --hostname=docker --u $(id -u):$(id -g) \
    -v <external-inputdata-directory>:<container-inputdata-directory> \
    -v <external-output-scratch-directory>:<container-output-directory> \
    <docker-image>:<tag> \
    /scripts/<build-script> <optional-script-inputs>

Building and running cases non-interactively

Although docker can be used interctively using the -ti option with docker run, enabling the user to setup and run a case within the container, it is possible to call the necessary scripts and commands directly from docker run command external from the container:

Calling build script

docker run -ti --hostname=docker --u $(id -u):$(id -g) \
    -v <input-data-directory>:/data \
    -v <output-scratch-directory>:/output \
    -v <scripts-directory>:/scripts \
    <docker-image>:<tag> \
    /scripts/<build-script> <optional-script-inputs>

Run case

docker run -ti --hostname=docker --u $(id -u):$(id -g) \
    -v <input-data-directory>:/data \
    -v <output-scratch-directory>:/output \
    <docker-image>:<tag> \
    /bin/sh -c 'cd /output/<case-directory> && ./case.submit'