Grid

class esmpy.api.grid.Grid(max_index=None, num_peri_dims=0, periodic_dim=None, pole_dim=None, coord_sys=None, coord_typekind=None, staggerloc=None, pole_kind=None, filename=None, filetype=None, reg_decomp=None, decompflag=None, is_sphere=None, add_corner_stagger=None, add_user_area=None, add_mask=None, varname=None, coord_names=None, tilesize=None, regDecompPTile=None, name=None)

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.

Refer to the Grid Class of the ESMF Reference Manual for more information.

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: 0, 1 or 2. If None, defaults to 0.

  • pole_dim (int) – The pole dimension 0 or 1. If None, defaults to 1.

  • 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.

  • pole_kind (PoleKind) – Two item list which specifies the type of connection which occurs at the pole. The first value specifies the connection that occurs at the minimum end of the pole dimension. The second value specifies the connection that occurs at the maximum end of the pole dimension. If None, defaults to MONOPOLE.

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.

Cubed sphere:

REQUIRED:

Parameters:

tilesize (int) – The number of elements on each side of the tile of the cubed sphere grid.

OPTIONAL:

Parameters:

  • regDecompPTile (list) – List of DE counts for each dimension. The second index steps through the tiles. The total deCount is determined as the sum over the products of regDecompPTile elements for each tile. By default every tile is decomposed in the same way. If the total PET count is less than 6, one tile will be assigned to one DE and the DEs will be assigned to PETs sequentially, therefore, some PETs may have more than one DE. If the total PET count is greater than 6, the total number of DEs will be a multiple of 6 and less than or equal to the total PET count. For instance, if the total PET count is 16, the total DE count will be 12 with each tile decomposed into 1x2 blocks. The 12 DEs are mapped to the first 12 PETs and the remaining 4 PETs have no DEs locally.

  • name (str) – The name of the Grid.

property all_areas
Return type:

2D list of numpy arrays, where the first index represents the local DE and the second index represents the stagger locations of the Grid. (In the typical case of 1 DE per PET, see also area.)

Returns:

The Grid cell areas represented as numpy arrays of floats of size given by upper_bounds - lower_bounds.

property all_coords
Return type:

3D list of numpy arrays of size given by upper_bounds - lower_bounds, where the first index represents the local DE, the second index represents the stagger locations of the Grid and the third index represents the coordinate dimensions of the Grid. (In the typical case of 1 DE per PET, see also coords.)

Returns:

The coordinates of the Grid.

property all_lower_bounds
Return type:

2D list of numpy arrays, where the first index represents the local DE and the second index represents the stagger locations of the Grid. (In the typical case of 1 DE per PET, see also lower_bounds.)

Returns:

The lower bounds of the Grid represented as numpy arrays of ints of size given by upper_bounds - lower_bounds.

property all_masks
Return type:

2D list of numpy arrays, where the first index represents the local DE and the second index represents the stagger locations of the Grid. (In the typical case of 1 DE per PET, see also mask.)

Returns:

The masks of the Grid represented as numpy arrays of ints of size given by ` upper_bounds - lower_bounds`.

property all_sizes
Return type:

2D list of numpy arrays, where the first index represents the local DE and the second index represents the stagger locations of the Grid. (In the typical case of 1 DE per PET, see also size.)

Returns:

The sizes of the Grid represented as numpy arrays of ints of size given by upper_bounds - lower_bounds.

property all_upper_bounds
Return type:

2D list of numpy arrays, where the first index represents the local DE and the second index represents the stagger locations of the Grid. (In the typical case of 1 DE per PET, see also upper_bounds.)

Returns:

The upper bounds of the Grid represented as numpy arrays of ints of size given by upper_bounds - lower_bounds.

property 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. (It is an error to use this property in the uncommon case where there is something other than 1 DE per PET; in that case, use all_areas.)

property areatype
Return type:

TypeKind

Returns:

The ESMF typekind of the Grid cell areas.

property 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 represents the coordinate dimensions of the Grid.

Returns:

The coordinates of the Grid. (It is an error to use this property in the uncommon case where there is something other than 1 DE per PET; in that case, use all_coords.)

property coord_sys
Return type:

CoordSys

Returns:

The coordinate system of the Grid.

property finalized
Return type:

bool

Returns:

Indicate if the underlying ESMF memory for this object has been deallocated.

property has_corners
Return type:

bool

Returns:

A boolean value to tell if the Grid has corners allocated.

property local_de_count
Return type:

int

Returns:

The number of DEs in the Grid on this PET.

property 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. (It is an error to use this property in the uncommon case where there is something other than 1 DE per PET; in that case, use all_lower_bounds.)

property 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`. (It is an error to use this property in the uncommon case where there is something other than 1 DE per PET; in that case, use all_masks.)

property 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.

property name
Return type:

str

Returns:

The name of the Grid.

property ndims
Return type:

int

Returns:

The rank of the coordinate arrays of the Grid.

property num_peri_dims
Return type:

int

Returns:

The total number of periodic dimensions in the Grid.

property 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.).

property 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.).

property pole_kind
Return type:

A numpy array with as many values as the Grid has poles.

Returns:

The number of connections at each pole of the Grid.

property rank
Return type:

int

Returns:

The rank of the Grid.

property 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. (It is an error to use this property in the uncommon case where there is something other than 1 DE per PET; in that case, use all_sizes.)

property staggerloc
Return type:

list of bools

Returns:

The stagger locations that have been allocated for the Grid.

property type
Return type:

TypeKind

Returns:

The ESMF typekind of the Grid coordinates.

property 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. (It is an error to use this property in the uncommon case where there is something other than 1 DE per PET; in that case, use all_upper_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 [lon, lat] = (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 a single staggerloc is given, coord_dim is specified and there is a single local DE, 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 and there is a single local DE, 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, localde=0)

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

REQUIRED:

Parameters:

coord_dim (int) – The dimension number of the coordinates to return e.g. [x, y, z] = (0, 1, 2), or [lon, lat] = (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:
Returns:

A numpy array of coordinate values at the specified staggerloc.

get_item(item, staggerloc=None, localde=0)

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

REQUIRED:

Parameters:

item (GridItem) – The GridItem to return.

OPTIONAL:

Parameters:
Returns:

A numpy array of mask or area values at the specified staggerloc.