GFDL - Geophysical Fluid Dynamics Laboratory

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.