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 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 a Grid 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:
1
,2
or3
. IfNone
, defaults to1
.  pole_dim (int) – The pole dimension
1
or2
. IfNone
, defaults to2
.  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
.

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 byupper_bounds  lower_bounds
.

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 theGrid
and the second index represent the coordinate dimensions of theGrid
.Returns: The coordinates of the Grid
.

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

periodic_dim
¶ Return type: int Returns: The periodic dimension of the Grid
(e.g.0
forx
orlongitude
,1
fory
orlatitude
, etc.).

pole_dim
¶ Return type: int Returns: The pole dimension of the Grid
(e.g.0
forx
orlongitude
,1
fory
orlatitude
, etc.).

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 byupper_bounds  lower_bounds
.

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

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 byupper_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 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[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.
 staggerloc (StaggerLoc) – The stagger location of the coordinate
values. If

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 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.
 staggerloc (StaggerLoc) – The stagger location of the item
values. If

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 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:
Parameters: item (GridItem) – The GridItem
to return.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.
 num_peri_dims (int) – The number of periodic dimensions, either