The pygridgen API¶
Tools for creating curvilinear grids using gridgen by Pavel Sakov

class
pygridgen.grid.
Focus
(*foci)[source]¶ Bases:
object
Return a container for a sequence of Focus objects.
The sequence is populated by using
add_focus()
, which defines a point (xo
oryo
), around which the grid is focused by a factor for the providedextent
in the along the givenaxis
. The region of focusing will be approximately Gaussian, and the resolution will be increased by approximately the value offactor
.Calls to the object return transformed coordinates:
xf, yf = foc(x, y)
where x and y must be within [0, 1], and are typically a uniform, normalized grid. The focused grid will be the result of applying each of the focus elements in the sequence they are added to the series.
Parameters: None Examples
>>> foc = pygridgen.Focus() >>> foc.add_focus(0.2, axis='x', factor=3.0, extent=0.20) >>> foc.add_focus(0.6, axis='y', factor=5.0, extent=0.35)
>>> x, y = np.mgrid[0:1:3j, 0:1:3j] >>> xf, yf = foc(x, y)
>>> print(xf) [[ 0. 0. 0. ] [ 0.36594617 0.36594617 0.36594617] [ 1. 1. 1. ]] >>> print(yf) [[ 0. 0.62479833 1. ] [ 0. 0.62479833 1. ] [ 0. 0.62479833 1. ]]

add_focus
(pos, axis, factor=2.0, extent=0.1)[source]¶ Add a single point of focus along an axis.
This adds a focused location to a grid and can be called multiple times in either the x or ydirection.
Parameters: pos : float
Relative position within the grid of the focus. This must be in the range [0, 1]
axis : string (‘x’ or ‘y’)
Axis along which the grid will be focused.
factor : float
Amount to focus grid. Creates cell sizes that are factor smaller (factor > 1) or larger (factor < 1) in the focused region.
extent : float
Lateral extent of focused region.


class
pygridgen.grid.
CGrid
(x, y)[source]¶ Bases:
object
Curvilinear Arakawa CGrid.
The basis for the CGrid class are two arrays defining the verticies of the grid in Cartesian (for geographic coordinates, see
CGrid_geo
). An optional mask may be defined on the cell centers. Other Arakawa Cgrid properties, such as the locations of the cell centers (rhopoints), cell edges (u and v velocity points), cell widths (dx and dy) and other metrics (angle, dmde, and dndx) are all calculated internally from the vertex points.Input vertex arrays may be either masked or regular numpy arrays. If masked arrays are used, the mask will be a combination of the specified mask (if given) and the masked locations.
Parameters: x, y : numpy.ndarray
Arrays of the x/y vertex/node positions
Examples
>>> import numpy as np >>> import pygridgen >>> x, y = np.mgrid[0.0:7.0, 0.0:8.0] >>> x = np.ma.masked_where((x < 3) & (y < 3), x) >>> y = np.ma.MaskedArray(y, x.mask) >>> grd = pygridgen.grid.CGrid(x, y) >>> print(grd.x_rho) [[   0.5 0.5 0.5 0.5] [   1.5 1.5 1.5 1.5] [   2.5 2.5 2.5 2.5] [3.5 3.5 3.5 3.5 3.5 3.5 3.5] [4.5 4.5 4.5 4.5 4.5 4.5 4.5] [5.5 5.5 5.5 5.5 5.5 5.5 5.5]] >>> print(grd.mask) [[ 0. 0. 0. 1. 1. 1. 1.] [ 0. 0. 0. 1. 1. 1. 1.] [ 0. 0. 0. 1. 1. 1. 1.] [ 1. 1. 1. 1. 1. 1. 1.] [ 1. 1. 1. 1. 1. 1. 1.] [ 1. 1. 1. 1. 1. 1. 1.]]

x
¶ xcoordinate of the grid vertices (a.k.a. nodes)

y
¶ ycoordinate of the grid vertices (a.k.a. nodes)

mask
¶ Mask for the cells (same as mask_rho)

x_rho
¶ xcoordinates of cell centroids

y_rho
¶ ycoordinates of cell centroids

mask_rho
¶ Returns the mask for the cells

x_u
¶ xcoordinate of upoint (leading edge in idirection?)

y_u
¶ ycoordinate of upoint (leading edge in idirection?)

mask_u
¶ Mask for the upoints

x_v
¶ xcoordinate of ypoint (leading edge in jdirection?)

y_v
¶ ycoordinate of ypoint (leading edge in jdirection?)

mask_v
¶ mask for the vpoints

x_psi
¶ xcoordinate of the anchor node for each cell? (upper left?)

y_psi
¶ ycoordinate of the anchor node for each cell? (upper left?)

mask_psi
¶ mask for the psipoints

dx
¶ dimension of cell in xdirection?

pm
¶

dy
¶ dimension of cell in ydirection?

pn
¶

