Testing the AWICM-PISM Coupling

Thank you for agreeing to help me test. Here are some instructions to help you get started. Please note that these instructions are also available as TESTING.md in esm-runscripts, on the awicm_pism_testing branch.

Access Prerequisites

We use a specialized version of awicm which includes changes to the echam6 atmosphere model to allow for dynamic changes to the orography and associated gravity wave drag parameterizations as well as some changes to the coupling routines to put ice sheet mass loss into the hydrology scheme. Direct interaction with the ocean via an iceberg module is reserved for a next step in the coupling development.

In order to get this particular version, you need access to the project modular-esm. Please talk to Dirk to get access here, I am not allowed to add you.

Since all the coupling occurs within the framework of the esm-tools, you need access to this project as well. Again, talk to either Dirk or Nadine.

Technical Skill Prerequisites

You should know how to use git. If you don't, I can recommend this video introduction (about 30 minutes). Alternatively, Dirk has made a nice workshop, which you can access through the esm-master tool (See next section)

Most of the code for the infrastructure scripts is written in ksh, some parts of the coupling routines are written in python, awicm is in fortran, and we make extensive use of both the cdo and nco toolkits. In particular the nco toolkit is documented in what might be seen as a user-unfriendly way, so if any of the nco commands you encounter look weird to you, come and ask what they are supposed to do.

Installing the required tools:

Please note that in the following instructions, I use the $ to signify your command prompt

Download the esm-master tool:

$ git clone https://${DKRZ_USERNAME}@gitlab.dkrz.de/esm-tools/esm-master.git
Cloning into 'esm-master'...
Password for 'https://a270077@gitlab.dkrz.de': 
remote: Enumerating objects: 442, done.
remote: Counting objects: 100% (442/442), done.
remote: Compressing objects: 100% (229/229), done.
remote: Total 442 (delta 238), reused 399 (delta 211)
Receiving objects: 100% (442/442), 80.17 KiB | 269.00 KiB/s, done.
Resolving deltas: 100% (238/238), done.

Now go into the directory, and execute the make command to configure the tools:

$ cd esm-master
$ make

You will be asked a series of questions, after which the tool will save your configuration.

Downloading the remaining esm-tools:

You can now get the rest of the esm-tools:

$ make get-esm-tools

You will need to type your password several times, and will then have a copy of esm-environment, esm-runscripts, esm-usermanual, and esm-workshop

Downloading awicm-test

You can get a modular version of awicm with the esm-master tool:

$ make get-awicm-test
$ make comp-awicm-test

Again, you will need to type your password a few times and wait for the compilation to finish. You now have a version of awicm that works just like the awicm-CMIP6 version, with the difference being that the model has been put together from individual repositories for echam-6.3.04p1, fesom-1.4, and oasis. Once Tido has confirmed that this produces bit-identical results to the standard awicm version, awicm-test should become the new default.

To help get the PalMod specific versions, I've made a palmod tag in each of the components. You can check these versions out with:

$ cd awicm-test
$ for model in echam-6.3.04p1  fesom-1.4  oasis; do
      cd $model
      git stash  # Sorry, don't know how to make this cleaner
      git checkout -b palmod-test${TEST_NUMBER} palmod
      git stash drop # Sorry, don't know how to make this cleaner
      git checkout master -- CMakeLists.txt # Sorry, don't know how to make this cleaner
      cd ..
  done
$ cd ..
$ make comp-awicm-test

Sorry about the mystical git stash stuff we need to do there, but I don't know how to fix that in a clean way right now.

Getting the right version of esm-runscripts

We are a little bit ahead of the release branch of esm-runscripts. To get the right version:

$ cd esm-runscripts
$ git checkout -b palmod_test${TEST_NUMBER} awicm_pism_testing

We also need to install some compiled programs:

$ cd functions
$ ./install_calendar.sh
$ ./install_calnoro.sh
$ ./install_jsbach_init_file.sh

Everything should work out-of-the box, and you are now ready to start testing.

If we need to change or fix something for your test, the first time you push, please use:

$ git push -u origin palmod_test${TEST_NUMBER} 

This will keep fixes for each test in separate branches, which will make it easier to sort out again in the end.

Reporting Problems

I've made a gitlab page for us to help keep track of problems and solutions. I've made one issue for each test we want to do, but if you run into more general problems, please use the issue tracker. These more general problems will probably effect everyone, not just your test.

If you need help using the issue tracker the first time, just let me know.