# ESMF_6_3_0r Regridding: Supported Grids and Features

This page describes the current support and testing status of the capabilities of the parallel regridding functionality provided by ESMF. (It includes a brief description of the capabilities, but see the Regrid Section in the ESMF reference manual for a more in depth description of ESMF regridding.) Regridding, also called remapping or interpolation, is the process of changing the grid that underlies data values while preserving 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 such as visualization.

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 values on the destination grid. This occurs through a parallel sparse matrix multiply. ESMF can be run so that only interpolation weights are generated, or so that weights are both generated and applied, or so that weights that come from some external source can be read in and applied.

# Regridding Options

### Options for running ESMF

**Integrated:**Integrated regridding means that interpolation weights are generated via subroutine calls during the execution of user code. Integrated regridding can perform the parallel sparse matrix multiply to apply these weights to interpolate user data. The integrated regridding can also be used to perform a sparse matrix multiply with user provided weights.**Offline:**Offline regridding means that interpolation weights are generated by a separate ESMF application, not within the user code. It only requires that a user input grid files in one of the accepted formats. The application is called the ESMF_RegridWeightGen application.

### Options for coordinate systems

**Cartesian:**Sometimes used for small regional grids. Coordinates expressed in terms of distance (e.g. x,y)**Spherical:**The standard spherical Earth representation. Coordinates expressed in angles. (e.g. longitude, latitude)

### Description of grid types

**Logically rectangular:**A grid whose points could be stored in a rectangular index space. Also sometimes called a structured grid. An example of this is a regular latitude-longitude grid. ESMF currently supports 2D or 3D logically rectangular grids:**2D:**These grids consist entirely of quadrilaterals.**3D:**These grids consist entirely of hexahedrons.

**Mesh:**A superset of logically rectangular grids consisting of cells with possibly different numbers of sides connected together. An example of this is a grid with triangular cells. ESMF currently supports 2D or 3D meshes:**2D:**ESMF supports meshes containing polygons with any number of sides (e.g. triangles, quadrilaterals, pentagons,...). Polygons with more than four sides are represented internally as a set of triangles, but to the user should behave as if they are a single polygon.**3D:**ESMF supports meshes containing hexahedrons and tetrahedrons.

### Options for regridding methods

**Bilinear:**Linear interpolation in 2 or 3 dimensions. [1]**Higher-order patch recovery (Patch):**Patch rendezvous method of taking the least squares fit of the surrounding surface patches. This is a higher order method that may produce interpolation weights that may be slightly less than 0 or slightly greater than 1. [2,3]**Nearest source to destination:**Each destination point is mapped to the closest source point. A source point can be mapped to multiple destination points. Some source points may not be mapped.**Nearest destination to source:**Each source point is mapped to the closest destination point. A destination point can be mapped to multiple source points, in which case the destination is the sum of the source values. Some destination points may not be mapped.**First-order conservative:**First order area averaged conservation is based on the ratio of source cell area overlapped with the corresponding destination cell area. If the**user areas**option (see below) is not used, then the areas used in this calculation are those calculated by ESMF and thus the ones for which the conservation holds. The**user areas**option allows the user to adjust the interpolation weights so that conservation is based on user-supplied areas.

### Support of regridding methods by grid type

**Logically rectangular:**ESMF currently supports regridding on 2D or 3D logically rectangular grids:**2D:**ESMF regridding currently supports the bilinear, higher-order patch recovery, nearest source to destination, nearest destination to source, and first-order conservative regridding methods on these.**3D:**ESMF regridding currently supports the bilinear, nearest source to destination, nearest destination to source, and first-order conservative regridding methods on these. The higher-order patch recovery method is currently not supported in 3D.

**Mesh:**ESMF currently supports regridding on 2D or 3D meshes:**2D:**ESMF regridding currently supports the bilinear, nearest source to destination, nearest destination to source, higher-order patch recovery, and first-order conservative regridding methods on all ESMF supported 2D meshes.**3D:**ESMF supports bilinear regridding on meshes containing hexahedrons, and nearest source to destination, nearest destination to source, and first-order conservative regridding on meshes containing hexahedrons and tetrahedrons. The higher-order patch recovery method is not currently supported in 3D.

### Options for poles, areas, masking, and unmapped points

