The FMS MOM4 User Guide

The Modular Ocean Model (MOM) is a numerical representation of the ocean's hydrostatic primitive equations, and it is designed primarily as a tool for studying the global ocean climate system. MOM4 is the latest version of the GFDL ocean model whose origins date back to the pioneering work of Kirk Bryan and Mike Cox in the 1960s-1980s. It is developed and supported by researchers at NOAA's Geophysical Fluid Dynamics Laboratory (GFDL), with contributions also provided by researchers worldwide.

MOM4 was released to the public in January of 2004. As with previous MOM versions, the developers welcome feedback, both positive and negative, on the code's integrity and portability. It is through such feedback that the code evolves and becomes more robust and user friendly.

The purpose of this web page is to provide general information about MOM4 and particular information for how to download and run the code.

MOM4 users can acquire the source code and associated data sets from GForge, and are required to register at the GFDL GForge location. Therefore, users need to register only once to get both the source code and datasets of MOM4. More details can be found in the quickstart_guide.html.

Email concerning MOM4 are to be directed to the mom4-email list located at oar.gfdl.mom4p0noaa.gov. All questions, comments, and suggestions are to be referred to this list. An archive of all emails is maintained at email archive. A subject-organized archive of the emails is available at http://www.gfdl.noaa.gov/~gtn/mom4_email.html. Note that by registering at GForge to access the code, you are automatically subscribed to the email list.

MOM4 has undergone roughly 1.5 years of beta-testing. During this time, numerous researchers throughout the MOM community have provided essential input to the development of the code and its portability to various machines. As a result, a number of bugs were identified and resolved, further diagnostic and functional capabilities added, all resulting in increased code integrity.

Out of the MOM4-beta-testing period grew an understanding of methods useful in Fortran 90 to organize model data flow. Motivated by the goals of using MOM4 for applications such as coupled modeling and ocean data assimilation, the MOM4 developers decided to employ derived data types in MOM4. Derived types (1) allow inputs and outputs to routines to be clearly defined and protected with the Fortran 90 intent attribute, (2) render algorithmic changes requiring additional variables to be easily embedded within the type structures, and (3) reduce dependencies between modules thus leading to enhanced modularity. Overall, derived types lead to increased code clarity and a more robust and easier architecture for future development.

The beta-testing period also identified portability and efficiency issues that remain a top priority for GFDL software engineers. In particular, use of MOM4 on the SGI Origin machine used at GFDL saw a sizable reduction in efficiency relative to similar experiments with MOM3.1. Research identified the use of array syntax for dynamically allocated arrays to be at the root of the problem. Compiling the model with static allocation (array sizes specified at compile time) leads to a factor of two speed-up relative to the default dynamic allocation (array sizes allocated at run-time). We are unaware of whether similar behaviour exists on other computer platforms. Compiler engineers at SGI are presently addressing the issues, with the hoped-for result being the elimination of the compiler "feature" leading to the slow-down. Until then, MOM4 will maintain the ability to run with either static or dynamically allocated arrays. The distinction is facilitated by a cpp-preprocessor option, with dynamical allocation the default.

In addition to this user guide, documentation for MOM4 is provided by two LaTeX generated postscript documents:

Although MOM4 shares much in common with earlier versions of MOM, it possesses a number of computational, numerical, and physical characteristics that are noteworthy. The following provides an overview of the main characteristics of MOM4 (please refer to A Technical Guide to MOM4 for references).

MOM4 has been coded within GFDL's Flexible Modeling System (FMS). Doing so allows for MOM4 developers to use numerous FMS infrastructure and superstructure modules that are shared amongst various atmospheric, ocean, sea ice, land, vegetative, etc. models. Common standards and shared software tools facilitate the development of high-end earth system models, which necessarily involves a wide variety of researchers working on different computational platforms. Such standards also foster efficient input from computational scientists and engineers as they can more readily focus on common computational issues.

The following list represents a sample of the FMS shared modules used by MOM4.

