The GUD Model

This wiki outlines the procedures for running the GUD model on Caramel system. GUD model is based on the MITgcm model, and the general information about the MITgcm can be found in this WikiPage and the MITgcm User’s Manual. This page focus on how to run GUD simulation.

Currently, the GUD model can run under two grid configurations:

  1. ECCO v3: Global ocean, 1-degree horizontal resolution, 23 vertical layers, excluding the Arctic. The total number of grid points is 360x160x23.
  2. ECCO v4: Global ocean, 1-degree horizontal resolution, 50 vertical layers, including the Arctic. The total number of grid points is 90x1170x50.

This tutorial is currently based on the first configuration (ECCO v3).

Create working directory

Copy all the files in /data/Lab/GUD to your home directory, which contains a template for module simulation.

   cp -r /data/Lab/GUD/ ~/

Source code compiling

Then let’s go to the build/ directory and build your Makefile:

   cd ~/GUD/gud1/verification/gud_eccov3_6+4/build
   premake  

This command line option tells genmake to override model source code with any files in the directory ../code/. I have written an alias called ‘premake’ in ~/.bashrc file to replace this long genmake command. It’s actually running: ../../../tools/genmake2 -mods=../code -optfile=../../../tools/build_options/linux_ifort_impi

Once a Makefile has been generated, we create the dependencies with the command:

   make depend

This modifies the Makefile by attaching a (usually, long) list of files upon which other files depend. The purpose of this is to reduce re-compilation if and when you start to modify the code. The make depend command also creates links from the model source to this directory. It is important to note that the make depend stage will occasionally produce warnings or errors since the dependency parsing tool is unable to find all of the necessary header files (eg. netcdf.inc). In these circumstances, it is usually OK to ignore the warnings/errors and proceed to the next step.

Next, you compile the code using:

   make

You can speed up the compilation by adding “-j4” or “-j8” (e.g., “make -j8”) to split the compilation amongst 4 or 8 processors.

If the compiling goes well (i.e. no error message), we can move the generated mitgcmuv file to your run directory:

   cp mitgcmuv ../run/

Running model

The model run folder is located here:

   cd ~/GUD/gud1/verification/gud_eccov3_6+4/run

We will find a bunch of data* files, which control files input/output and model parameters for GUD model simulation. For example, data.ptracers contains the names, units, and definitions of the 47 tracers defined in the model. You can use a file editor like gedit to view and modify this file.

Now, we can submit a job to Caramel:

   bsub < run.gud.6+4

If your run finishes without any problems, the very last line of your STDOUT.0000 file should indicate the model ‘ENDED NORMALLY’.

Check running status

You can most simply enter either of the following for information on your runs:

   bjobs

Stop running

You can also kill your job if you find out that something is going wrong:

   bkill JOBID

JOBID is a number assigned to your job, and could be found by running bjobs.

Model debugging

1. If your run crashes, check the following files for error messages:

STDERR.0000

STDOUT.0000

omp.error.<job_id> (where <job_id> is the ID number assigned by the queue system)

2. You may also find it is helpful to check the *.f files in your build/ directory. This is what the code looks like at ‘run time’, so if pieces of code are being chopped off or #include statements are missing, this kind of thing will turn up in the *.f compiled files.

3. If you want to isolate if your problem is coming from partitioning, chemistry, deposition, etc, you can comment out individual processes in gchem_calc_tendency.F. Recompile with ‘make’ and run with a limited number of processes turned on.

Results analysis

The results of the model are stored in NetCDF format (*.nc) in a series of generated folders (e.g., ecco_gud_20180505_0017). These folders contain the following types of files:

  • 2d.*.t*.nc: 2D diagnostics
  • 3d.*.t*.nc: 3D diagnostics
  • grid.t*.nc: Model grid definition
  • ptr_tave.*.t*.nc: Average tracer concentrations, which are the most important model output
  • ptr_flux_tave.*.t*.nc: Tracer fluxes
  • tave.*.t*.nc: Average concentrations of other variables, such as temperature, salinity, ocean current velocities, etc.

Due to parallel computing, these files are distributed across multiple folders. To assemble them into a complete file (using ptr_tave as an example; other files follow the same procedure):

cd ~/GUD/gud1/verification/gud_eccov3_6+4/run 
gluemncbig -o ptr_tave.nc ecco_gud_*/ptr_tave*.nc

You can then use programs like ncview to analyze the results.

ncview ptr_tave.nc

In the pop-up interface, select a variable to quickly generate a plot. You can also use MATLAB for further analysis and statistical processing of these results.