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. Masking is supported for 2D logically rectangular (i.e. with grid_rank=2) grids in the SCRIP format. This application
can do regrid weight generation from a global or regional source grid to a global or regional destination grid.
It assumes that the source and destination grids are on a sphere and that the coordinates given in
the files are latitude and longitude values. The coordinates can either be in degrees or radians (this is indicated by the ``units'' attribute attached to the value).
This file based regrid weight generation application is parallel. This application is used in the
ESMF_RegridWeightGenCheck external demo, so that can serve as an example of its use.
This application requires the NetCDF libary to read the grid files and write out the weight files in NetCDF format. In addition, it also requires the LAPACK library to generate the patch regridding weights. To compile ESMF with the NetCDF library and the LAPACK library, please refer to the Third Party Libraries Section in the ESMF User Guide for more information.
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, the corner coordinates are also put into the corner stagger location
(ESMF_STAGGERLOC_CORNER), for conservative regridding. 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 indices 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 (unless ``-i'' is specified). 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'').
Masking is supported for grids generated from a SCRIP file where the grid_rank=2 (i.e. 2D logically rectangular grids). Masking is currently not supported for unstructured grids. If the variable ``grid_imask'' is set to 0 for a grid point, then that point is considered masked out and won't be used in the weights generated by the application.
If a destination point can't be mapped because it falls outside the unmasked source grid, then the default behavior of the application is to stop with an error. By specifying ``-i'' or the equivalent ``-ignore_unmapped'' the user can cause the application to ignore unmapped destination points. In this case, the output matrix won't contain entries for the unmapped destination points.
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 interpolation weights generated by this application are output to a NetCDF file (specified by the ``-w'' or ``-weight'' keywords). The format of this file is the same as that generated by SCRIP. Note that the sequence of the weights in the file can vary with the number of processors used to run the application. This means that two weight files generated by using different numbers of processors can contain exactly the same interpolation matrix, but can appear different in a direct line by line comparison (such as would be done by ncdiff).
The command line arguments are all keyword based. Both the long keyword 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|..]
[--ignore_unmapped|-i]
--src_type [SCRIP|ESMF]
--dst_type [SCRIP|ESMF]
-t [SCRIP|ESMF]
-r
--src_regional
--dst_regional
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.
--ignore_unmapped
or
-i - ignore unmapped destination points. If not specified
the default is to stop with an error if an unmapped
point is found.
--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.
-r - an optional argument specifying that the source and
destination grids are regional grids. If the argument
is not given, the grids are assumed to be global.
--src_regional - an optional argument specifying that the source is
a regional grid and the destination is a global grid.
--dst_regional - an optional argument specifying that the destination
is a regional grid and the source is a global grid.