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.

The first release of MOM4 took place January of 2004. There have been four releases of this code: MOM4p0a (Jan 2004), MOM4p0b (March 2004), MOM4p0c (August 2004), and MOM4p0d (May 2005). The developers welcome feedback, both positive and negative, on the code's integrity and portability as well as documentation. It is through such feedback that the code and documentation evolves and becomes more robust and user friendly.

The purpose of this web guide 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 datasets 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 should 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 the mom4 email archive. Note that by registering at GForge to access the code, you are automatically subscribed to the email list.

There have been four releases of MOM4p0: (1) MOM4p0a was released January 2004, (2) MOM4p0b was released March 2004, and (3) MOM4p0c was released August 2004, and (4) MOM4p0d released May 2005. Each release is documented on this web page.

There are two major algorithm issues that are being addressed by GFDL developers. (1) Generalized quasi-Eulerian vertical coordinates are being implemented in MOM4. It is anticipated that MOM4p1a will have this capability, with a release date hopefully late 2005. (2) Two-way nesting is being considered for MOM. It is hoped that nesting will be available also late 2005 or early 2006.

There remains two general ways to compile mom4: with static allocation of arrays or dynamic allocation. Recent work on the SGI machines at GFDL has reduced the difference in efficiency between these two compilations. We understand that on some platforms, the dynamic allocation actually is better than static. Such remains an ongoing issue, as do other elements of code efficiency. Our general goal is to provide code that is efficient across a broad range of computer platforms, but not at the cost of sacrificing portability. Those who know they will be working with one particular platform for a period of time should readily find better ways of coding some parts of mom4 and the associated FMS code. If you feel your efficiency improvements are of a general nature and wish to have them distributed in future MOM4 releases, we would be happy for you to contribute the modified code.

Since its release in January 2004, there have been nearly 450 registrations with the mom4 distribution, with each registration generally representing more than one user. This is a sizable user community. For various purposes, it is useful to tabulate these users.

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

The documentation of most Fortran modules in FMS is inserted right in the source code to ensure consistency between the code and documentaion. A Perl software is used to extract documentation from the source code to create a corresponding .html module. For example, documentation for shared/diag_manager/diag_manager.F90 module is shared/diag_manager/diag_manager.html. In general, the embedded documentation is a good starting point to understand the Fortran module. Here is a complete tree that depicts all documentation of MOM4 code as well as shared code.

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).

Computational characteristics of MOM4 include the following.

Numerical and kinematic/dynamic characteristics of MOM4 include the following.

Physical parameterizations available in MOM4 include the following.

Miscellaneous features of the code released with MOM4 include the following.

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 "Lima version") has been released to the public on GForge, with further releases every few months.

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.

mom4_test1: This experiment consists of a flat bottom sector domain and uses very simple physics. This experiment 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: This experiment consists of a flat bottom sector domain and it uses more realistic physics options. This experiment has the same grid as test1, but it more thoroughly exercises the model's various physics packages. Since the domain is small, it should be accessible to those with single workstations, though it will be slower than mom4_test1 due to the use of more realistic physical parameterizations.

mom4_test3A: This experiment consists of an east-west channel using open boundary conditions at the western end of the channel. This experiment provides an illustration of the open boundary condition capability of MOM4. Tracers include potential temperature and salinity.

mom4_test3B: This experiment consists of an solid wall on all four sides and with a domain twice as long as the open boundary condition test3A. This experiment is used to verify the relevance of the open boundary solution from test3A solution at early times. That is, for early times, the solution from test3A should closely (though not bitwise) agree with that from test3B. Tracers include potential temperature and salinity.

mom4_test4: This model uses a global tripolar grid with roughly "3-degree" resolution and 28 vertical levels. The ocean is coupled to the GFDL sea ice model. Tracers include temperature and salinity, as well as the age, OCMIP biotic, and cfc tracer packages. This model is aimed to test the capabilities of the multipe tracers available with mom4. Note that the Sweby advection scheme is used here for all tracers, as is recommended by GFDL researchers.

