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 theGrid
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 aGrid
in memory, or from SCRIP formatted or CF compliant GRIDSPEC file. The arguments for each type ofGrid
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
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 in-memory:
- Parameters:
staggerloc (StaggerLoc) – The stagger location of the coordinate values. If
None
, defaults toCENTER
in 2D andCENTER_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 toMONOPOLE
.
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 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 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 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 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 esmpy.
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.