Skip to content

5. Using the docker image

Jump to bottom
GilesFearon edited this page Oct 30, 2024 · 14 revisions

As described here, we have a docker image which has been designed to run the command line interface file somisana-opendrift/cli.py. This gives us a clean approach to run any function in our repo, without the need to setup a local python environment. This is particularly useful as part of our operational workflow, and the hope is that it will assist in running the model operationally on other servers. For example, one could imagine a GUI which creates the config.py file based on user inputs, and then the model can be run via the docker image. This can be on any server, so long as the forcing files are available.

In this tutorial, we'll show how all of the functions we ran from a python environment in the previous tutorials here and here can be run from the docker image directly. If you are following on from those tutorials, you may want to create a new directory to test the docker image, and copy over the working config.py file:

cd /home/$USER/OpenDrift_tutorial
mkdir 07_docker
cd 07_docker
cp ../06_croco_mercator_gfs/config.py .

5.1 Running the model

Before running the docker image, let's first run the cli.py function from with the opendrift environment activated. This essentially mimics what will get run inside the docker container when we run the image (if you're new to the jargon, a docker container is a running instance of a docker image). You can copy this code to a new file called run_od_cli.bash file and execute it (or just run directly on the command line):

#!/bin/bash
python <path-to-somisana-opendrift>/cli.py \
      run_model \
        --model_type oceandrift \
        --config_dir $PWD

If you dig into the run_model function of the cli.py, you'll see it just executes the relevant function in opendrift-tools/run.py.

Now let's do the same thing, but using the docker image. Copy this into a new file called run_od_docker.bash (or just run directly on the command line):

#!/bin/bash
docker run --rm \
  -v /home/$USER/OpenDrift_tutorial:/mnt/tutorial_dir \
  ghcr.io/saeon/somisana-opendrift_main:latest \
    run_model \
      --model_type oceandrift \
      --config_dir /mnt/tutorial_dir/07_docker

When running the docker image, you need to ensure that the paths to the forcing files inside the config.py file point to the file locations inside the docker container running the image (not the locations on your local system). So you have to mount the relevant local dir(s) to the container running the image, using the -v input. In the example above, we mounted home/$USER/OpenDrift_tutorial to /mnt/tutorial_dir, so all your local files in home/$USER/OpenDrift_tutorial are seen in the container at /mnt/tutorial_dir. I've specifically mounted this directory, as a single mount then gives us access to both the forcing files and the configuration directory (we could have also done two mounts, one to the forcing directory and one to the configuration directory).

Given this mount, the forcing files will be located at /mnt/tutorial_dir/forcing inside the running container. So we need to edit the config.py file to reflect this. Once edited, execute the run_od_docker.bash file. It should produce a trajectories.nc output file as before.

5.2 Animate/plot the particle output

As per the tutorial on processing the output, you can use the docker image to animate the particle output:

docker run --rm \
  -v /home/$USER/OpenDrift_tutorial/07_docker:/mnt/config_dir \
  ghcr.io/saeon/somisana-opendrift_main:latest \
    animate \
      --type particles \
      --config_dir /mnt/config_dir \
      --extents 17,19,-35,-32 \
      --gif_out trajectories.gif

5.3 Grid the output

We can also grid the output as before:

docker run --rm \
  -v /home/$USER/OpenDrift_tutorial/07_docker:/mnt/config_dir \
  ghcr.io/saeon/somisana-opendrift_main:latest \
    grid_particles \
      --config_dir /mnt/config_dir \
      --fname trajectories.nc \
      --fname_gridded gridded_particle_density.nc \
      --grid_type density

If you are running an oil spill simulation, you can change the --grid_type to surface_oil and stranded_oil with a new fname_gridded, respectively.

5.4 Animate/plot the gridded output

And animate the gridded output:

docker run --rm \
  -v /home/$USER/OpenDrift_tutorial/07_docker:/mnt/config_dir \
  ghcr.io/saeon/somisana-opendrift_main:latest \
    animate  \
      --type gridded  \
      --config_dir /mnt/config_dir \
      --fname_gridded gridded_particle_density.nc \
      --extents 17,19,-35,-32 \
      --gif_out gridded_particle_density.gif

If you're running an oil spill simulation, you may want to animate the surface oil thickness:

docker run --rm \
  -v /home/$USER/OpenDrift_tutorial/07_docker:/mnt/config_dir \
  ghcr.io/saeon/somisana-opendrift_main:latest \
    animate  \
      --type gridded  \
      --config_dir /mnt/config_dir \
      --fname_gridded gridded_surface_oil.nc \ # or whatever you called it
      --extents 17,19,-35,-32 \
      --var_str surface_thickness \
      --ticks 0,0.01,0.1,1,10 \
      --cbar_label 'surface oil thickness ($\mu$m)' \
      --cmap Greys \
      --gif_out gridded_surface_oil.gif

If you wanted to plot the minimum time to arrival:

docker run --rm \
  -v /home/$USER/OpenDrift_tutorial/07_docker:/mnt/config_dir \
  ghcr.io/saeon/somisana-opendrift_main:latest \
    animate  \
      --type gridded_stats  \
      --config_dir /mnt/config_dir \
      --fname_gridded gridded_particle_density.nc \
      --extents 17,19,-35,-32 \
      --var_str minimum_time \
      --ticks 0,0.5,1.5,2,2.5,3,3.5,4,4.5,5 \
      --cbar_label 'minimum time (days)' \
      --cmap Spectral_r \
      --jpg_out gridded_surface_oil_min_time.jpg

Or maybe the maximum surface oil thickness:

docker run --rm \
  -v /home/$USER/OpenDrift_tutorial/07_docker:/mnt/config_dir \
  ghcr.io/saeon/somisana-opendrift_main:latest \
    animate  \
      --type gridded_stats  \
      --config_dir /mnt/config_dir \
      --fname_gridded gridded_surface_oil.nc \
      --extents 17,19,-35,-32 \
      --var_str maximum \
      --ticks 0,0.01,0.1,1,10 \
      --cbar_label 'max. surface oil thickness ($\mu$m)' \
      --cmap Greys \
      --jpg_out gridded_surface_oil_max.jpg

5.5 Oil mass balance

For oil spill simulations it is instructive to see how the oil mass balance evolves over time. We have a function oil_massbal() in somisana-opendrift/opendrift_tools/postprocess.py. You can call this from your own python code, or you could run the function via the docker image:

docker run --rm \
  -v /home/$USER/OpenDrift_tutorial/07_docker:/mnt/config_dir \
  ghcr.io/saeon/somisana-opendrift_main:latest \
    oil_massbal  \
      --config_dir /mnt/config_dir

And to plot this file you could run the plot_budget() function in somisana-opendrift/opendrift_tools/plotting.py, or run the docker image:

docker run --rm \
  -v /home/$USER/OpenDrift_tutorial/07_docker:/mnt/config_dir \
  ghcr.io/saeon/somisana-opendrift_main:latest \
    plot_budget  \
      --config_dir /mnt/config_dir
Clone this wiki locally