mom4_test5: This model uses a global tripolar grid with roughly "1-degree" resolution and 50 vertical levels. The ocean is coupled to the GFDL sea ice model. The configuration is forced with the German OMIP dataset. Ocean tracers include potential temperature and salinity as well as the age tracer package. This is a large model, and it is similar (though not the same) to the ocean and ice configuration used for the GFDL IPCC simulations.

mom4_iom: This is Indian Ocean Community Model version 1.0 developed for Intensive Course on Ocean Modeling held at CMMACS, India, October 4-14, 2004.

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 in which to run these command. Then you enter the following Unix commands:

> setenv CVS_RSH ssh
> cvs -d:ext:USERNAME@fms.gfdl.noaa.gov:/cvsroot/mom4 co -r mom4p0d_patch20050717 mom4 
     

where you should replace USERNAME by your GForge username and the system prompts for your GForge password which you chose when you registered your account. This will create a directory called mom4 in your current working directory containing the release package.

If you have already checked out this CVS tag previously and some files have been modified since your last checkout you may wish to update your code as follows:

> cvs -d:ext:USERNAME@fms.gfdl.noaa.gov:/cvsroot/mom4 update -r mom4p0d mom4
    

If you prefer not to use CVS, you may download the tar file by first logging into your account then navigating through the tabs: My STUFF -> Projects tab -> the relevant project link -> FILES. Sample output is also available there for download. See Section 8.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 data sets 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).

All datasets of MOM4 are in NetCDF format since this format is widely used in the community. A number of useful tools are available here that allow the user to perform some necessary operations (editting attributes, merging, etc.) on a NetCDF file.

We start this section with some general comments regarding the setup of a model experiment.

--Setting up an experiment is critical part to the success of a research or development project with mom4. It is important that the user take some time to understand each of the many steps, and scrutinize the output from this code.

We have endeavoured over the years to provide tools facilitating the ready setup of a new experiment. However, we remain unable to provide code that does everything possible under the sun. Additionally, all features that are provided here may not be fully tested. For these reasons, the preprocessing code continues to evolve as use and functionality evolve. We sincerely appreciate ALL comments about code and documentation, especially comments regarding clarity, completeness, and correctness. Your input is essential for the improvement of the code and documentation.

--Many steps in idealized experiments that were formerly performed while running earlier MOM versions have been extracted from mom4 and placed into preprocessing. Hence, even if you are running an idealized experiment, it is likely that you will need to perform some if not all of the preprocessing steps discussed here.

--In addition to this section discussing how to set up an experiment, the online USER GUIDE has a Frequently Asked Questions (FAQ) section devoted to these issues. If you have a problem that is not addressed either here or the FAQ, then please feel free to query the mom4 email list. No question is too silly, so please ask!

--All code used to setup an experiment with mom4 is written in Fortran 90/95 except make_xgrids, which is written in C. Most code is dependent on FMS shared code for the purpose of parallization and interpolation. In addition to the documentation provided here and FAQs, there are comments within the code to help users debug and to make modifications to suit their purpose.

--Some users make nontrivial changes of general use. With your support, assistance, and maintenance, we will endeavour to include your changes in future releases.

Within GFDL FMS, ocean and ice are assumed to share the same grid. This means that the two models read in the same grid specification file. Even so, the domain decomposition on parallel systems may be different, and indeed they generally are due to different load balance issues between the two models.

Even though the ocean and ice models read the same grid specification file, they use the information from the grid file in a slightly different manner when setting up the respective model's tracer grid. In particular, the ocean model reads the tracer location directly from the arrays (x_T/geolon_t, y_T/geolat_t) written in the grid specification file. In contrast, the GFDL ice model reads (x_vert_T/geolon_vert_t, y_vert_T/geolat_vert_t) from the grid specifcation file and then averages these four vertex locatons to get the tracer location used in the ice model. The result is that diagnositics output from the two models have ocean and ice fields at slightly different locations for cases such as the tripolar grid when the grid is not spherical.

The ocean/ice grid specification file is generated by executing the ocean_grid_generator utility. The ocean_grid_generator utility generates the horizontal grid, vertical grid, and topography. A C-shell script is provided to compile relevant code to generate and run the executable to produce the grid file. To create the desired grid and topography, setting namelist options within the runscript is needed.

