MITgcm tips

This page is intended to supplement the MITgcm documentation in a way that is more focused on how to use the model, rather than the the inner workings of the model. Recommended parameters and flags are listed, and the EXF and SEAICE packages are described.

The first section is relevant to the core model. It covers choosing an equation of state, using checkpoint files, and specifying the model grid. The following sections cover the EXF, SEAICE, and DIAGNOSTICS packages that supplement the core model.

Core model parameters and recommendations

Choosing an equation of state

The equation of state relates temperature, density, and salinity of water. The MITgcm has several choices available. The default choice is a linear equation of state. This is generally a poor choice when using SEAICE. Freshwater is most dense at 4 C, so if temperatures are near 4 C the linear equation of state will not represent the true densities. A much better choice is to use a nonlinear equation of state that includes the density maximum. In MITgcm, a good choice is the JMD95Z equation of state. More detail about this EOS is given in the EOS documentation page.

Setting the equation of state

The equation of state is specified by the namelist entry eosType in the PARM01 namelist of the data file. To choose the JMD95Z equation of state, you would include the following in your data file

   &PARM01
   ...
   eosType='JMD95Z',
   ....

Using checkpoint files

At some point you will be running the model, and it will fail. This can happen on Graham if the node fails, the power flicks or goes out, or any number of other reasons. This can cost you a lot of time when you're running big jobs. Therefore, it's best practice to use checkpoint files. MITgcm has built-in rolling and permanent checkpoint files. As the names suggest, rolling checkpoint files save the model current state with one of two file names (pickup.ckptA.data and pickup.ckptB.data), overwriting the oldest of the two to save each new checkpoint file. Permanent checkpoint files are saved with the model iteration number in their name and don't get overwritten. The frequencies are controlled separately by the keywords chkptFreq for rolling checkpoints and pchkptFreq for permanent checkpoint files. These keywords belong in the time namelist PARM03 (with other time-stepping parameters) in the data file.

Specifying a model grid

The size of the model grid needs to be specified at compile time and at run time. Each compiled executable must always be run with the same number of grid points and processors, but can be run for different resolutions on the same grid.

Compile-time options

The model grid is first specified in the SIZE.h file. The full domain (size Nx x Ny) is split into tiles in X and Y. Each tile is split into a number of grid points in X and Y (variables sNx and sNy). A group of tiles (size nSx x nSy) is sent to each processor, and the number of processors in the X and Y directions are specified by nPx and nPy. Therefore, we need Nx = sNx * nSx * nPx and Ny = sNy * nSy * nPy.

Each tile must overlap so each tile sharing the edge agrees on the field values on the edge. The overlap extent is specified by OLx and OLy. The required values depend on the advection scheme and packages used.

See the example SIZE.h file below. You can copy this file from MITgcm/model/inc/SIZE.h. You will need to comment out the first few lines, and change the values to match your configuration.

   CBOP
   C    !ROUTINE: SIZE.h
   C    !INTERFACE:
   C    include SIZE.h
   C    !DESCRIPTION: \bv
   C     *==========================================================*
   C     | SIZE.h Declare size of underlying computational grid.
   C     *==========================================================*
   C     | The design here supports a three-dimensional model grid
   C     | with indices I,J and K. The three-dimensional domain
   C     | is comprised of nPx*nSx blocks (or tiles) of size sNx
   C     | along the first (left-most index) axis, nPy*nSy blocks
   C     | of size sNy along the second axis and one block of size
   C     | Nr along the vertical (third) axis.
   C     | Blocks/tiles have overlap regions of size OLx and OLy
   C     | along the dimensions that are subdivided.
   C     *==========================================================*
   C     \ev
   C
   C     Voodoo numbers controlling data layout:
   C     sNx :: Number of X points in tile.
   C     sNy :: Number of Y points in tile.
   C     OLx :: Tile overlap extent in X.
   C     OLy :: Tile overlap extent in Y.
   C     nSx :: Number of tiles per process in X.
   C     nSy :: Number of tiles per process in Y.
   C     nPx :: Number of processes to use in X.
   C     nPy :: Number of processes to use in Y.
   C     Nx  :: Number of points in X for the full domain.
   C     Ny  :: Number of points in Y for the full domain.
   C     Nr  :: Number of points in vertical direction.
   CEOP
         INTEGER sNx
         INTEGER sNy
         INTEGER OLx
         INTEGER OLy
         INTEGER nSx
         INTEGER nSy
         INTEGER nPx
         INTEGER nPy
         INTEGER Nx
         INTEGER Ny
         INTEGER Nr
         PARAMETER (
        &           sNx =  30,
        &           sNy =  15,
        &           OLx =   2,
        &           OLy =   2,
        &           nSx =   2,
        &           nSy =   4,
        &           nPx =   1,
        &           nPy =   1,
        &           Nx  = sNx*nSx*nPx,
        &           Ny  = sNy*nSy*nPy,
        &           Nr  =   4)
   
   C     MAX_OLX :: Set to the maximum overlap region size of any array
   C     MAX_OLY    that will be exchanged. Controls the sizing of exch
   C                routine buffers.
         INTEGER MAX_OLX
         INTEGER MAX_OLY
         PARAMETER ( MAX_OLX = OLx,
        &            MAX_OLY = OLy )

Run-time options

The resolution is specified at run time in namelist PARM04 in the data file. The grids are specified as (int: number of points) * (float: distance between points) or by specifying a list of distances between neighbouring points. See example namelist below

   &PARM04
   usingCartesianGrid =.TRUE.,
   usingSphericalPolarGrid=.FALSE.,
   delX =400∗12.50,
   delY =400∗12.50,
   delR =50∗0.2 ,

Available Packages

The sections discusses the diagnostics, seaice, and exf packages. All packages required some compile-time and some run-time options. At minimum, packages must be enabled at compile time by adding the package name to the packages.conf file. At run time, the package must be enabled in data.pkg

   packages.conf:
   
   oceanic
   diagnostics
   exf
   cal
   seaice

   data.pkg:
   
   &PACKAGES
   useEXF        =.TRUE.,
   useCAL        =.TRUE.,
   useSEAICE.    =.TRUE.,
   useDIAGNOSTICS=.TRUE.,
   &

DIAGNOSTICS

The diagnostics package exists to make it easier to control the output files generated by the model. It makes it easy to choose which output fields are written and how frequently output files are generated.