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.

     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

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.