The horizontal grid can be conventional lon-lat spherical grid or a reprojected rotated tripolar grid (R. Murray, "Explicit generation of orthogonal grids for ocean models", 1996, J.Comp.Phys., v. 126, p. 251-273.). The choice is controlled by the namelist option "tripolar grid" (true for tripolar grid and false for lon-lat spherical grid). Note that cartesian beta-plane and f-plane geometries are set up within mom4, not within the grid generation preprocesing steps discussed here (see mom4/ocean_core/ocean_grids.F90 for beta-plane and f-plane namelist options).

The grid_spec file contains the following horizontal grid information: geographic location of T,E,C and N-cell (Tracer, East, Corner, and North cells), half and full cell lengths (in meters), rotation information between logical (i.e., grid oriented) and geographic east of cell. The complete description of the horizontal grid and namelist option is available in hgrid

The vertical grid information includes depth of tracer points and tracer_boundaries. The complete description of namelist option is available in vgrid

The topography can be idealized (various examples are provided and others can be easily added through emulating those provided) or remapped from a source topography dataset. The type of topography is specified by the namelist variable "topography". Namelist "topog_depend_on_vgrid" specifies if the topography will depend on the vertical grid or not. To generate a grid for mom4, "topog_depend_on_vgrid" should always be true. A useful option for those upgrading older models to mom4 is "adjust_topo". If this option is set to false, there will be no adjustments made to the topography. See topog for further details about topography namelist options.

"Exchange grid" information is required for coupled models (i.e., ocean/ice coupled to land and/or atmosphere) that employ the GFDL coupler technology. The exchange grid is defined by taking the union of the ocean/ice grid with the atmosphere and land grids. This union is then used to compute area integrals to allow for conservative mapping of fluxes between the component models.

The exchange grid information is generated by executing the make_xgrids utility. The execution of the make_xgrids utility will generate a netcdf file with the name grid_spec.nc. The grid_spec.nc contains the component model grids as well as the exchange grid information. In particular, the utility make_xgrids generates two exchange grids used by the FMS coupler: one grid for surface fluxes and another for runoff. make_xgrids is created by compiling its C source:

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

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

make_xgrids -o ocean_grid.nc -a atmos_grid.nc -l land_grid.nc

This execution produces 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). The grid files ocean_grid.nc, atmosphere_grid.nc, and land_grid.nc all can be generated separately through the ocean_grid_generator utility. Normally at GFDL we select the same atmosphere and land model grid, but such is not necessary. When the land and atmosphere grids are the same, then we can reduce the execute command to

make_xgrids -o ocean_grid.nc -a atmos_grid.nc

If you further decide to choose same ocean, atmosphere and land grid, the execute command will be

make_xgrids -o ocean_grid.nc -a ocean_grid.nc

make_xgrids expects a netCDF format input specification for each of the component model grid files. For the ice/ocean grid (ocean_grid.nc), the following three fields are required:

1. wet - a 2D array of double precision numbers set to 1.0 where the ice and ocean models are active and 0.0 elsewhere. wet has im indices in the i-direction (pseudo east-west) and jm indices in the j-direction (pseudo north-south). These correspond to the size of the global arrays of temperature, salinity and ice thickness in the coupled climate model.

2. x_vert_T and y_vert_T - 3D double precision arrays (dimensioned im * jm * 4) that contain the longitudes and latitudes (respectively) of the four corners of T- cells. The numbers are in degrees.

For the netCDF format input specification for the atmosphere and land grid (atmos_grid.nc and/or land_grid.nc), x_vert_T and y_vert_t are required.

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 then the surface and runoff exchange grids.

Using the Sutherland-Hodgeman polygon clipping algorithm (reference in next paragraph) for model cell interaction calculation, make_xgrids takes care that the land and ocean grids perfectly tile the sphere. The land model's domain is defined as that 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.

After generating the model grid, it is time to generate the initial and boundary conditions (ICs and BCs). These conditions are specific to the details of the model grid, so it is necessary to have the grid specificiation file in hand before moving to the IC and BC generation.

There are two options for ICs and BCs.

