Install Docker

First you need to get Docker, see here. For Ubuntu 16.04, this proceeds as follows:

 sudo apt-get update
 sudo apt-get install \
     apt-transport-https \
     ca-certificates \
     curl \
     software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo apt-key fingerprint 0EBFCD88
sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"
sudo apt-get update
sudo apt-get install docker-ce

Getting CPL library Docker Image and Starting

Then we get the CPL library docker image:

sudo docker pull cpllibrary/cpl-library

the dockerhub can be found here along with the dockerfile showing what is installed.

If we don't want to use GUI or store anything from a docker run, we can simply start Docker as follows,

sudo docker run -it --name cplrun cpllibrary/cpl-library

Graphical User Interface

However, some of the examples use matplotlib and interactive Graphical User Interface (GUI). In addition, there are grid design tools which can be used to setup a coupled run. Getting Docker to work with the host display can be a little tricky. The following solution from stackoverflow has been the most successful

XSOCK=/tmp/.X11-unix
XAUTH=/tmp/.docker.xauth
xauth nlist $DISPLAY | sed -e 's/^..../ffff/' | xauth -f $XAUTH nmerge -
sudo docker run -ti -e DISPLAY=$DISPLAY -v $XSOCK:$XSOCK -v $XAUTH:$XAUTH -e XAUTHORITY=$XAUTH cpllibrary/cpl-library

A script to run this is includes in the utils folder of coupler library.

Running CPL library with Docker

The cases which are available are found under examples, these are detailed on the cpl library [1] and include 1) linking example in Fortran, C++ and Python, as well as 2) minimal code to couple in Python an example of 3) visualising a coupled simulation a case where an 4) interactive slider interface is attached to a Fortran code and finally a fully functional 5) 2D CFD and MD example in Python.

The examples can be found by issuing the commands

cd examples
ls

with the examples discussed above (and on the quickstart guide) are in,

sendrecv_globcell
minimal_send_recv_mocks
topology_plot_example
interactive_plot_example
MD_CFD

the easiest way to run these is to cd to each directory and run

./test_all.sh

which is just a bash script to run the various cases. Have a look in these files to see what is done, which is often just a case of running both coupled codes using mpiexec.

In addition, the range of different units tests can be run from the top level /cpl-library directory. These are less visual but include a range of different communication and consistency checks,

test-pytest-mapping 
test-pytest-initialisation 
test-examples 
test-gtests

A Minimal Example

In order to understand a minimal coupled examples, check out

cd /cpl-library/examples/minimal_send_recv_mocks

Have a look at the file, they give an example of a minimal coupled case,

#!/usr/bin/env python
from mpi4py import MPI
from cplpy import CPL

comm = MPI.COMM_WORLD
CPL = CPL()
CFD_COMM = CPL.init(CPL.CFD_REALM)
CPL.setup_cfd(CFD_COMM.Create_cart([1, 1, 1]), xyzL=[1.0, 1.0, 1.0], 
              xyz_orig=[0.0, 0.0, 0.0], ncxyz=[32, 32, 32])
recv_array, send_array = CPL.get_arrays(recv_size=4, send_size=1)

for time in range(5):

    recv_array, ierr = CPL.recv(recv_array)
    print("CFD", time, recv_array[0,0,0,0])
    send_array[0,:,:,:] = 2.*time
    CPL.send(send_array)

CPL.finalize()
MPI.Finalize()

This initialises CPL library, creates a topology with 32 cells in each direction with one processes and loops five times sending and receiving data each time.

The MD file is very similar, but instead has 8 processes. This coupled example can be run as follows:

cplexec -c 1 minimal_CFD.py -m 8 minimal_MD.py

which creates two MPI runs, writes a PORT file and merges the two MPI_COMM_WORLD s

Or, this can be run in the MPMD mode, using,

mpiexec -n 1 python minimal_CFD.py : -n 8 python minimal_MD.py

which runs both codes in a single MPI_COMM_WORLD instance. Be aware that this becomes important if either coupled code uses MPI_COMM_WORLD in any of its MPI communications (which almost every code does).

Mounting Docker Volumes

If you want to run a coupled case and keep the output, you need to use docker volumes, which can be done as follows:

sudo docker run -it --name cplrun --mount source=cpl-vol,target=/cplruns cpllibrary/cpl-library

The example codes should then be copied to /cplruns and run in this as above

rsync -avP /cpl-library/examples/minimal_send_recv_mocks/ /runs/

The output from the run will then be saved between runs

cd /runs/
cplexec -c 1 minimal_CFD.py -m 8 minimal_MD.py

The only output in this run will be save in the /runs/cpl folder in the form of various header files.

On the host operating system this can be access using the command,

sudo docker volume inspect cpl-vol

Getting the path, which in ubuntu defaults to

/var/lib/docker/volumes/cpl-vol/_data