The FMS infrastructure (the "Jakarta version") has been released to the public on GForge, with further releases every three-four months. Notably, the release of MOM4 represents the first major model code to be released using the FMS infrastructure.

The Flexible Modeling System ( FMS) is free software; you can redistribute it and/or modify it and are expected to follow the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

FMS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with MOM4; if not, write to:

MOM4 is distributed with a set of test cases located in mom4/exp/. These tests are taken from models used at GFDL for testing the numerical and computational integrity of the code.

	Warning
	These experiments are NOT sanctioned for their physical relevance. They are instead provided for the user to learn how to run MOM4, and to verify the numerical and/or computational integrity of the code. PLEASE do not assume that the experiments will run for more than the short time selected in the sample runscripts.

mom4_test1: flat bottom sector model with simple physics. This model is very small and can be easily run on a single workstation. It should provide the user with a basic experience of running mom4.

mom4_test2: flat bottom sector model which more fully tests some realistic physics options. This experiment has the same grid as test1, but it more thoroughly exercises the various physics packages.

mom4_test3A: east-west channel with open boundary at west. This experiment is an illustration of the open boundary condition capability of MOM4. Tracers include potential temperature and salinity.

mom4_test3B: solid wall of twice domain size as test3A for testing OBC. This experiment is used to verify the relevance of the test3A solution at early times. That is, for early times, the solution from test3A should agree with that from test3B. Tracers include potential temperature and salinity.

mom4_test4: global tripolar grid using roughly 3x3 resolution with 28 vertical levels and age, biotic, and cfc tracer packages. Coupled to GFDL sea ice model.

mom4_test5: global tripolar grid using roughly "1-degree" resolution ocean with 50 vertical levels coupled to the GFDL sea ice model and forced with the German OMIP dataset. Tracers include potential temperature, salinity, and age.

The FMS development team uses a local implementation of GForge to serve FMS software, located at http://fms.gfdl.noaa.gov. In order to obtain the source code and data sets, you must register as an FMS user on our software server. After submitting the registration form on the software server, you should receive an automatically generated confirmation email within a few minutes. Clicking on the link in the email confirms the creation of your account.

After your account has been created, you should log in and request access to the Flexible Modeling System project. Once the FMS project administrator grants you access, you will receive a second email notification. This email requires action on the part of the project administrator and thus may take longer to arrive. The email will contain a software access password along with instructions for obtaining the release package, which are described below.

To check out the release package containing source code, scripts, and documentation via CVS, type the following commands into a shell window. You might wish to first create a directory called fms in which to run these commands. You should enter the software access password when prompted by the cvs login command. At cvs login, the file ~/.cvspass is read. If this file does not already exist, an error message may display and the cvs login may fail. In this event, you should first create this file via touch ~/.cvspass.

      cvs -z3 -d:pserver:cvs@fms.gfdl.noaa.gov:/cvsroot/mom4 login
      cvs -z3 -d:pserver:cvs@fms.gfdl.noaa.gov:/cvsroot/mom4 co -r mom4p0b mom4
    

This will create a directory called mom4 in your current working directory containing the release package.

If you prefer not to use CVS, you may download the tar file from https://fms.gfdl.noaa.gov/projects/mom4/. Sample output is also available there for download. See Section 7.1, “Sample model output” for more information on the sample output.

All data sets that are needed to run MOM4 test cases are available for download from the same place in GForge where users get the source code. Therefore, users need to register only once to get both the source code and datasets of MOM4. More details can be found in the quickstart_guide.html.