--Idealized Conditions. These conditions are based on subroutines that design idealized setups for either initial conditions (e.g., exponential temperature profile) or boundary conditions (e.g., cosine zonal wind stress). Code for these purposes is found in the idealized_ic and idealized_bc directories in the mom4 distribution. Details of available namelist choices are in the documentation file idealized_ic.html as well as the comments within the source code itself. Users can readily incorporate their favorite idealized IC or BC into the mom4 idealized preprocessing step by emulating the code provided.

--Realistic Conditions. These ICs and BCs generally result from a regridding routine to bring, say, the Levitus analysis onto the model grid for initializing a model, or for mapping surface fluxes onto the grid for boundary conditions. Code enabling the regridding functions is found in the preprocessing/regrid_2d, preprocessing/regrid_3d and preprocessing/regrid directories in the mom4 distribution.

In the remainder of this section, we detail code to generate the ICs and BCs of use for mom4.

Scalability of a complex model like MOM4 is the correlation between the number of processing elements (PE) and the run time. One would expect that run time decreases as the number of PEs increases. It is important, however, to note that there are a number of important factors that can affect scalability considerably:

For many analysis applications, it is sufficient, and often preferable, to have output on the model's native grid (i.e., the grid used to run the simulation). Accurate computation of budgets, for example, must be done on the model's native grid, preferably online during integration. MOM4 provides numerous online diagnostics for this purpose.

Many applications, such as model comparison projects, require results on a common latitude-longitude spherical grid. Such facilitates the development of difference maps. For this purpose, we have developed a tool to regrid scalar and vector fields from a tripolar grid to a spherical grid. In principle, this tool can be used to regrid any logically rectangular gridded field onto a spherical grid. However, applications at GFDL have been limited to the tripolar to spherical regrid case.

In general, regridding is a difficult task to perform accurately and without producing noise or spurious results. The user should carefully examine regridding results for their physical integrity. Problems occur, in particular, with fields near mom4's partial bottom step topography in the presence of realistic topography and land/sea geometry. Indeed, we were unable to find a simple algorithm to handle regridding in the vertical that did not produce egregious levels of noise. Hence, the regridding tool provided with mom4 only handles horizontal regridding. The regridded data will thus be on the source vertical grid.

Model comparisons should ideally be performed only after regridding output using the same regridding algorithm. Unfortunately, such is not generally the case since there is no standard regridding algorithm used in the modeling community.

Please note that the regridding code is relatively new at GFDL. We greatly appreciate user's feedback.

The regridding algorithm provided with the mom4 distribution is located in the directory postprocessing/regrid

The algorithm accepts data from any logically rectangular grid (e.g., tripolar or latitude-longitude) and regrids to a spherical latitude-longitude grid. When the data is on the tracer cell (T-cell), the regridding interpolation is conservative. Thus, total heat, salt, and passive tracer remain the same on the two grids. However, when data is located at another position:

then regridding is accomplished non-conservatively using a nearest neighbor distance weighting algorithm. It is for this reason that computationally accurate results are only available when working on the model's native grids.

The regridding tool reads grids information from a netcdf file, specified by the namelist "grid_spec_file". "grid_spec_file" contains source grid, destination grid and exchange grid information.

To create the exchange grid, execute the command

make_xgrids -o src_grid.nc -a dst_grid.nc

The exchange grid creates a file grid_spec.nc. It has new fields with names:

AREA_ATMxOCN, DI_ATMxOCN, DJ_ATMxOCN, I_ATM_ATMxOCN, J_ATM_ATMxOCN, I_OCN_ATMxOCN, J_OCN_ATMxOCN, AREA_ATMxLND, DI_ATMxLND, DJ_ATMxLND, I_ATM_ATMxLND, J_ATM_ATMxLND, I_LND_ATMxLND, J_LND_ATMxLND, AREA_LNDxOCN, DI_LNDxOCN, DJ_LNDxOCN, I_LND_LNDxOCN, J_LND_LNDxOCN, I_OCN_LNDxOCN, J_OCN_LNDxOCN, xba, yba, xta, yta, AREA_ATM, xbl, ybl, xtl, ytl, AREA_LND, AREA_LND_CELL, xto, yto, AREA_OCN

It is critical that src_grid.nc DO NOT already have any of the above new exchange grid fields. If they do, then these fields should be removed using netcdf tools such as ncks.

