GFDL - Geophysical Fluid Dynamics Laboratory

Skip to main content

XGRID_MOD

PUBLIC INTERFACE / DATA / ROUTINES / NAMELIST / DIAGNOSTICS / CHANGES / ERRORS / REFERENCES / NOTES

Contact: Michael Winton
Reviewers:

OVERVIEW

XGRID_MOD implements exchange grids for coupled models running on multiple processors. An exchange grid is formed from the union of the bounding lines of the two (logically rectangular) participating grids. The exchange grid is therefore the coarsest grid that is a refinement of both participating grids. Exchange grids are used for two purposes by coupled models: (1) conservative interpolation of fields between models uses the exchange grid cell areas as weights and (2) the surface flux calculation takes place on the exchange grid thereby using the finest scale data available. XGRID_MOD uses a NetCDF grid specification file containing the grid cell overlaps in combination with the mpp_domains domain decomposition information to determine the grid and processor connectivities.

DESCRIPTION

XGRID_MOD is initialized with a list of model identifiers (three characters each), a list of mpp_domains domain data structures, and a grid specification file name. The first element in the lists refers to the "side one" grid. The remaining elements are on "side two". Thus, there may only be a single side one grid and it is further restricted to have no partitions (sub-grid areal divisions). In standard usage, the atmosphere model is on side one and the land and sea ice models are on side two. XGRID_MOD performs interprocessor communication on the side one grid. Exchange grid variables contain no data for zero sized partitions. The size and format of exchange grid variables change every time the partition sizes or number of partitions are modified with a set_frac_area call on a participating side two grid. Existing exchange grid variables cannot be properly interpreted after that time; new ones must be allocated and assigned with the put_to_xgrid call.

OTHER MODULES USED

  • mpp_mod (v?)
  • mpp_domains_mod (v?)
  • utilities_mod (v?)

PUBLIC INTERFACE

use xgrid_mod, only : xmap_type, setup_xmap, set_frac_area, xgrid_count,











                      put_to_xgrid, get_from_xgrid, some, conservation_check
  • setup_xmap 
    Sets up exchange grid connectivity using grid specification file and
processor domain decomposition.
  • set_frac_area 
    Changes sub-grid partion areas and/or number.
  • xgrid_count 
    Returns current size of exchange grid variables.
  • put_to_xgrid 
    Scatters data from model grid onto exchange grid.
  • get_from_xgrid 
    Sums data from exchange grid to model grid.
  • xmap_type 
    Contains the information needed to implement exchange grid (private).
  • some 
    Returns logical associating exchange grid cells with given side two grid.
  • conservation_check 
    Returns three numbers which are the global sum of a variable (1) on its
home model grid, (2) after interpolation to the other side grid(s), and (3)
after re_interpolation back onto its home side grid(s).  Conservation_check
must be called by all PEs to work properly.

PUBLIC DATA

The fields of xmap_type are all private.

PUBLIC ROUTINES

  • setup_xmap xmap type(xmap_type) grid_ids character(len=3), dimension(:) grid_domains type(Domain2d) , dimension(:) grid_file character(len=*)
  • set_frac_area f real , dimension(:,:,:) grid_id character(len=3) xmap type(xmap_type)
  • xgrid_count xmap type(xmap_type)
  • put_to_xgrid d real, dimension(:,:) or dimension(:,:,:) grid_id character(len=3) x real , dimension(:) xmap type(xmap_type)
  • get_from_xgrid d real, dimension(:,:) or dimension(:,:,:) grid_id character(len=3) x real , dimension(:) xmap type(xmap_type)
  • some grid_id character(len=3) xmap type(xmap_type)
  • conservation_check d real, dimension(:,:) or dimension(:,:,:) grid_id character(len=3) xmap type(xmap_type)

NAMELIST

make_exchange_reproduce  .false. set to .true. to make XGRID_MOD reproduce
                                 answers on different numbers of PEs.  This
                                 option has a considerable performance impact.

DIAGNOSTIC FIELDS

  • XGRID_MOD currently has no diagnostics.

DATA SETS

  • XGRID_MOD reads a NetCDF grid specification file to determine the grid and processor connectivities. The exchange grids are defined by 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. For example, if the side one grid id is "ATM" and the side two grid id is "OCN", XGRID_MOD expects to find the following five fields in the grid specification file: I_ATM_ATMxOCN, J_ATM_ATMxOCN, I_OCN_ATMxOCN, J_OCN_ATMxOCN, and AREA_ATMxOCN. These fields may be generated by the make_xgrids utility.

CHANGE HISTORY

  • Revision history

ERROR MESSAGES

  • A list of error messages by routine and what it means.

REFERENCES

  • A list of references.

COMPILER SPECIFICS

  • A list of compiler recommendations (might include recommended compiler version or optimization options for a particular system).

PRECOMPILER OPTIONS

  • A list of precompiler options.

LOADER OPTIONS

  • A list of loader options (e.g., libraries) and/or recommendations (note that this may be machine dependent).

KNOWN BUGS

  • A list of known bugs.

NOTES

  • Developer notes.

FUTURE PLANS

  • Future plans.