The main product delivered by ESMF is the ESMF library that allows application developers to write programs based on the ESMF API. In addition to the programming library, ESMF distributions come with a small set of applications that are of general interest to the community. These applications utilize the ESMF library to implement features such as printing general information about the ESMF installation, or generating regrid weight files. The provided ESMF applications are intended to be used as standard command line tools.
The bundled ESMF applications are built and installed during the usual ESMF installation process, which is described in detail in the ESMF User's Guide section "Building and Installing the ESMF". After the installation the applications will be located in the ESMF_APPSDIR directory, which can be found as a Makefile variable in the esmf.mk file. The esmf.mk file can be found in the ESMF_INSTALL_LIBDIR directory after a successful installation. The ESMF User's Guide discusses the esmf.mk mechanism to access the bundled applications in more detail in section "Using Bundled ESMF Applications".
The following sections provide in-depth documentation of the bundled ESMF applications. In addition, each application supports the standard --help command line argument, providing a brief description of how to invoke the program.
The ESMF_Info application prints basic information about the ESMF installation to stdout.
The application usage is as follows:
ESMF_Info [--help] where --help prints a brief usage message
In addition to the online regridding functionality, the ESMF distribution also
contains an exectuable for generating regridding weights. This tool reads in
two grid files and outputs weights for interpolation
between the two grids. The input and output files are all in netcdf format. The grid files are either in
the same format as is used as an input to SCRIP [3], or in the ESMF unstructured grid format ![[*]](crossref.png)
. The weight file is the same format as is output by SCRIP. The interpolation weights can be generated with
the bilinear, patch, or first order conservative methods decribed below. This application assumes that the
source and destination grids are spherical and that the coordinates given in the files are latitude and longitude
values. This file based regrid weight generation application is fully parallel. This application is used in the
ESMF_RegridWeightGenCheck external demo, so that can serve as an example of its use.
Internally this application uses the ESMF public API to generate the interpolation weights.
If a the source or destination grid is logically rectangular, then ESMF_GridCreate() is used to create an ESMF_Grid object. The cell center
coordinates of the input grid are put into the center stagger location (ESMF_STAGGERLOC_CENTER). In addition, for conservative regridding, the corner coordinates are also put into the corner stagger location
(ESMF_STAGGERLOC_CORNER). The 2D coordinates are mapped
into 3D Cartesian coordiantes by setting the regridScheme flag to ESMF_REGRID_SCHEME_FULL3D while calling
ESMF_FieldRegridStore(). The method
ESMF_MeshCreate() is used to create an ESMF_Mesh object, if the
source or destination grid is a cubed sphere grid or an unstructured grid. When making this call,
the flag convert3D is set to TRUE to convert the 2D coordinates into 3D Cartesian coordinates.
ESMF_FieldRegridStore() is used to generate the weight table and indicies table representing the interpolation matrix.
The regridding occurs in 3D to avoid problems with periodicity and with the pole singularity. This application supports four options for handling the pole region (i.e. the empty area above the top row of the source grid or below the bottom row of the source grid). The first option is to leave the pole region empty (``-p none''), in this case if a destination point lies above or below the top row of the source grid, it will fail to map, yielding an error. With the next two options, the pole region is handled by constructing an artificial pole in the center of the top and bottom row of grid points and then filling in the region from this pole to the edges of the source grid with triangles. The pole is located at the average of the position of the points surrounding it, but moved outward to be at the same radius as the rest of the points in the grid. The difference between these two artificial pole options is what value is used at the pole. The default pole option (``-p all'') sets the value at the pole to be the average of the values of all of the grid points surrounding the pole. For the other option (``-p N''), the user chooses a number N from 1 to the number of source grid points around the pole. For each destination point, the value at the pole is then the average of the N source points surrounding that destination point. For the last pole option (``-p teeth'') no artificial pole is constructed, instead the pole region is covered by connecting points across the top and bottom row of the source Grid into triangles. As this makes the top and bottom of the source sphere flat, for a big enough difference between the size of the source and destination pole regions, this can still result in unmapped destination points. Only pole option ``none'' is currently supported with the conservative interpolation method (i.e. ``-m conserve'').
This regridding application can be used to generate bilinear, patch, or first-order conservative interpolation weights. The default interpolation method is bilinear. The algorithm used by this application to generate the bilinear weights is the standard one found in many textbooks. Each destination point is mapped to a location in the source Mesh, the position of the destination point relative to the source points surrounding it is used to calculate the interpolation weights.
This application can also be used to generate patch interpolation weights. Patch interpolation is the ESMF version of a techique called ``patch recovery'' commonly used in finite element modeling [1] [2]. It typically results in better approximations to values and derivatives when compared to bilinear interpolation. Patch interpolation works by constructing multiple polynomial patches to represent the data in a source element. For 2D grids, these polynomials are currently 2nd degree 2D polynomials. The interpolated value at the destination point is the weighted average of the values of the patches at that point.
The patch interpolation process works as follows. For each source element containing a destination point we construct a patch for each corner node that makes up the element (e.g. 4 patches for quadrilateral elements, 3 for triangular elements). To construct a polynomial patch for a corner node we gather all the elements around that node. (Note that this means that the patch interpolation weights depends on the source element's nodes, and the nodes of all elements neighboring the source element.) We then use a least squares fitting algorithm to choose the set of coefficients for the polynomial that produces the best fit for the data in the elements. This polynomial will give a value at the destination point that fits the source data in the elements surrounding the corner node. We then repeat this process for each corner node of the source element generating a new polynomial for each set of elements. To calculate the value at the destination point we do a weighted average of the values of each of the corner polynomials evaluated at that point. The weight for a corner's polynomial is the bilinear weight of the destination point with regard to that corner. The patch method has a larger stencil than the bilinear, for this reason the patch weight matrix can be correspondingly larger than the bilinear matrix (e.g. for a quadrilateral grid the patch matrix is around 4x the size of the bilinear matrix). This can be an issue when performing a regrid weight generation operation close to the memory limit on a machine.
First-order conservative interpolation [4] is also available as a regridding method. This method will typically have a larger interpolation error than the previous two methods, but will do a much better job of preserving the value of the integral of data between the source and destination grid. In this method the value across each source cell is treated as a constant. The weights for a particular destination cell, are the area of intersection of each source cell with the destination cell divided by the area of the destination cell. Areas in this case are the great circle areas of the polygons which make up the cells (the cells around each center are defined by the corner coordinates in the grid file).
The command line arguments are all keyword based. Both the long keyward prefixed with '--' or the
one character short keyword prefixed with '-' are supported. The format to run the application is
as follows:
ESMF_RegridWeightGen [--help]
[--source|-s] src_grid_filename
[--destination|-d] dst_grid_filename
[--weight|-w] out_weight_file
[--method|-m] [bilinear|patch|conserve]
[--pole|-p] [none|all|teeth|1|2|..]
--src_type [SCRIP|ESMF]
--dst_type [SCRIP|ESMF]
-t [SCRIP|ESMF]
where
--help - print the usage message
--source or -s - a required argument specifying the source grid file name
--destination or -d - a required argument specifying the destination grid file name
--weight or -w - a required argument specifying the output regridding
weight file name
--method or -m - an optional argument specifying which interpolation method
is used. The value can be one of the following:
bilinear - for bilinear interpolation, also the default
method if not specified.
patch - for patch recovery interpolation
conserve - for first-order conservative interpolation
--pole or -p - an optional argument indicating what to do with the pole.
The value can be one of the following:
none - No pole, the source grid ends at the top (and bottom)
row of nodes specified in <source grid>.
all - Construct an artificial pole placed in the center of the
top (or bottom) row of nodes, but projected onto the
sphere formed by the rest of the grid. The value at
this pole is the average of all the pole values. This
is the default option.
teeth - No new pole point is constructed, instead the holes at
the poles are filled by constructing triangles across
the top and bottom row of the source Grid. This can be
useful because no averaging occurs, however, because
the top and bottom of the sphere are now flat, for a
big enough mismatch between the size of the destination
and source pole regions, some destination points may
still not be able to be mapped to the source Grid.
<N> - Construct an artificial pole placed in the center of the
top (or bottom) row of nodes, but projected onto the
sphere formed by the rest of the grid. The value at
this pole is the average of the N source nodes next to
the pole and surrounding the destination point (i.e.
the value may differ for each destination point. Here
N ranges from 1 to the number of nodes around the pole.
--src_type - an optional argument specifying the source grid file type. The
value could be either SCRIP or ESMF. Currently, the ESMF
file type is only available for the unstructured grid. The
default option is SCRIP.
--dst_type - an optional argument specifying the destination grid file type.
The value could be either SCRIP or ESMF. Currently, the ESMF
file type is only available for the unstructured grid. The
default option is SCRIP.
-t - an optional argument specifying the file types for both the
source and the destination grid files. The default option
is SCRIP. If both -t and --src_type or --dst_type are given
at the same time and they disagree with each other, an error
message will be generated.