After the grid_spec.nc file is generated, it is passed into the regrid program through the nml option "grid_spec_file".

The regrid program reads model data from a netcdf file, which is specfied by the namelist variable "src_data". Again, src_data fields are gridded according to src_grid.nc. The number of fields to be regridded is specified by num_flds. The name of the fields (e.g., temp, salt) to be regridded is specified by the namelist variable "fld_name". Each field can be a scalar or vector. If a vector, then specify by vector_fld. Vector fields should always be paired together (e.g., u,v components to the horizontal current). The output file is a netcdf file specified by the namelist variable "dst_data".

The complete namelist option description is available in regrid.html or the code itself.

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_manager.html for detailed information on the use of diag_manager.

    "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 in NetCDF format. The diagnostics manager is packaged with the MOM4 source code. The FMS diagnostic manager can handle scalar fields as well as arrays. 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, cross-land insertion, and other options. 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
/





"xland_mix","ocean_mod","xland_mix"
"xland","Gibraltar","ixland_1=274,ixland_2=276,jxland_1=146,jxland_2=146,kxland_1=1,kxland_2=28,vxland=0.55e6"
"xland","Gibraltar","ixland_1=274,ixland_2=276,jxland_1=147,jxland_2=147,kxland_1=1,kxland_2=28,vxland=0.55e6"
"xland","Black-Med","ixland_1=305,ixland_2=309,jxland_1=151,jxland_2=152,kxland_1=1,kxland_2=6,vxland=0.01e6"
"xland","Black-Med","ixland_1=306,ixland_2=309,jxland_1=151,jxland_2=153,kxland_1=1,kxland_2=6,vxland=0.01e6"/

"xland_insert","ocean_mod","xland_insert"
"xland","Gibraltar","ixland_1=274,ixland_2=276,jxland_1=146,jxland_2=146,kxland_1=1,kxland_2=18,tauxland=86400.0"
"xland","Gibraltar","ixland_1=274,ixland_2=276,jxland_1=147,jxland_2=147,kxland_1=1,kxland_2=18,tauxland=86400.0"
"xland","Black-Med","ixland_1=305,ixland_2=309,jxland_1=151,jxland_2=152,kxland_1=1,kxland_2=6,tauxland=86400.0"
"xland","Black-Med","ixland_1=306,ixland_2=309,jxland_1=151,jxland_2=153,kxland_1=1,kxland_2=6,tauxland=86400.0"/



"diff_cbt_enhance","ocean_mod","diff_cbt_enhance"
"diffcbt","Gibraltar","itable=274,jtable=146,ktable_1=1,ktable_2=18,diff_cbt_table=0.01"
"diffcbt","Gibraltar","itable=276,jtable=146,ktable_1=1,ktable_2=18,diff_cbt_table=0.01"
"diffcbt","Gibraltar","itable=274,jtable=147,ktable_1=1,ktable_2=18,diff_cbt_table=0.01"
"diffcbt","Gibraltar","itable=276,jtable=147,ktable_1=1,ktable_2=18,diff_cbt_table=0.01"
"diffcbt","Black-Med","itable=305,jtable=151,ktable_1=1,ktable_2=6,diff_cbt_table=0.01"
"diffcbt","Black-Med","itable=309,jtable=152,ktable_1=1,ktable_2=6,diff_cbt_table=0.01"
"diffcbt","Black-Med","itable=306,jtable=151,ktable_1=1,ktable_2=6,diff_cbt_table=0.01"
"diffcbt","Black-Med","itable=309,jtable=153,ktable_1=1,ktable_2=6,diff_cbt_table=0.01"/



   

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 and cross-land insertion 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. The grid points where this exchange takes place, and the rates of the exchange, are specified in the field table.

For some cases, it is necessary to set a large vertical tracer diffusivity at a specified point in the model, say next to a river mouth to ensure fresh water is mixed vertically. These diffusivities are specified in the field table.

For a technical description of cross-land tracer mixing and insertion, 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.

The following lists some new features of the MOM4p1a release in August 2006.

The following lists some new features of the MOM4p0d_patch20050717 release in July 2005.