PUBLIC INTERFACE ~ PUBLIC DATA ~ PUBLIC ROUTINES ~ NAMELIST ~ DIAGNOSTIC FIELDS ~ ERROR MESSAGES ~ REFERENCES ~ NOTES

Module xgrid_mod

Contact:  Michael Winton
Reviewers: 
Change History: WebCVS Log

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

        fms_mod
        mpp_mod
mpp_domains_mod
     mpp_io_mod
  constants_mod

PUBLIC INTERFACE

put_to_xgrid:
Scatters data from model grid onto exchange grid.
get_from_xgrid:
Sums data from exchange grid to model grid.
conservation_check:
Returns three numbers which are the global sum of a variable.
xgrid_init:
Initialize the xgrid_mod.
setup_xmap:
Sets up exchange grid connectivity using grid specification file and processor domain decomposition.
set_frac_area:
Changes sub-grid portion areas and/or number.
xgrid_count:
Returns current size of exchange grid variables.
some:
Returns logical associating exchange grid cells with given side two grid.

PUBLIC DATA

Name Type Value Units Description
xmap_type --- --- The fields of xmap_type are all private.

PUBLIC ROUTINES

  1. put_to_xgrid

    call put_to_xgrid (d, grid_id, x, xmap, remap_order)
    DESCRIPTION
    Scatters data from model grid onto exchange grid.


    INPUT
    d   
       [real, dimension(:,:)]
       [real, dimension(:,:,:)]
    grid_id   
       [ character(len=3)]
       [ character(len=3)]
    remap_method    exchange grid interpolation method. It has four possible values: FIRST_ORDER (=1), SECOND_ORDER(=2), SECOND_ORDER_MERID(=3) and SECOND_ORDER_ZONAL(=4). Default value is FIRST_ORDER.
       [integer,optional]

    INPUT/OUTPUT
    x   
       [real, dimension(:)]
       [real, dimension(:)]
    xmap   
       [xmap_type]
       [xmap_type]

  2. get_from_xgrid

    call get_from_xgrid (d, grid_id, x, xmap)
    DESCRIPTION
    Sums data from exchange grid to model grid.


    INPUT
    x   
       [real, dimension(:)]
       [real, dimension(:)]
    grid_id   
       [ character(len=3)]
       [ character(len=3)]

    INPUT/OUTPUT
    xmap   
       [xmap_type]
       [xmap_type]

    OUTPUT
    d   
       [real, dimension(:,:)]
       [real, dimension(:,:,:)]

  3. conservation_check

    call conservation_check (d, grid_id, xmap,remap_order)
    DESCRIPTION
    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.


    INPUT
    d   
       [real, dimension(:,:)]
       [real, dimension(:,:,:)]
    grid_id   
       [character(len=3)]
       [character(len=3)]
    remap_method   
       [integer,optional]

    INPUT/OUTPUT
    xmap   
       [xmap_type]
       [xmap_type]

    OUTPUT
       The global sum of a variable.

  4. xgrid_init

    call xgrid_init ( )
    DESCRIPTION
    Initialization routine for the xgrid module. It reads the xgrid_nml, writes the version information and xgrid_nml to the log file.


    OUTPUT
    remap_method    exchange grid interpolation method. It has four possible values: FIRST_ORDER (=1), SECOND_ORDER(=2), SECOND_ORDER_MERID(=3) and SECOND_ORDER_ZONAL(=4)
       [integer]

  5. setup_xmap

    call setup_xmap (xmap, grid_ids, grid_domains, grid_file)
    DESCRIPTION
    Sets up exchange grid connectivity using grid specification file and processor domain decomposition. Initializes xmap.


    INPUT
    grid_ids   
       [character(len=3), dimension(:)]
    grid_domains   
       [type(Domain2d), dimension(:)]
    grid_file   
       [character(len=*)]

    OUTPUT
    xmap   
       [xmap_type]

  6. set_frac_area

    call set_frac_area (f, grid_id, xmap)
    DESCRIPTION
    Changes sub-grid portion areas and/or number.


    INPUT
    f   
       [real, dimension(:,:,:)]
    grid_id   
       [character(len=3)]

    INPUT/OUTPUT
    xmap   
       [xmap_type]

  7. xgrid_count

     
xgrid_count (xmap)
    DESCRIPTION
    Returns current size of exchange grid variables.


    INPUT
    xmap   
       [xmap_type]

    OUTPUT
    xgrid_count   
       [integer]

  8. some

    call some (xmap, some_arr, grid_id)
    DESCRIPTION
    Returns logical associating exchange grid cells with given side two grid.


    INPUT
    xmap   
       [xmap_type]
    grid_id   
       [character(len=3)]

    OUTPUT
    some_arr    logical associating exchange grid cells with given side 2 grid.
       [logical, dimension(xmap%size)]

NAMELIST

&xgrid_nml

make_exchange_reproduce
Set to .true. to make xgrid_mod reproduce answers on different numbers of PEs. This option has a considerable performance impact.
[logical, default: .false.]
interp_method
exchange grid interpolation method. It has four options: "first_order", "second_order", "second_order_merid", "second_order_zonal".
[character(len=64), default: 'first_order' ]

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.

ERROR MESSAGES

None.

REFERENCES

  1. A guide to grid coupling in FMS.
  2. A simple xgrid example.

COMPILER SPECIFICS

None.

PRECOMPILER OPTIONS

None.

LOADER OPTIONS

None.

TEST PROGRAM

None.

KNOWN BUGS

None.

NOTES

None.

FUTURE PLANS

None.

top