dndx
¶

dmde
¶

angle
¶

angle_rho
¶

orthogonality
¶ Calculate orthogonality error in radians

mask_polygon
(polyverts, mask_value=False)[source]¶ Mask Cartesian points contained within the polygon defined by
polyverts
.A cell is masked if the cell center (x_rho, y_rho) is within the polygon. Other submasks (mask_u, mask_v, and mask_psi) are updated automatically.
A mask_value=False may be specified to alter the value of the mask set within the polygon (e.g., mask_value=True for water points)
Parameters: polyverts : sequence of 2tuples or numpy array (N, x)
The x/y coordinates of the polygon used to mask the grid.
mask_value : bool, optional (default = False)
The value of the mask to be set for cells whose centroids are inside the polygon.


class
pygridgen.grid.
CGrid_geo
(lon, lat, proj, use_gcdist=True, ellipse='WGS84')[source]¶ Bases:
pygridgen.grid.CGrid
Curvilinear Arakawa Cgrid defined in geographic coordinates.
For a geographic grid, the cell widths are determined by the great circle distances. Angles, however, are defined using the projected coordinates, so a projection that conserves angles must be used. This means typically either Mercator (projection=’merc’) or Lambert Conformal Conic (projection=’lcc’).
Parameters: lon, lat : numpy.ndarrays
Array of grid vertex/node positions in decimal degrees (i.e., longitude and latitude).
proj : pyproj.Proj
A projection object that can translate
lon
andlat
into Cartesian coordinates.use_gcdist : bool, optional (default = True)
Toggles the use of great circle distances when computing cell dimensions.
ellipse : str, optional (default = ‘WGS84’)
The ellipsoid reference for
lon
andlat
,
dx
¶

dy
¶

lon
¶ Shorthand for lon_vert

lat
¶ Shorthand for lat_vert


class
pygridgen.grid.
Gridgen
(xbry, ybry, beta, shape, ul_idx=0, focus=None, proj=None, nnodes=14, precision=1e12, nppe=3, newton=True, thin=True, checksimplepoly=True, verbose=False, autogen=True)[source]¶ Bases:
pygridgen.grid.CGrid
Main class for curvilinearorthogonal grid generation.
Parameters: xbry, ybry : arraylike
One dimensional sequences of the x and ycoordinates of the grid boundary.
beta : arraylike
Turning values of each coordinate defined by
xbry
andybry
. The sum of all beta values must equal 4. If you think about this like the righthand rule of basic physics, positive turning points (+1) face up and work to close the boundary polygon. Negative turning points (1) open it up (e.g., to define a side channel or other complexity). In between these points, neutral points should be assigned a value of 0.shape : twotuple of ints (ny, nx)
The number of cells that would cover the full spatial extent of the grid in standard Corder (i.e., rows, then columns).
ul_idx : optional int (default = 0)
The index of the what should be considered the upper left corner of the grid boundary in the
xbry
,ybry
, and beta inputs. This is actually more arbitrary than it sounds. Put it some place convenient for you, and the algorithm will conceptually rotate the boundary to place this point in the upper left corner. Keep that in mind when specifying the shape of the grid.focus :
Focus
, optionalA focus object to tighten/loosen the grid in certain sections.
proj : pyproj.Proj, optional
A pyproj projection to be used to convert lat/lon coordinates to a projected (Cartesian) coordinate system (e.g., UTM, state plane).
nnodes : int, optional (default = 14)
The number of nodes used in grid generation. This affects the precision and computation time. A rule of thumb is that this should be equal to or slightly larger than log10(precision).
precision : float, optional (default = 1.0e12)
The precision with which the grid is generated. The default value is good for lat/lon coordinate (i.e., smaller magnitudes of boundary coordinates). You can relax this to e.g., 1e3 when working in state plane or UTM grids and you’ll typically get better performance.
nppe : int, optional (default = 3)
The number of points per internal edge. Lower values will coarsen the image.
newton : bool, optional (default = True)
Toggles the use of GaussNewton solver with Broyden update to determine the sigma values of the grid domains. If False simple iterations will be used instead.
thin : bool, optional (default = True)
Toggle to True when the (some portion of) the grid is generally narrow in one dimension compared to another.
checksimplepoly : bool, optional (default = True)
Toggles a check to confirm that the boundary inputs form a valid geometry.
verbose : bool, optional (default = True)
Toggles the printing of console statements to track the progress of the grid generation.
autogen : bool, optional (default = True)
Toggles the automatic generation of the grid. Set to False if you want to delay calling the
generate_grid
method.
sigmas
¶ Some weird intermediate value that takes a long time to the C code to compute with complex boundaries.

nsigmas
¶ The number of sigma values.

nx
¶ Number of nodes in the xdirection (columns).

ny
¶ Number of nodes in the ydirection (rows).

shape
¶ The shape of the overall grid (row, columns).