The topography data set for test4 and test5 is a coarsened version of that kindly provided by Andrew Coward and David Webb at the Southampton Oceanography Centre. Their topography is a montage of that developed by Smith and Sandwell (1997) by satellite data in the region of 72°S to 72°N, the NOAA (1988) 5-minute global topography ETOPO5, and the International Bathymetric Chart of the Arctic Ocean (IBCAO). The chlorophyll-a density data set was compiled by Colm Sweeney, using data from James A. Yoder and Maureen A. Kennelly at the Graduate School of Oceanography, University of Rhode Island. This data set contains monthly chlorophyll concentrations from the SeaWiFS satellite for the period 1999-2001. Monthly wind stress is based on Hellerman and Rosenstein (1983). Temperature and salinity initial and boundary conditions are provided by the NOAA National Oceanographic Data Center (NODC) World Ocean Atlas (WOA).

The grid_spec.nc file is generated by executing the make_xgrids utility. make_xgrids generates the two exchange grids used by the FMS coupler, one for surface fluxes and the other for runoff, when the simulation requires an atmospheric grid different from the sample exchange grids provided by FMS. make_xgrids is created by compiling its C source, for example:

        cc -O -o make_xgrids make_xgrids.c -L/usr/local/lib -lnetcdf -lm
    

creates the make_xgrids executable from C-source and the netCDF and standard math libraries and is executed with the command:

       make_xgrids -o LON2.5LAT2LONLAT.nc -a N45.nc -l N45.nc
    

which makes a grid_spec.nc file (input files containing grid information for the ocean/sea-ice, atmosphere and land component models are indicated by the -o, -a and -l flags, respectively). make_xgrids expect a netCDF format input specification for the ice/ocean grid ( LON2.5LAT2LONLAT.nc in the above example). Three fields are required to be in this file:

make_xgrids also expects a netCDF format input specification for the atmosphere and land grid (N45.nc in the above example). x_vert_T and y_vert_t are required in the atmosphere/land grid file (N45.nc). make_xgrids copies all fields of the ice/ocean grid specification file to its output file, grid_spec.nc, and then appends fields that specify the atmosphere and land model grids and the surface and runoff exchange grids.

make_xgrids takes care that the land and ocean grids perfectly tile the sphere. The land model's domain is defined as the part of the sphere not covered by ocean (where wet = 0 on the ocean grid). To accomplish this, the land cells must be modified to remove the ocean parts. This is done in make_xgrids by first taking the intersections of atmosphere and land cells. The overlap area between these cells and active ocean cells are then subtracted. Finally, the modified atmosphere/land intersections are aggregated into land cell areas and atmosphere/land exchange cell areas.

Model cell intersections are calculated using the Sutherland-Hodgeman polygon clipping algorithm (Sutherland, I. E. and G. W. Hodgeman, 1974: Reentrant polygon clipping, CACM, 17(1), 32-42.). This algorithm finds the intersection of a convex and arbitrary polygon by successively removing the portion of the latter that is "outside" each boundary of the former. It can be found in many computer graphics text books (e.g., Foley, J. D., A. van Dam, S. K. Feiner, and J. F. Hughes, 1990: Computer graphics: principles and practice, second edition. Addison Wesley, 1174 pp.). The implementation in make_xgrids is particularly simple because the clipping polygon is always a rectangle in longitude/latitude space. For the purpose of finding the line intersections in the clipping operations, the cell boundaries are assumed to be straight lines in longitude/latitude space. This treatment is only perfectly accurate for cells bounded by lines of longitude and latitude.

Spherical areas are calculated by taking the integral of the negative sine of latitude around the boundary of a polygon (Jones, P. W., 1999: First- and second-order conservative remapping schemes for grids in spherical coordinates. Monthly Weather Review, 127, 2204-2210.). The integration pathways are again straight lines in longitude/latitude space. make_xgrids checks that the sphere and the individual cells of the atmosphere and ocean grids are tiled by the surface exchange cells. The fractional tiling errors are reported.

A runscript is provided in each test case directory (mom4/exp/$test_case ) for each test case. Details can be found in quickstart_guide.html.