**Full circle average:**Use all of the latitude points directly surrounding a pole to calculate an artificial pole value.**N-point average:**Specify the number of source points next to a given destination point to use to calculate an artificial pole value. This option is useful when the full circle average may yield a zero valued vector field.**No pole:**Do not use a pole value at all. The grid ends at the top and bottom rows of latitude points that are given.**User areas:**User provided areas are used to adjust conservative interpolation weights. If this option is used, then the provided areas will be the ones for which the conservation holds.**Destination masking:**Allow some points (usually representative of land masses) of the destination grid to not be included in the interpolation.**Source masking:**Allow some points of the source grid to not be included in the interpolation.**Ignore unmapped points:**Ignore points which lie outside of the interpolation space instead of issuing an error.**Line type:**Allow the user to control the type of the line which connects two points on a sphere.- Integrated regridding, bilinear method, Cartesian coordinates
- Integrated regridding, bilinear method, spherical coordinates
- Integrated regridding, higher-order patch recovery method, Cartesian coordinates
- Integrated regridding, higher-order patch recovery method, spherical coordinates
- Integrated regridding, nearest source to destination method, Cartesian coordinates
- Integrated regridding, nearest source to destination method, spherical coordinates
- Integrated regridding, nearest destination to source method, Cartesian coordinates
- Integrated regridding, nearest destination to source method, spherical coordinates
- Integrated regridding, first-order conservative method, Cartesian coordinates
- Integrated regridding, first-order conservative method, spherical coordinates
- Offline regridding, bilinear method, Cartesian coordinates
- Offline regridding, bilinear method, spherical coordinates
- Offline regridding, higher-order patch recovery method, Cartesian coordinates
- Offline regridding, higher-order patch recovery method, spherical coordinates
- Offline regridding, nearest source to destination method, Cartesian coordinates
- Offline regridding, nearest source to destination method, spherical coordinates
- Offline regridding, nearest destination to source method, Cartesian coordinates
- Offline regridding, nearest destination to source method, spherical coordinates
- Offline regridding, first-order conservative method, Cartesian coordinates
- Offline regridding, first-order conservative method, spherical coordinates
- Pole, area, and masking options for integrated regridding
- Pole, area, and masking options for offline regridding

# List of Tables

**Supported Grid Pairs for Different Regridding Methods**

**Pole, Area, and Masking Options**

**Numerical Results**

## Legend

Supported (completely and automatically tested) | |

Supported (partially and/or manually tested) | |

Should work, but not yet tested | |

Not supported |

# Supported Grid Pairs for Different Regridding Methods

### Supported grids: Integrated regridding, bilinear method, Cartesian coordinates

2D regional grids | 3D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D regional grids | Logically rectangular | ||||

Mesh | |||||

3D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Integrated regridding, bilinear method, spherical coordinates

2D global grids | 2D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D global grids | Logically rectangular | ||||

Mesh | |||||

2D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Integrated regridding, higher-order patch recovery method, Cartesian coordinates

2D regional grids | 3D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D regional grids | Logically rectangular | ||||

Mesh | |||||

3D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Integrated regridding, higher-order patch recovery method, spherical coordinates

2D global grids | 2D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D global grids | Logically rectangular | ||||

Mesh | |||||

2D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Integrated regridding, nearest source to destination method, Cartesian coordinates

2D regional grids | 3D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D regional grids | Logically rectangular | ||||

Mesh | |||||

3D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Integrated regridding, nearest source to destination method, spherical coordinates

2D global grids | 2D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D global grids | Logically rectangular | ||||

Mesh | |||||

2D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Integrated regridding, nearest destination to source method, Cartesian coordinates

2D regional grids | 3D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D regional grids | Logically rectangular | ||||

Mesh | |||||

3D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Integrated regridding, nearest destination to source method, spherical coordinates

2D global grids | 2D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D global grids | Logically rectangular | ||||

Mesh | |||||

2D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Integrated regridding, first-order conservative method, Cartesian coordinates

2D regional grids | 3D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D regional grids | Logically rectangular | ||||

Mesh | |||||

3D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Integrated regridding, first-order conservative method, spherical coordinates

2D global grids | 2D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D global grids | Logically rectangular | ||||

Mesh | |||||

2D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Offline regridding, bilinear method, Cartesian coordinates

2D regional grids | 3D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D regional grids | Logically rectangular | ||||

Mesh | |||||

3D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Offline regridding, bilinear method, spherical coordinates

2D global grids | 2D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D global grids | Logically rectangular | ||||

Mesh | |||||

2D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Offline regridding, higher-order patch recovery method, Cartesian coordinates

2D regional grids | 3D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D regional grids | Logically rectangular | ||||

Mesh | |||||

3D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Offline regridding, higher-order patch recovery method, spherical coordinates

2D global grids | 2D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D global grids | Logically rectangular | ||||

Mesh | |||||

2D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Offline regridding, nearest source to destination method, Cartesian coordinates

