Grid¶

class
ESMF.api.grid.
Grid
(max_index=None, num_peri_dims=0, periodic_dim=None, pole_dim=None, coord_sys=None, coord_typekind=None, staggerloc=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 theGrid
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 aGrid
in memory, or from SCRIP formatted or CF compliant GRIDSPEC file. The arguments for each type ofGrid
creation are outlined below.Created inmemory:
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
or1
. IfNone
, defaults to0
.periodic_dim (int) – The periodic dimension:
0
,1
or2
. IfNone
, defaults to0
.pole_dim (int) – The pole dimension
0
or1
. IfNone
, defaults to1
.coord_sys (CoordSys) – Coordinate system for the
Grid
. IfNone
, defaults toSPH_DEG
.coord_typekind (TypeKind) – Type of the
Grid
coordinates. IfNone
, defaults toR8
.
Created either from file or inmemory:
 Parameters
staggerloc (StaggerLoc) – The stagger location of the coordinate values. If
None
, defaults toCENTER
in 2D andCENTER_VCENTER
in 3D.
Created from file:
REQUIRED:
 Parameters
filename (str) – The name of the NetCDF grid file.
filetype (FileFormat) – The grid
FileFormat
.
OPTIONAL:
 Parameters
is_sphere (bool) – Set to
True
for a spherical grid, orFalse
for regional. Defaults toTrue
.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 toFalse
.add_user_area (bool) – Set to
True
to read in the cell area from the grid file; otherwise, ESMF will calculate it. Defaults toFalse
.add_mask (bool) – Set to
True
to generate the mask using themissing_value
attribute defined invarname
. This argument is only supported with filetypeGRIDSPEC
. Defaults toFalse
.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 filetypeGRIDSPEC
. Defaults toNone
.coord_names (list) – A twoelement 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 toNone
.
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.

property
area
¶

property
coords
¶

property
has_corners
¶

property
lower_bounds
¶

property
mask
¶

property
max_index
¶

property
num_peri_dims
¶

property
periodic_dim
¶

property
pole_dim
¶

property
size
¶

property
staggerloc
¶  Return type
list of bools
 Returns
The stagger locations that have been allocated for the
Grid
.

property
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 toCENTER
in 2D andCENTER_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 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:
OPTIONAL:
 Parameters
staggerloc (StaggerLoc) – The stagger location of the item values. If
None
, defaults toCENTER
in 2D andCENTER_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.

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[lon, lat] = (0, 1)
(coordinates will not be returned ifcoord_dim
is not specified andstaggerlocs
is a list with more than one element).
OPTIONAL:
 Parameters
staggerloc (StaggerLoc) – The stagger location of the coordinate values. If
None
, defaults toCENTER
in 2D andCENTER_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:
OPTIONAL:
 Parameters
staggerloc (StaggerLoc) – The stagger location of the item values. If
None
, defaults toCENTER
in 2D andCENTER_VCENTER
in 3D. Returns
A numpy array of mask or area values at the specified staggerloc.