3.2 Directory Structure

First, refer to Figure 3.1 for a schematic view of how the directory structure of MOM_3 is organized at GFDL. The structure is divided between two file systems: the CRAY file system contains the data part and the workstation file system contains all code and run_scripts. This structure is arbitrary but not without reason; especially the flat file structure used for the code which is described below. The recommendation is that this structure be retained as much as possible. Doing so will make things easy.

On the CRAY file system, there is an ARCHIVE/MOM_3/DATABASE directory. The DATABASE contains Hellerman and Rosenstein (1983) monthly climatological wind stress on a $2^\circ$ grid, Oort (1983) Monthly Surface air temperature on a $5^\circ$ grid, Levitus (1982) monthly temperature and salinity on a $1^\circ$ grid, and Scripps topography on a $1^\circ$ grid^3.1. There is also an ARCHIVE/MOM_3/EXP directory where interpolated data from the DATABASE and results^3.2 from various experiments are stored, each under their own sub-directory^3.3. The only sub-directory included is ..EXP/TEST_CASE which (after executing run scripts described below) will contain an interpolated version^3.4 of the DATABASE appropriate for the domain and resolution of the test case which is described below.

On the workstation file system, there is also a MOM_3 directory containing code,  run_scripts, and four sub-directories: MOM_3/PREP_DATA for preparing surface boundary conditions and initial conditions, MOM_3/SBC for handling various types of surface boundary conditions, MOM_3/NETCDF^3.5 containing routines to interface to the netcdf library, and MOM_3/EXP which in general contains a sub-directory for each experiment.

Note that as far as the actual fortran code, the file structure is basically flat with all code relating to the model proper being lumped into one place (in the MOM_3 directory). An alternative is to impose some structure by dividing the code up and placing related routines into sub-directories under MOM_3. For instance, vertical diffusion routines could be placed under sub-directory MOM_3/VERT_DIFFUSION, etc. With such a segmented file structure, finding and editing source code becomes a chore. However, with the aid of UNIX, any file structure can be easily sifted out of the flat file structure. For instance, suppose, it is necessary to look at all routines having anything to do with biharmonic mixing. The following UNIX call

 grep -l biharmonic *

will list the subset of filenames. The files are all in one place and immediately available for editing. For the future, this method can be made even more effective by embedding keywords in the comments of routines. For instance, placing a comment with the phrase "SGS parameterization" in each routine that is a sub-grid scale parameterization will allow all such routines to be easily listed.

Details of the sub-directories under MOM_3 are given below:

• PREP_DATA contains subroutines and CRAY T90 run_scripts for extracting data^3.6 from the DATABASE and interpolating it to arbitrary resolution for use as surface boundary conditions and initial conditions within MOM. Before this can be done, the domain and resolution must first be specified in module grids as discussed in Chapter 16. The run scripts are:

  1.

   run_sbc reads unformatted climatological monthly (also annual means) Hellerman stress (1983) and Oort (1983) surface air temperature and interpolates to the grid defined by module grids. Look for the USER INPUT section to choose the type of interpolation appropriate for the grid resolution. The run script uses file sbc.F which is included in the directory. If option netcdf is enabled in run_sbc then a NetCDF version of the interpolated dataset sbc.dta.nc will also be produced. Land values are not flagged. Refer to Section 3.10 for how to mask out land values in plots.

  2.

   run_ic reads unformatted monthly Levitus (1982) temperature^3.7 and salinity data and generates monthly (and annual mean) climatological initial conditions along with surface temperature and salinity for the grid defined by module grids. Look for the USER INPUT section to choose the type of interpolation appropriate for the grid resolution. This script uses file ic.F which is included in the directory. If option netcdf is enabled in run_ic then a NetCDF version of the interpolated dataset ic.dta.nc will also be produced. Land values are not flagged. Refer to Section 3.10 for how to mask out land values in plots.

  3.

   run_sponge reads output files produced by run_ic to construct sponge rows for damping model predicted temperature and salinity back to these data near northern and southern artificial walls. This is only appropriate for use in limited domain models and is the poor mans open boundary condition. This script uses file sponge.F which is included. The width of the sponge layers and the variation of Newtonian damping time scale within the sponge layer may be set within file sponge.F.

  4.

   run_read_levitus is a simple workstation script showing how to read the Levitus (1982) data (with Levitus land/sea masks) on a workstation. It assumes the Levitus (1982) data has been copied to the workstation's local disk. If option netcdf is enabled in run_read_levitus then a NetCDF dataset levitus.dta.nc will be produced. Land values are flagged.

  5.

   run_obc is a run script which uses file obc.F for constructing data needed for open boundary conditions. This was done by Arne Biastoch (abiastoch@ifm.uni-kiel.de) but has not been converted to the CRAY T90 at GFDL at this point.

  6.

   run_obcpsi is a run script which uses file obcpsi.F for constructing data needed for open boundary conditions. This was done by Arne Biastoch (abiastoch@ifm.uni-kiel.de) but has not been converted to the CRAY T90 at GFDL at this point.

