ESMP
Welcome to ESMP!
The ESMP home page has all of the
latest information on the ESMP project including release notes, known
bugs, supported platforms, and download information.
Please see the ESMF home page
for more information on ESMF in general.
Fast Parallel Grid Remapping for Unstructured and Structured Grids
gives a nice overview of the ESMF remapping functionality.
The ESMF Regridding Status
page gives a good overview of the functionality that is available through
various interfaces to ESMF regridding.
The ESMF_RegridWeightGen application
is a command-line version of the functionality that is available through ESMP.
Please contact esmf_support@list.woc.noaa.gov with any questions or problems.
Introduction
ESMP is based on the Earth System Modeling Framework (ESMF) software for
building and coupling weather, climate, and related models. ESMF has a robust,
parallel and scalable remapping package, used to generate remapping weights for
structured, unstructured, regional or global grids in NetCDF format. ESMP is a
prototype Python interface to the ESMF regridding utility.
ESMP supports a single-tile logically rectangular discretization type called
ESMP_Grid and an unstructured discretization type called ESMP_Mesh (ESMF also
supports observational data streams).
ESMP supports bilinear, finite element patch recovery and first order
conservative regridding. There is also an option to ignore unmapped
destination points and mask out points on either the source or destination.
Regridding on the sphere takes place in 3D Cartesian space, so the pole
problem is not an issue as it commonly is with many Earth system grid remapping
softwares. Grid objects can only be created in 2D space and Mesh objects can be
created in 2D or 3D space, but 3D conservative
regridding is not currently supported. Future plans for ESMP involve the
incorporation of the other ESMF discretization types (observational data
streams).
Remapping, also called regridding or interpolation, is the process of changing
the grid underneath field data values while preserving the qualities of the
original data. Different kinds of transformations are appropriate for
different problems. Regridding may be needed when communicating data between
Earth system model components such as land and atmosphere, or between
different data sets to support operations like plotting.
Regridding can be broken into two stages. The first stage is generation of an
interpolation weight matrix that describes how points in the source grid
contribute to points in the destination grid. The second stage is the
multiplication of values on the source grid by the interpolation weight matrix
to produce the appropriate values on the destination grid.
Getting the Code
The ESMF User’s Guide contains information on building and installing ESMF.
The ESMF Reference Manual contains information on the architecture of ESMF,
example code, and details of the API (Application Programming Interface).
Instructions on how to download the ESMP code can be found at the ESMP Download page:
http://earthsystemcog.org/projects/esmp/download
Installation
Please contact esmf_support@list.woc.noaa.gov with any questions or problems.
Requirements
The following packages are required to work with ESMP:
The following packages are optional:
- GNUMake - package validation
- mpi4py - python bindings to MPI
Environment Variables
The PYTHONPATH environment variable needs to include the directory containing
the ESMP directory. (e.g. if ESMP is in a directory named ‘python’ then,
PYTHONPATH+=<path-to-directory>/python)
The ESMFMKFILE environment variable should be set to the esmf.mk file of a
valid ESMF installation. If your ESMF installation libraries are in directory
ESMF_LIBSDIR, then you would set ESMFMKFILE=<path-to-ESMF_LIBSDIR>/esmf.mk
Use
To use this package in an external program, import it with:
import ESMP
Validation
To use the GNUMake system to validate the ESMP package, try the following
commands. This can also be done with python and shell commands, which are
included in sub-bullets:
- ‘gmake build’ or,
- ‘python src/ESMP_LoadESMF.py’ will build the ESMP.pyc library.
- ‘gmake run’ or,
- ‘python test/ESMP_utest_run.py’ will build and run the ESMP unit tests.
- ‘gmake run_tutorial’ or,
- ‘python tutorial/ESMP_tutorial.py’ will build and run the ESMP tutorial.
- ‘gmake run_tutorial_par’ or,
- ‘mpirun -np 4 python tutorial/ESMP_tutorial.py’ will build and run the ESMP tutorial in parallel - Note that this requires the mpi4py package.
- ‘gmake run_examples’ or,
- ‘python examples/ESMP_GridToMeshRegrid.py’ will build and run the structured
to unstructured regridding example.
- ‘gmake dust’ or,
- ‘rm *.log *.ESMF_LogFile’ will clean out all log files.
- ‘gmake clean’ or,
- ‘rm *.log *.ESMF_LogFile *.pyc’ will clean out all log files and libraries.
Please contact esmf_support@list.woc.noaa.gov with any questions or problems.
Interface
Classes
| Class |
Description |
|---|
| ESMP_Field |
A data field built on an unstructured mesh |
| ESMP_Grid |
A structured grid for coordinate representation |
| ESMP_Mesh |
An unstructured grid for coordinate representation |
| ESMP_VM |
The ESMF virtual machine |
Limitations
Data structure related:
- Grids only supported in 2 dimensions
- No FieldBundle class, only single Fields
- No access to Mesh coordinates
- No access to Field bounds
Testing related:
- Only tested on Darwin/gfortran and Linux/gfortran platforms
Tutorial
Warning
Under construction..
ESMP Field Regridding Tutorial
This is a demonstration of the regridding capabilities available through the
ESMF Python interface. This can be run as a stand-alone Python program - it
will dynamically load the ESMP library as long as the ESMFMKFILE environment
variable has been set to a valid ESMF installation and the ESMP library has
been installed. See the ESMP README for more information on the build and
installation.
The ESMF Python interface is very similar to the ESMF Fortran interface, and
regridding is accomplished in much the same way. One notable difference with
the ESMP interface is the use of the Numpy library for array data
representation. All named constants and library routines in the ESMF
interface have similar names, with the exception of an ESMP prefix instead
of ESMF_.
The program flow of this tutorial goes as follows: Two ESMP_Field objects
are created on top of two independent and different ESMP_Grid objects. The
Grids are created as periodic grids defined on the surface of the sphere, and
there is masking on the source Grid. The source Field is set to an analytic
function, and a conservative regridding operation is performed from the source
to the destination Field. After the regridding is completed, the destination
Field is compared to the exact solution over that domain and the conservation
of mass from the source to destination is validated.
Methods
-
static ESMP_tutorial.create_grid(bounds, domask)
- PRECONDITIONS: ESMP has been initialized, ‘bounds’ contains the number of
- indices required for the first two dimensions of a Grid.
‘domask’ is a boolean value that gives the option to put
a mask on this Grid.
POSTCONDITIONS: An ESMP_Grid has been created and returned.
-
static ESMP_tutorial.create_field(grid, name)
- PRECONDITIONS: An ESMP_Grid has been created, and ‘name’ is a string that
- will be used to initialize the name of a new ESMP_Field.
POSTCONDITIONS: An ESMP_Field has been created and returned.
-
static ESMP_tutorial.build_analyticfield(field, grid, mask)
- PRECONDITIONS: An ESMP_Field has been created as ‘field’, and ‘grid’ has
- been created and coordinates have been set on both the
center and corner stagger locations. ‘mask’ holds the
masked values of ‘grid’.
POSTCONDITIONS: The ‘field’ has been initialized to an analytic field.
-
static ESMP_tutorial.run_regridding(srcfield, dstfield, srcfracfield, dstfracfield)
- PRECONDITIONS: Two ESMP_Fields have been created and a regridding operation
- is desired from ‘srcfield’ to ‘dstfield’. The ‘srcfracfield’
and ‘dstfractfield’ are Fields created and intended to hold
the fractions of the source and destination fields which
contribute to the regridding operation.
POSTCONDITIONS: An ESMP regridding operation has set the data on ‘dstfield’.
-
static ESMP_tutorial.compute_mass(valuefield, areafield, fracfield, dofrac)
- PRECONDITIONS: Two fields have been created and initialized. ‘valuefield’
- contains data values on field built on the cells of a grid,
‘areafield’ contains the areas associated with the grid
cells, and ‘fracfield’ contains the fractions of each cell
which contributed to a regridding operation involving
‘valuefield. ‘dofrac’ is a boolean value that gives the
option to not use the ‘fracfield’.
POSTCONDITIONS: The mass of the data field is computed and returned.
-
static ESMP_tutorial.compare_fields(interp_field, exact_field, dstfracfield, srcmass, dstmass)
- PRECONDITIONS: ‘interp_field’ is a Field that holds the values restulting
- from a regridding operation, ‘exact_field’ is a Field
containing the values of the exact solution that is
expected, and ‘dstfracfield’ is a Field containing the
fractions of the ‘interp_field’ which contributed to the
regridding product. ‘srcmass’ and ‘dstmass’ are the
mass values for the source and destination data fields.
- POSTCONDITIONS: The interpolation accuracy of a regridding operation is
- determined by comparing the ‘interp_field’ to the
‘exact_field’. The mass conservation is validated by
comparing the ‘srcmass’ to the ‘dstmass’.
main()
# start up ESMF
ESMP.ESMP_Initialize()
# set the ESMF logging to log after every line
ESMP.ESMP_LogSet(True)
# create two unique Grids
srcgrid, srcmask = create_grid([18,10], True)
dstgrid, dstmask = create_grid([10,8], False)
# create the Fields
srcfield = create_field(srcgrid, 'srcfield')
dstfield = create_field(dstgrid, 'dstfield')
exact_field = create_field(dstgrid, 'dstfield_exact')
# create the area fields
srcareafield = create_field(srcgrid, 'srcfracfield')
dstareafield = create_field(dstgrid, 'dstfracfield')
# create the fraction fields
srcfracfield = create_field(srcgrid, 'srcfracfield')
dstfracfield = create_field(dstgrid, 'dstfracfield')
# initialize the Fields to an analytic function
srcfield = build_analyticfield(srcfield, srcgrid, srcmask)
exact_field = build_analyticfield(exact_field, dstgrid, dstmask)
# run the ESMF regridding
dstfield, srcfracfield, dstfracfield = run_regridding(srcfield, dstfield,
srcfracfield, dstfracfield)
# compute the mass
srcmass = compute_mass(srcfield, srcareafield, srcfracfield, True)
dstmass = compute_mass(dstfield, dstareafield, 0, False)
# compare results and output PASS or FAIL
compare_fields(dstfield, exact_field, dstfracfield, srcmass, dstmass)
# clean up
ESMP.ESMP_FieldDestroy(srcfield)
ESMP.ESMP_FieldDestroy(dstfield)
ESMP.ESMP_FieldDestroy(exact_field)
ESMP.ESMP_FieldDestroy(srcfracfield)
ESMP.ESMP_FieldDestroy(dstfracfield)
ESMP.ESMP_GridDestroy(srcgrid)
ESMP.ESMP_GridDestroy(dstgrid)
# stop ESMF
ESMP.ESMP_Finalize()