Incorporated in the FMS infrastructure is MPP (Massively Parallel Processing), which provides a uniform message-passing API interface to the different message-passing libraries. If MPICH is installed, the user can compile the MOM4 source code with MPI. If the user does not have MPICH or the communications library, the MOM4 source code can be compiled without MPI by omitting the CPPFLAGS value -Duse_libMPI in the example runscript.

The diagnostics table allows users to specify the sampling rates and choose the output fields prior to executing the MOM4 source code. It is included in the input directory for each test case (mom4/exp/$test_case/input). A portion of a sample MOM4 diagnostic table is displayed below. Reference diag_table_tk.html for detailed information on the diagnostics table.

    "Diagnostics for MOM4 test case"
    1980 1 1 0 0 0
    #output files
    "ocean_month",1,"months",1,"hours","Time"
    "ocean_snap",1,"days",1,"hours","Time"
    #####diagnostic field entries####
    #===============================================================
    # ocean model grid quantities (static fields and so not time averaged))
    "ocean_model","geolon_t","geolon_t","ocean_month" "all",.false.,"none",2
    "ocean_model","geolat_t","geolat_t","ocean_month","all",.false.,"none",2
    #================================================================
    # prognostic fields 
    "ocean_model","temp","temp","ocean_month","all", "max", "none",2
    "ocean_model","age_global","age_global","ocean_month","all","min","none",2
    #================================================================
    # diagnosing tracer transport 
    "ocean_model","temp_xflux_sigma","temp_xflux_sigma","ocean_month","all",.true.,"none",2
    "ocean_model","temp_yflux_sigma","temp_yflux_sigma","ocean_month","all",.true.,"none",2
    #================================================================ 
    # surface forcing
    "ocean_model","sfc_hflux","sfc_hflux","ocean_month","all",.true.,"none",2
    "ocean_model","sfc_hflux_adj","sfc_hflux_adj","ocean_month","all",.true.,"none",2
    #================================================================
    # ice model fields 
    "ice_model", "FRAZIL",   "FRAZIL",     "ice_month", "all", .true., "none", 2,
    "ice_model", "HI",    "HI",   "ice_month", "all", .true., "none", 2
    #-----------------------------------------------------------------
  

The diagnostics manager module, diag_manager_mod, is a set of simple calls for parallel diagnostics on distributed systems. It provides a convenient set of interfaces for writing data to disk, namely in NetCDF format. The diagnostics manager is packaged with the MOM4 source code. The FMS diagnostic manager presently cannot handle scalar fields that are functions of time for technical reasons. This limitation of the FMS diagnostic tool will be remedied. Until then, scalars sent to the diagnostic manager are given a vertical dimension, with each value in the vertical the same. For more information on the diagnostics manager, reference diag_manager.html.

The MOM4 field table is used to specify tracers and their advection schemes, cross-land tracer mixing and checkerboard smoothing. The field table is included in the runscript as a namelist and is written to an output file upon execution of the runscript.

   

"diag_tracers","ocean_mod","frazil"
file_in  = INPUT/ocean_frazil.res.nc
file_out = RESTART/ocean_frazil.res.nc
/
   
   

"prog_tracers","ocean_mod","temp"
horizontal-advection-scheme = quicker
vertical-advection-scheme = quicker
file_in  = INPUT/ocean_temp_salt.res.nc
file_out = RESTART/ocean_temp_salt.res.nc
/
   

 
"prog_tracers","ocean_mod","salt"
horizontal-advection-scheme = mdfl_sweby
vertical-advection-scheme = mdfl_sweby
file_in  = INPUT/ocean_temp_salt.res.nc
file_out = RESTART/ocean_temp_salt.res.nc
/ 
   

"tracer_packages","ocean_mod","ocean_age_tracer"
names = global
horizontal-advection-scheme = mdfl_sweby
vertical-advection-scheme = mdfl_sweby
file_in  = INPUT/ocean_age.res.nc
file_out = RESTART/ocean_age.res.nc
min_tracer_limit=0.0
/
   

"namelists","ocean_mod","ocean_age_tracer/global"
slat = -90.0
nlat =  90.0
wlon =   0.0
elon = 360.0
/
  

