CPL library in 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  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,
the easiest way to run these is to cd to each directory and run
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
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