• SBC contains three sub-directories for supplying various types of surface boundary conditions to MOM. Each is located in a separate sub-directory:

  1.

  TIME_MEAN contains subroutines which supply the time mean Hellerman and Rosenstein climatological winds (1983) along with the time mean Levitus (1982) SST and sea surface salinity climatologies which are used by the test case to compute effective heat and salt fluxes given a damping time scale and thickness which can be input from a MOM namelist. Refer to Section 14.4 for information on namelist variables. Note that the time scale can be different for restoring temperature and salinity. These time means are assumed to have been created using scripts from PREP_DATA so they are appropriately defined as functions of latitude and longitude on the domain and resolution specified by module grids. The option used to configure this type of surface boundary condition for MOM is time_mean_sbc_data which is described further in Chapter 19.

  2.

  MONTHLY contains subroutines which supply monthly mean Hellerman and Rosenstein climatological winds along with monthly mean Levitus (1982) climatological SST and sea surface salinity which are used by the test case to compute effective monthly mean heat and salt fluxes given a damping time scale which can be input from a MOM namelist. Refer to Section 14.4 for information on namelist variables. Note that the time scale can be different for restoring temperature and salinity. All are assumed to have been created by scripts from PREP_DATA so they are monthly averages appropriately defined as functions of latitude and longitude on the domain and resolution specified by module grids. Each dataset is defined by an averaging period and time stamp which marks the end of the averaging period. As the model integrates, the datasets are used to interpolate to the time corresponding to each model time step. It should be noted that there is enough generality to accommodate datasets with other periods (daily, hourly, etc) and treat them as climatologies (periodic) or real data (non periodic). Also datasets with differing periods may be mixed (example: climatological monthly SST may be used with hourly winds from other datasets). The option used to configure this type of surface boundary condition for MOM is time_varying_sbc_data which is described further in Chapter 19. There are four methods for interpolating these datasets to the time step level required by MOM as described in Section 19.2 .

  3.

  ATMOS contains subroutines that prototype what must be done to couple MOM to an atmosphere model for the general case of two way coupling when resolution and land/sea areas do not match. The atmosphere model is unrealistic. It is intended only to show that essentially two things must be done: a boundary condition grid must be defined to match the atmospheric grid (which is assumed to be different from the MOM grid resolution) and boundary conditions such as winds and heat flux must be accumulated in arrays as indicated. The option used to configure this type of surface boundary condition for MOM is coupled which is explained further in Section 19.1.

• NETCDF contains^3.8 fortran routines written by John Sheldon at GFDL for interfacing to lower level netcdf routines. These lower level routines are resolved by linking to the appropriate NetCDF libraries which will be site specific. The proper linking to these libraries at GFDL is given in script run_mom. For other sites, the appropriate links will have to be made by the researcher. The NetCDF section of any diagnostic can be used as a template to add NetCDF capability to new diagnostics.

• EXP contains one sub-directory for each experimental design but only EXP/TEST_CASE is indicated. If there were others, they would have the same structure. EXP may also contains printout files from the four test cases described later. They were produced on the CRAY T90 at GFDL and are named printout.0.gfld, printout.1.gfld, printout.2.gfld, and printout.3.gfld. These files can be used for comparison with results generated elsewhere and are described further in Section 3.4. Under the EXP/TEST_CASE are two sub-directories:

  1.

  MOM_UPDATES contains only code and run_scripts from the MOM_3 directory which need to be altered to define an experiment (e.g. the test case on another platform). Actually, no fortran code is included here because the basic MOM_3 files are already configured for the test case at GFDL. Typically though, the following would be a minimum set of useful ones: module grids and  run_grids which are used to design the grid, size.h which is used to implement the grid size, and module topog and  run_topog which are used to design the topography and geometry. Also, any other subroutine requiring changes must be placed in this directory because Cray script run_mom looks to this MOM_UPDATES directory for all updated code.

  2.

  PREP_UPDATES contains only code and CRAY T90 run_scripts from the PREP_DATA directory which would have be altered to define the test case. Actually, none are here since the ones in PREP_DATA are already setup to do the test case. Typically though, only run_scripts need be copied into this directory to alter pathnames (near the beginning of the scripts) which point to where interpolated initial conditions and surface boundary conditions are to be written. The scripts are then executed from this directory on the CRAY T90 to build the interpolated DATABASE appropriate for the resolution specified by module grids.