In the first section of the field table, the user can specify tracers to be used in the simulation. Although there is no limit to the number of tracers specified, temperature (temp) and salinity (salt) must be included. The user may also define the horizontal and vertical tracer advection schemes. For more information on the field manager, reference field_manager.html.

In climate modeling, it is often necessary to allow water masses that are separated by land to exchange tracer and surface height properties. This situation arises in models when the grid mesh is too coarse to resolve narrow passageways that in reality provide crucial connections between water masses. The cross-land mixing establishes communication between bodies of water separated by land. The communication consists of mixing tracers and volume between non-adjacent water columns. Momentum is not mixed. The scheme conserves total tracer content, total volume, and maintains compatibility between the tracer and volume budgets.

Discretization of gravity waves on a B-grid can admit a stationary grid scale checkerboard pattern (e.g., Killworth et al., 1991). This pattern is associated with an unsuppressed grid splitting that can be initiated through grid scale forcing, such as topography, or indeed any forcing that projects onto the grid scale, such as fresh water forcing. The field table contains specifications for selectively enhancing the smoothing provided by the ocean_checkerboard.F90 module.

For a technical description of cross-land tracer mixing and checkerboard null mode, please reference A Technical Guide to MOM4.

Running the MOM4 source code in a parallel processing environment will produce one output NetCDF diagnostic file per processor. mppnccombine joins together an arbitrary number of data files containing chunks of a decomposed domain into a unified NetCDF file. If the user is running the source code on one processor, the domain is not decomposed and there is only one data file. mppnccombine will still copy the full contents of the data file, but this is inefficient and mppnccombine should not be used in this case. Executing mppnccombine is automated through the runscripts. The data files are NetCDF format for now, but IEEE binary may be supported in the future.

mppnccombine requires decomposed dimensions in each file to have a domain_decomposition attribute. This attribute contains four integer values: starting value of the entire non-decomposed dimension range (usually 1), ending value of the entire non-decomposed dimension range, starting value of the current chunk's dimension range and ending value of the current chunk's dimension range. mppnccombine also requires that each file have a NumFilesInSet global attribute which contains a single integer value representing the total number of chunks (i.e., files) to combine.

The syntax of mppnccombine is:

        mppnccombine [-v] [-a] [-r] output.nc [input ...] 
    

An output file must be specified and it is assumed to be the first filename argument. If the output file already exists, then it will not be modified unless the option is chosen to append to it. If no input files are specified, their names will be based on the name of the output file plus the extensions '.0000', '.0001', etc. If input files are specified, they are assumed to be absolute filenames. A value of 0 is returned if execution is completed successfully and a value of 1 indicates otherwise.

The source of mppnccombine is packaged with the MOM4 module in the postprocessing directory. mppnccombine.c should be compiled on the platform where the user intends to run the FMS MOM4 source code so the runscript can call it. A C compiler and NetCDF library are required for compiling mppnccombine.c:

       cc -O -o mppnccombine -I/usr/local/include -L/usr/local/lib mppnccombine.c -lnetcdf
    

Sample MOM4 model output data files are available to registered MOM4 users on GFDL's NOMADS server. The output data are organized into directories that bear the same names as the test cases . For example, output for test case test5 can be found in directory test5. Output files are classified into three subdirectories:

Note that these output files are compressed using tar. All .tar files should be decompressed for viewing. The decompress command is:

       tar -xvf filename.tar
    

There are several graphical packages available to display the model output. These packages vary widely depending on factors, such as the number of dimensions, the amount and complexity of options available and the output data format. The data will first have to be put into a common format that all the packages can read. FMS requires the data to be stored in NetCDF format since it is so widely supported for scientific visualization. The graphical package is also dependent upon the computing environment. For ocean modeling, ncview, Ferret and GrADS are most commonly used.

This is a list of files that are modified after the release of MOM4p0a code.