Grid

class ESMF.api.grid.Grid(*args, **kwargs)

The Grid class is a Python wrapper object for the ESMF Grid. The individual values of all coordinate and mask arrays are referenced to those of the underlying Fortran ESMF object.

The Grid class is used to describe the geometry and discretization of logically rectangular physical grids. It also contains the description of the underlying topology and decomposition of the physical grid across the available computational resources. The most frequent use of the Grid class is to describe physical grids in user code so that sufficient information is available to perform regridding operations.

For more information about the ESMF Grid class, please see the ESMF Grid documentation.

A Grid can be created in two different ways, as a Grid in memory, or from SCRIP formatted or CF compliant GRIDSPEC file. The arguments for each type of Grid creation are outlined below.

Created in-memory:

REQUIRED:

Parameters:max_index (list) – An integer list of length 2 or 3, with the number of grid cells in each dimension.

OPTIONAL:

Parameters:
  • num_peri_dims (int) – The number of periodic dimensions, either 0 or 1. If None, defaults to 0.
  • periodic_dim (int) – The periodic dimension: 1, 2 or 3. If None, defaults to 1.
  • pole_dim (int) – The pole dimension 1 or 2. If None, defaults to 2.
  • coord_sys (CoordSys) – Coordinate system for the Grid. If None, defaults to SPH_DEG.
  • coord_typekind (TypeKind) – Type of the Grid coordinates. If None, defaults to R8.

Created either from file or in-memory:

Parameters:staggerloc (StaggerLoc) – The stagger location of the coordinate values. If None, defaults to CENTER in 2D and CENTER_VCENTER in 3D.

Created from file:

REQUIRED:

Parameters:

OPTIONAL:

Parameters:
  • is_sphere (bool) – Set to True for a spherical grid, or False for regional. Defaults to True.
  • add_corner_stagger (bool) – Set to True to use the information in the grid file to add the corner stagger to the grid. The coordinates for the corner stagger are required for conservative regridding. If not specified, defaults to False.
  • add_user_area (bool) – Set to True to read in the cell area from the grid file; otherwise, ESMF will calculate it. Defaults to False.
  • add_mask (bool) – Set to True to generate the mask using the missing_value attribute defined in varname. This argument is only supported with filetype GRIDSPEC. Defaults to False.
  • varname (str) – If add_mask is True, provide a variable name stored in the grid file and the mask will be generated using the missing value of the data value of this variable. The first two dimensions of the variable has to be the longitude and the latitude dimension and the mask is derived from the first 2D values of this variable even if this data is a 3D, or 4D array. This argument is only supported with filetype GRIDSPEC. Defaults to None.
  • coord_names (list) – A two-element array containing the longitude and latitude variable names in a GRIDSPEC file if there are multiple coordinates defined in the file. This argument is only supported with filetype GRIDSPEC. Defaults to None.
area
Return type:A list of numpy arrays with an entry for every stagger location of the Grid.
Returns:The Grid cell areas represented as numpy arrays of floats of size given by upper_bounds - lower_bounds.
areatype
Return type:TypeKind
Returns:The ESMF typekind of the Grid cell areas.
coords
Return type:2D list of numpy arrays of size given by upper_bounds - lower_bounds, where the first index represents the stagger locations of the Grid and the second index represent the coordinate dimensions of the Grid.
Returns:The coordinates of the Grid.
coord_sys
Return type:CoordSys
Returns:The coordinate system of the Grid.
has_corners
Return type:bool
Returns:A boolean value to tell if the Grid has corners allocated.
lower_bounds
Return type:A list of numpy arrays with an entry for every stagger location of the Grid.
Returns:The lower bounds of the Grid represented as numpy arrays of ints of size given by upper_bounds - lower_bounds.
mask
Return type:A list of numpy arrays with an entry for every stagger location of the Grid.
Returns:The mask of the Grid represented as numpy arrays of ints of size given by ` upper_bounds - lower_bounds`.
max_index
Return type:A numpy array with as many values as the Grid rank.
Returns:The number of Grid cells in each dimension of the grid.
num_peri_dims
Return type:int
Returns:The total number of periodic dimensions in the Grid.
periodic_dim
Return type:int
Returns:The periodic dimension of the Grid (e.g. 0 for x or longitude, 1 for y or latitude, etc.).
pole_dim
Return type:int
Returns:The pole dimension of the Grid (e.g. 0 for x or longitude, 1 for y or latitude, etc.).
rank
Return type:int
Returns:The rank of the Grid.
size
Return type:A list of numpy arrays with an entry for every stagger location of the Grid.
Returns:The size of the Grid represented as numpy arrays of ints of size given by upper_bounds - lower_bounds.
staggerloc
Return type:list of bools
Returns:The stagger locations that have been allocated for the Grid.
type
Return type:TypeKind
Returns:The ESMF typekind of the Grid coordinates.
upper_bounds
Return type:A list of numpy arrays with an entry for every stagger location of the Grid.
Returns:The upper bounds of the Grid represented as numpy arrays of ints of size given by upper_bounds - lower_bounds.
add_coords(staggerloc=None, coord_dim=None, from_file=False)

Add coordinates to the Grid at the specified stagger location.

Parameters:
  • staggerloc (StaggerLoc) – The stagger location of the coordinate values. If None, defaults to CENTER in 2D and CENTER_VCENTER in 3D.
  • coord_dim (int) – The dimension number of the coordinates to return e.g. [x, y, z] = (0, 1, 2), or [lat, lon] = (0, 1) (coordinates will not be returned if coord_dim is not specified and staggerlocs is a list with more than one element).
  • from_file (bool) – Boolean for internal use to determine whether the Grid has already been created from file.
Returns:

A numpy array of coordinate values if staggerloc and coord_dim are specified, otherwise return None.
add_item(item, staggerloc=None, from_file=False)

Allocate space for a Grid item (mask or areas) at a specified stagger location.

REQUIRED:

Parameters:item (GridItem) – The GridItem to allocate.

OPTIONAL:

Parameters:
  • staggerloc (StaggerLoc) – The stagger location of the item values. If None, defaults to CENTER in 2D and CENTER_VCENTER in 3D.
  • from_file (bool) – Boolean for internal use to determine whether the Grid has already been created from file.
Returns:

A numpy array of the mask or area values if a single staggerloc is given, otherwise return None.
copy()

Copy a Grid in an ESMF-safe manner.

Returns:A Grid shallow copy.
destroy()

Release the memory associated with a Grid.

get_coords(coord_dim, staggerloc=None)

Return a numpy array of coordinates at a specified stagger location. The returned array is NOT a copy, it is directly aliased to the underlying memory allocated by ESMF.

REQUIRED:

Parameters:coord_dim (int) – The dimension number of the coordinates to return e.g. [x, y, z] = (0, 1, 2), or [lat, lon] = (0, 1) (coordinates will not be returned if coord_dim is not specified and staggerlocs is a list with more than one element).

OPTIONAL:

Parameters:staggerloc (StaggerLoc) – The stagger location of the coordinate values. If None, defaults to CENTER in 2D and CENTER_VCENTER in 3D.
Returns:A numpy array of coordinate values at the specified staggerloc.
get_item(item, staggerloc=None)

Return a numpy array of item values at a specified stagger location. The returned array is NOT a copy, it is directly aliased to the underlying memory allocated by ESMF.

REQUIRED:

Parameters:item (GridItem) – The GridItem to return.

OPTIONAL:

Parameters:staggerloc (StaggerLoc) – The stagger location of the item values. If None, defaults to CENTER in 2D and CENTER_VCENTER in 3D.
Returns:A numpy array of mask or area values at the specified staggerloc.