Gravity wave tutorial

(WIP)

MIT GCM Tutorial -- Getting Started with the MITgcm

This is a short tutorial designed to walk someone through the main parts of the MITgcm and developing a sensible parameter set for your particular experiment. The MITgcm has a series of additional tutorials that may also be useful to you under the /verification/ folder. This tutorial is useful if you have never worked with the model before and want to very quickly get a sense of the main parts and offers a "hands on" alternative to sifting through the manual. The tutorial will also attempt to walk you through troubleshooting skills that will be useful as the manual becomes less so.

Troubleshooting Resources

The MITgcm Online Manual can be found here. A more useful, complete PDF file of the manual can be found [here|http://mitgcm.org/public/r2_manual/latest/online_documents/manual.pdf]. The MITgcm help support mailing list can be found here, and it is often useful to search the help inquiries (google with the addition site: mitgcm.org) if you are having a specific issue. Finally, the MITgcm is supported by a code browser that allows you to track certain variables within the entire code base. Keep in mind that this search model may contain out-of-date code, but it is a useful resource for sourcing where problems may be found. The best option is always to track it down in your local version of the MITgcm!

Acquiring the Code

The MITgcm page provides a relatively easy-to-follow set of instructions to picking up the code browser. Of course, best practice is to set up CVS so that the model can be updated if you're working on it long term, but you may find it easier to just use the .tar (non-Linux users, this is the equivalent of a .zip.

Getting Started with the Tutorial

The tutorial materials and some additional helpful scripts can be found at the git repository developed by Emily Tyhurst https://git.uwaterloo.ca/etyhurst/MITgcmUtils. (!!!) ADD INSTRUCTIONS ON HOW TO GIT THESE OVER**. For this tutorial you will need everything in the directory called tutorial wave, and a mpi file for whichever system you are running the MITgcm on. This tutorial does not cover how to write MPI files in order to find your local Fortran compiler, so hopefully you will be provided with one. There are a few mpi-files in the directory mpi_files but they may need revision if the systems have changed since this tutorial was written. The mpi file should be placed in the MITgcm directory tools/build_options

Case 1: Looking at the Example

For this tutorial you will be looking at a very simple 2D simulation. A density difference established via a temperature difference begins at a perfect vertical division at t=0s. The division becomes a simple gravity wave as the warmer water floats and the cooler water sinks below. Below is an image of the simulation in the IGW, next to an image of what your simulation will hopefully look like in MATLAB.

(!!!) add images here

A: Compile-Time Procedure

The first course of action is to compile the MITgcm into an executable file. Change directories into the 'build_folder' and run the following command:

 % ../../tools/genmake2 -mods=../code -of ../../tools/build_options/my_device_mpi

The first command tells the machine to use genmake2, an MITgcm script for creating all the appropriate make files. The -mods flag tells it where the compile-time options are located. You can cd into ../code if you want to take a look at these. We will address them later. The -of flag locates the mpi file for your particular machine, as mentioned in "getting started". Once genmake2 has concluded use the command:

 % make depend 

To compile all the Fortran dependencies. The directory should fill up with a large number of .F files. Then use the command:

 % make

To complete the creation of the executable. If you have errors they are most likely related to the mpi file at this stage. The error "Clock Skew detected" does not seem to affect the model in any major way. If it completes successfully, you should have an executable called mitgcmuv. Send a copy of this to the directory case_1_density (cp mitgcmuv ../case1_density if you're unfamiliar with Linux). This takes care of all the compile-time information. The main components set at compile time are the grid size (in computational grid cells, not m, see SIZE.h) and which packages are added (see packages.conf). It takes extra time to compile more packages, so don't compile them unless you need them!

B: Run-Time Procedure

Go to the data_files directory and take a look at the contents. One of the most important files there is data which sets the majority of the important parameters for the MITgcm.