A Guide to Grid Coupling in FMS
by Michael Winton, October 2001
FMS provides the capability to couple component models (atmosphere, land, sea ice, and ocean) on different logically rectangular grids. Presently, the atmosphere and land models are constrained to be on standard longitude/latitude grids (not necessarily the same) and the ocean and sea-ice are constrained to be on the same grid which need only be logically rectangular. A logically rectangular grid has an array-like set of areas, each of which border one other area in each of the pseudo-north, -south, -east, and -west directions, except at the poles. The coupling between the models is designed to conserve fluxes. A grid specification file is used to initialize the model grids and perform exchanges between the models. The next section describes how this file is generated. The following three sections describe how the grid specification file is used at run time by the coupled model, how the exchange information contained in the file is generated and how the ocean/sea-ice grid file is generated.
At runtime, the coupled model sets up its grids using the grid_spec.nc file that it finds in the INPUT subdirectory. This is a NetCDF file that contains grid information for all of the component models as well as exchange grid information for the coupler to use. The file is generated by a two step process:
- a NetCDF file containing the ocean/sea-ice grid is generated by a utility called grid_generator
- the output file from grid_generator is used as input by a utility called make_xgrids along with longitude and latitude boundaries of the atmosphere and land models to generate the grid_spec.nc file.
Grid_generator is part of MOM4. Currently, it generates longitude/latitude and “tripolar” grids (see OCEAN/SEA-ICE GRID GENERATION below) from namelist input.
Some examples can be found in /archive/mw/grids. The following ocean grids and the script that generated all but the last of them (make_ocean_grids.csh) can be found in /archive/mw/grids/ocean:
LON2.5LAT2LONLAT.nc - 2.5 degree longitude by 2 degree latitude grid
LON2.5LAT2TRIPOLAR.nc - same but tripolar north of 65N
LON1.25LAT1LONLAT.nc - 1.25 degree longtidue by 1 degree latitude grid
LON1.25LAT1TRIPOLAR.nc - same but tripolar north of 65N
LON1.25OM1.nc - a 1.25 degree longitude "OM1" grid
LON1LAT1POLE2EQ.nc - 1 degree lon/lat with poles rotated to equator
(see figure above)
/archive/mw/grids/lonlat contains text files listing longitude and latitude boundaries for the N45 and T42 atmospheric model grids, one number per line.
N45_x.dat T42_x.dat
N45_y.dat T42_y.dat
These are used in conjunction with the above ocean grids to generate the coupled model grid specification files found in /archive/mw/grids/mv_these_to_grid_spec.nc:
N45_LON2.5LAT2LONLAT.nc T42_LON2.5LAT2LONLAT.nc
N45_LON2.5LAT2TRIPOLAR.nc T42_LON2.5LAT2TRIPOLAR.nc
N45_LON1.25LAT1LONLAT.nc T42_LON1.25LAT1LONLAT.nc
N45_LON1.25LAT1TRIPOLAR.nc T42_LON1.25LAT1TRIPOLAR.nc
N45_LON1.25OM1.nc T42_LON1.25OM1.nc
N45_LON1LAT1POLE2EQ.nc T42_LON1LAT1POLE2EQ.nc
The script make_grid_specs.csh in the same directory was used to generate these files. You can move one of these files to INPUT/grid_spec.nc in the execution directory of the your coupled model.
If the runtime atmospheric model grid does not match that found in the INPUT/grid_spec.nc file, the coupled model will give an error and stop. The coupled model always writes out the longitude and latitude boundaries of its atmosphere model in files xba.dat and yba.dat respectively. These can be used as input to make_xgrids to generate a grid_spec.nc file compatible with the coupled model you are running. For example:
/home/mw/bin/make_xgrids.hpcs -a xba.dat,yba.dat -l xba.dat,yba.dat -o LON1.25OM1.nc
makes a grid_spec.nc for coupling the OM1 ocean model with the atmospheric model you are running and a land model on the same grid.
At runtime, the ocean, sea ice, and land models read their grids from the grid_spec.nc file. The land model areas must be read from grid_spec.nc rather than calculated because the grid_spec.nc land areas have been modified in the grid generation process to remove overlaps with the ocean/sea-ice grid cells. The land mask is set to true where this modified area is positive. The land model areas are used for conserving runoff on the land grid. The ocean and sea-ice grids are the same by virtue of initializing from the same fields of grid_spec.nc. Additionally, the sea ice model uses this grid information to rotate vectors between the longitude/latitude atmosphere grid and the general ocean/sea-ice grids.
The coupler uses grid_spec.nc to initialize its exchange grids. An exchange grid between two component model grids is the grid formed with the union of the bounding lines of the component model grids. The exchange grid is, therefore, the coarsest grid that is a refinement of each of the component model grids. The coupler uses exchange grids for two purposes:
- conservative interpolation of fields between models uses the exchange grid cell areas as weights and
- the surface flux calculation takes place on the exchange grid thereby using the finest scale data available.
The coupler has two exchange grids. The first is for surface fluxes with the atmosphere on one side and the land and sea ice on the other. Under FMS the sea ice model serves as the interface to the ocean model — the atmosphere model never exchanges directly with the ocean model. The second exchange grid is between the land and the sea ice for runoff. No fluxes are computed on this exchange grid; it is used solely for conservation.
The coupler’s utility for interfacing to the grid_spec.nc file and performing exchange grid operations is xgrid_mod. Xgrid_mod uses the mpp_domains domain of each of the models along with information it reads from the grid specification file to determine grid and processor connectivities. The coupler’s fortran call to initialize the surface exchange grid (xmap_sfc) is:
call setup_xmap(xmap_sfc, (/ 'ATM', 'OCN', 'LND' /), &
(/ Atm%Domain, Ice%Domain, Land%Domain /), &
"INPUT/grid_spec.nc" )
Xgrid_mod reads the exchange grids from grid_spec.nc as a sequence of quintuples: the i/j indices of the intersecting cells of the two participating grids and their areal overlap. The names of the five fields are generated automatically from the three character ids of the participating grids that appear in the above initialization call. For example, for atmosphere/sea ice exchange on the coupler’s surface exchange grid, the following fields are read by xgrid_mod: I_ATM_ATMxOCN, J_ATM_ATMxOCN, I_OCN_ATMxOCN, J_OCN_ATMxOCN, and AREA_ATMxOCN. These fields were placed in grid_spec.nc by 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. Make_xgrids expects a NetCDF format input specification for the ice/ocean grid. Three fields are required to be in this file:
- wet – a 2D array of double precision numbers set to 1.0 where the ice and ocean models are active and 0.0 else where. Wet has im indices in the i (pseudo east-west) direction and jm indices in the j (pseudo north-south) direction. These correspond to the global arrays of temperature, salinity and ice thickness in the coupled climate model.
- geo_lonc and
- geo_latc – 2D double precision arrays (dimensioned im+1 by jm+1) that contain the longitudes and latitudes (respectively) of the corners of the sea ice and ocean model grid cells in degrees.
Since the atmosphere and land models are required to be longitude/latitude, 1D arrays of the longitude and latitude boundaries suffice to specify their grids. Make_xgrids expects this information to be provided in text files with a single latitude or longitude (in degrees) per line. In both the 2D and 1D boundary specification arrays, the coordinate values must increase monotonically with index. Make_xgrids copies all fields of the 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 and Hodgeman, 1974). 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 et al, 1990). 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 as in Jones (1999) by taking the integral of the negative sine of latitude around the boundary of a polygon. 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.
As of this writing (10/01) the ocean grid generator can optionally generate a single non-longitude/latitude grid: the tripolar grid of Murray (1996). This grid a a composite of two grids that are connected along a specified “join” latitude. To the south of the join, a standard longitude/latitude grid is used. This grid has a single pole – the south pole. The grid used north of the join is generated by taking a stereographic projection of a hemisphere containing both poles and reprojecting it onto a sphere with a different radius so that it fits perfectly into the region north of the join. This grid is known as the “bipolar” grid and it is rotated within the join latitude to place its poles over land (Canada and Siberia). Thus, all three poles of the tripolar grid fall over land. Recall that the land model is on a standard longitude/latitude grid and so is not impacted by the bipolar grid poles over Canada and Siberia. The tripolar grid is shown as Murray’s figure 7 (reproduced here).
Although it may not be apparent at first, the tripolar grid is a logically rectangular grid and is representable as an array. The “top” of the array follows the bipolar grid’s prime meridion between its poles. This line is known as the “cut” or “fold”. The figure to the right shows the bipolar grid separating at the cut to form a cylinder representable by an array that is cyclic in the i-direction. Array elements along the cut communicate with their mirror partners on the other side. Mpp_domains supports this kind of communication with the FOLD_NORTH_EDGE option to mpp_define_domains (see http://www.gfdl.noaa.gov/~vb/mpp_domains.html).  When vector quantities are passed across this cut, the sign must be changed on both u and v components (mpp_domains also supports this). The processor domains must also have mirror partners and mpp_domains currently requires that there be a processor boundary between the last and first i-row elements along the cyclic boundary on the pseudo-east/west edge. Consequently, when using the tripolar grid, arrays of geographic fields must start at the longitude of one of the bipolar grid poles. We have chosen the Siberian pole for admittedly non-science reasons.
A final tripolar grid issue concerns the specification of the bipolar grid longitudes in the region north of the join. Because of its transverse orientation, the bipolar grid longitudes just north of the join run nearly parallel to the latitudes lines south of the join and may be thought of as psuedo-latitude or i-lines lines placed in the bipolar region. The bipolar grid latitudes, on the other hand, are extensions of the longitude lines south of the join and are completely determined by them. The bipolar longitudes are not so determined and have only the requirement that they bound an even number of cells so that geographic fields will have equal numbers of elements on either side of the cut and so can be represented as arrays. The location of a bipolar longitude can be determined by the geographic latitude at which it crosses the bipolar equator. Grid_generator takes this to be the latitude specified for an equivalent non-tripolar grid. Thus, the geographic location of i-lines is unchanged along the bipolar equator when the tripolar_grid option is switched on and off in grid_generator‘s namelist input. If the latitudes are specified in a continuous fashion for a non-tripolar grid, when the tripolar_grid option is turned on they will remain continuous along the bipolar grid equator (a geographic longitude line) but will be discontinuous elsewhere north of the join.
- 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.
- Jones, P. W., 1999: First- and second-order conservative remapping schemes for grids in spherical coordinates. Monthly Weather Review, 127, 2204-2210.
- Murray, R. J., 1996: Explicit generation of orthogonal grids for ocean models. Journal of Computational Physics, 126, 251-273.
- Sutherland, I. E. and G. W. Hodgeman, 1974: Reentrant polygon clipping, CACM, 17(1), 32-42.