2D regional grids | 3D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D regional grids | Logically rectangular | ||||

Mesh | |||||

3D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Offline regridding, nearest source to destination method, spherical coordinates

2D global grids | 2D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D global grids | Logically rectangular | ||||

Mesh | |||||

2D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Offline regridding, nearest destination to source method, Cartesian coordinates

2D regional grids | 3D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D regional grids | Logically rectangular | ||||

Mesh | |||||

3D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Offline regridding, nearest destination to source method, spherical coordinates

2D global grids | 2D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D global grids | Logically rectangular | ||||

Mesh | |||||

2D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Offline regridding, first-order conservative method, Cartesian coordinates

2D regional grids | 3D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D regional grids | Logically rectangular | ||||

Mesh | |||||

3D regional grids | Logically rectangular | ||||

Mesh |

### Supported grids: Offline regridding, first-order conservative method, spherical coordinates

2D global grids | 2D regional grids | ||||

Logically rectangular | Mesh | Logically rectangular | Mesh | ||

2D global grids | Logically rectangular | ||||

Mesh | |||||

2D regional grids | Logically rectangular | ||||

Mesh |

# Pole, Area, and Masking Options

### Pole, area, and masking options for integrated regridding

Capabilities | Description | Bilinear | Patch | Conservative | Nearest S To D | Nearest D to S |
---|---|---|---|---|---|---|

Regridding | ||||||

Masking | Destination | |||||

Source | ||||||

Ignore unmapped points | ||||||

Pole options | Full circle average | N/A | N/A | N/A | ||

N-point average | N/A | N/A | N/A | |||

No pole | ||||||

User areas |
N/A | N/A | N/A | N/A | ||

Line type |
N/A |

### Pole and masking options for offline regridding

Capabilities | Description | Bilinear | Patch | Conservative | Nearest S To D | Nearest D to S |
---|---|---|---|---|---|---|

Regridding | ||||||

Masking | Destination | |||||

Source | ||||||

Ignore unmapped points | ||||||

Pole options | Full circle average | N/A | N/A | N/A | ||

N-point average | N/A | N/A | N/A | |||

No pole | ||||||

User areas |
N/A | N/A | N/A | N/A | ||

Line type |
N/A |

Numerical Results

The following table presents some specific examples of numerical results of the ESMF regridding capabilities. The numerical test cases that were evaluated for this table were computed using global grids. The results were collected from the ESMF_RegridWeightGenCheck external demo. All of the results in this table were generated by regridding a second order spherical harmonic-like field F = 2 + cos^2(theta)*cos(2*phi).

Methods | Grids [source to destination] |
Largest negative weight | Interpolation error (least squares) | Conservation relative error | Notes |
---|---|---|---|---|---|

Bilinear | Lat-lon 1 degree to Lat-lon 2.5 degree |
-6.00e-15 | 1.89e-05 | N/A | This test was done with no masking and the full circle average pole option. |

Cubed sphere grid (ne30np4-t2.nc) to Lat-lon 1.9x2.5 degree (fv1.9x2.5_050503.nc) |
-4.46e-11 | 2.54e-05 | N/A | ||

Patch | Lat-lon 1 degree to Lat-lon 2.5 degree |
-6.21e-02 | 1.85e-05 | N/A | This test was done with no masking and the full circle average pole option. |

Cubed sphere grid (ne30np4-t2.nc) to Lat-lon 1.9x2.5 degree (fv1.9x2.5_050503.nc) |
-6.40e-02 | 2.22e-05 | N/A | ||

Conservative | Lat-lon 1 degree to Lat-lon 2.5 degree |
0 | 1.39e-04 | 3.34e-13 | This test was done with no masking and the no pole option. |

Cubed sphere grid (ne30np4-t2.nc) to Lat-lon 1.9x2.5 degree (fv1.9x2.5_050503.nc) |
0 | 2.07e-04 | 7.11e-14 |

## References

**[1]**W.H. Press, S.A. Teukolsky, W.T. Vetterling, B.P. Flannery.

Numerical Recipes in C - The Art of Scientific Computing, Second Edition, pp. 123-128.

New York, Cambridge University Press, 1999.

**[2]**Khoei S.A. Gharehbaghi A, R.

The superconvergent patch recovery technique and data transfer operators in 3d plasticity problems.

Finite Elements in Analysis and Design, 43(8), 2007.

**[3]**K.C. Hung, H. Gu, Z. Zong.

A modified superconvergent patch recovery method and its application to large deformation problems.

Finite Elements in Analysis and Design, 40(5-6), 2004.