Docker MOM-5

IMPORTANT NOTE

Do you have git installed?

IF YOU ARE USING WINDOWS USE for clonning the directory

git clone https://git.io-warnemuende.de/boergel/mom5-docker.git --config core.autocrlf=input

This is AFAIK the only way to avoid end of line reading errors.

What are you going to do?

This repository creates a docker image that compiles MOM5 using Ubuntu 18.04. The docker image can be distributed to students or can be used as a first introductin to MOM5.

This image can be used on your personal computer. However, docker allows multi-processing, hence, computing on the IOW-servers should be also possible.

In the following you will find a step by step guide to run your own first MOM5 ocean only (MOM-SIS) simulation.

Step-by-step guide

Install docker on your local machine

Docker Engine is supported on x86_64 (or amd64), armhf, and arm64 architectures.

It is advised to follow the description give on the offical docker homepage

Download the forcing data

The forcing data can be download from the butto below. It will open a website called zenodo. zenodo can be used to share data.

The access is restricted and you need to ask for permission. Once you have been given access download the data and put them into ./MOM_forcing.

What is a dockerfile

Probably you are already familiar with Virtual Machine (VMs). Docker is similiar. The key difference that docker is is a container based technology and containers are just user space of the operating system.

The dockerfile is giving a description on how to build the container. Please have a look at the dockerfile and see the comments.

FROM ubuntu:18.04
ENV PATH="/home/mom5/miniconda3/bin:${PATH}"
ARG PATH="/home/mom5/miniconda3/bin:${PATH}"

RUN apt-get update && apt-get install -y  git \
                        tcsh \
                        pkg-config \
                        gfortran \
                        netcdf-bin \
                        libnetcdf-dev \
                        libnetcdff-dev \
                        openmpi-bin \
                        libopenmpi-dev \
                        libnetcdff-dev \
                        vim \
                        wget

RUN useradd -ms /bin/bash mom5

[...]

Building the docker image

Execute the following line

docker build -t mom5:0.2 .

to build the docker image. This will take a while since everything will be downloaded and setup for you. In addition, the dockerfile will automatically compile our ocean model. The compilation time varies from system to system and will be performed automatically once you build the docker image.

The corresponding line in the dockerfile is:

RUN cd /home/mom5/MOM_code && ./build

Note that MOM consists of more than 100.000 lines of code that need to be compiled into an executable. If you are interested find here the model documentation. Once the compilation completes, an executable is placed in the folder /home/mom5/MOM_code/exec/gfortran/MOM_SIS called fms_MOM_SIS.x. This is the executable that runs the model.

Run the docker

Before executing the line below please have a look at it's content:

docker run -v $pwd/model_setup:/home/mom5/MOM_setup -v %cd%/MOM_forcing:/home/mom5/MOM_forcing -v %cd%/model_simulations:/home/mom5/model_simulations -p 8888:8888 -it mom5:0.2 bash

-v mounts the corresponding folder into the virtual machine. In contrast to copying the folder to your docker image, we avoid that the docker image gets to big.

Now execute the line.

You should now see something like

Note: if you are using cmd.exe on windows replace $pwd in that command above with %cd%

mom5@08a244e1e168:~$ 

You successfully started the docker image!

Start the ocean model

Copy the previously compiled executable to the MOM_setup folder

cp /home/mom5/MOM_code/exec/gfortran/MOM_SIS/fms_MOM_SIS.x /home/mom5/MOM_setup/binary/.

Inside /home/mom5/MOM_setup you will find the following structure

├── binary
│   └── fms_MOM_SIS.x
├── create_model_setup.py
├── firstlog
├── forcing_file.yaml
├── init
│   ├── ocean_ergom.res.nc
│   ├── ocean_temp_salt.res.nc
│   └── sst_ice_clim.nc
├── input
│   ├── data_table
│   ├── data_table~
│   ├── diag_table
│   ├── diag_table~
│   ├── field_table
│   ├── grid_spec.nc
│   ├── input.nml
│   ├── input.nml~
│   ├── postprocessing.sh
│   └── roughness_cdbot.nc
├── job_driver
├── job_reference_run50_init
├── job_submit_git
├── job_v02_r01
├── log
├── log2
├── logfile
├── logtest
├── __pycache__
│   ├── create_submit_python.cpython-37.pyc
│   └── create_submit_python.cpython-38.pyc
├── RUNYEAR01
├── test
└── tst

The file create_model_setup.py will handle everything for you.

Just type

 python create_model_setup.py -h

and follow the instructions. Note that -begin needs to be 1961 and -end 1962 for our example.

The folder input/ and init/ represent our cooking book for the model and the initial conditions, respectively. forcing_file.yaml links the downloaded forcing data into the defined setup. If used correctly you will end up with a folder /home/mom5/model_simulations/{your simulation name}.

In summary, you need to execute:

python create_model_setup.py -n {your simulation name} -nforcing forcing_file.yaml -inputfolder input -begin 1961 -end 1962 

Go to that directory and go to 1961/ and type ./fms_MOM_SIS.x to run the model.

This will take a while now.

After the end of the simulation you should see the files ice_day.nc and ocean_day3d.nc which we will analyze in the following.

After the lecture:

Hey everyone,

thank you for following along during our last lecture. I think we all got to the point we were able to start our docker image.

If you finished your model simulation already, you should check the model_simulations folder on your local machine (inside your mom5-docker repository). It should contain your model run.

If you want to start your docker image again, please use your terminal (for windows power shell is best) and direct yourself to the mom5-docker folder. Once you are in that repository execute

docker run -v $pwd/model_setup:/home/mom5/MOM_setup -v %cd%/MOM_forcing:/home/mom5/MOM_forcing -v %cd%/model_simulations:/home/mom5/model_simulations -p 8888:8888 -it mom5:0.2 bash

to start the docker.

To visualize plots (I forgot to install the necessary library) please first enter

conda install -y matplotlib

in your docker

If you want to analyze your data, you should start now your jupyter notebook. Please navigate to your simulation directory (in the docker) and the year 1961. You should now see something like ~/model_simulations/mariesostseelauf/1961

Now please enter:

jupyter lab --ip=0.0.0.0 .

This will start a jupyter server. You should see in your terminal something like:

http://127.0.0.1:8888/lab?token=207782a53ea615d3cef55720b20cfaa8911496e9f8ec323d

Open now the web browser of your choice and open that URL.

You should see now something like this

Click on the python3 notebook.

You should see an notebook environment now and a notebook called Untitled.ipynb in the left column where all files are listed.

The notebook is also stored on you local machine.

Additional information

Multi processing

If you want to use multiple cores use

mpirun -np <your number of cores> ./fms_MOM_SIS.x

Important: using multiple core requires to add a layout to &ocean_model_nml and &ice_model_nml in the file input.nml.

For example if you want to use 4 cores:

#cat input.nml

&ice_model_nml
[...]
layout = 2,2
\

&ocen_model_nml
[...]
layout = 2,2
\

docker-compose.yml

For largers applications the docker-compose file can give some structure on how to build the application. In this case it might be a little bit over the top.

services:
  MOM:
    build: .
    image: mom5:0.2

To install docker-compose run on Linux

sudo curl -L "https://github.com/docker/compose/releases/download/1.27.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

and check with

docker-compose --version

if the installation worked.

For more details see https://docs.docker.com/compose/install/