The pygridgen API¶
Tools for creating curvilinear grids using gridgen by Pavel Sakov
Return a container for a sequence of Focus objects.
The sequence is populated by using
add_focus(), which defines a point (
yo), around which the grid is focused by a factor for the provided
extentin the along the given
axis. The region of focusing will be approximately Gaussian, and the resolution will be increased by approximately the value of
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.
>>> 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)¶
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 y-direction.
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.
Curvilinear Arakawa C-Grid.
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 C-grid properties, such as the locations of the cell centers (rho-points), 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.
x, y : numpy.ndarray
Arrays of the x/y vertex/node positions
>>> 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-coordinate of the grid vertices (a.k.a. nodes)
y-coordinate of the grid vertices (a.k.a. nodes)
Mask for the cells (same as mask_rho)
x-coordinates of cell centroids
y-coordinates of cell centroids
Returns the mask for the cells
x-coordinate of u-point (leading edge in i-direction?)
y-coordinate of u-point (leading edge in i-direction?)
Mask for the u-points
x-coordinate of y-point (leading edge in j-direction?)
y-coordinate of y-point (leading edge in j-direction?)
mask for the v-points
x-coordinate of the anchor node for each cell? (upper left?)
y-coordinate of the anchor node for each cell? (upper left?)
mask for the psi-points
dimension of cell in x-direction?
dimension of cell in y-direction?
Calculate orthogonality error in radians
Should deprecate in favor of property
Mask Cartesian points contained within the polygon defined by
A cell is masked if the cell center (x_rho, y_rho) is within the polygon. Other sub-masks (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)
polyverts : sequence of 2-tuples 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.
CGrid_geo(lon, lat, proj, use_gcdist=True, ellipse='WGS84')¶
Curvilinear Arakawa C-grid 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’).
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
latinto 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
Shorthand for lon_vert
Shorthand for lat_vert
Gridgen(xbry, ybry, beta, shape, ul_idx=0, focus=None, proj=None, nnodes=14, precision=1e-12, nppe=3, newton=True, thin=True, checksimplepoly=True, verbose=False, autogen=True)¶
Main class for curvilinear-orthogonal grid generation.
xbry, ybry : array-like
One dimensional sequences of the x- and y-coordinates of the grid boundary.
beta : array-like
Turning values of each coordinate defined by
ybry. The sum of all beta values must equal 4. If you think about this like the right-hand 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 : two-tuple of ints (ny, nx)
The number of cells that would cover the full spatial extent of the grid in standard C-order (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
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.
A 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.0e-12)
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., 1e-3 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 Gauss-Newton 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
Some weird intermediate value that takes a long time to the C code to compute with complex boundaries.
The number of sigma values.
Number of nodes in the x-direction (columns).
Number of nodes in the y-direction (rows).
The shape of the overall grid (row, columns).
The business end of this whole thing. Collects all of the inputs, passes them to the gridgen-c code, and returns arrays of node coordinates. Unless
autogenwas set to False, this happens when the object is instantiated.
rho_to_vert(xr, yr, pm, pn, ang)¶
Possibly converts centroids to nodes
return u-, v-, and psi-masks based on input rho-mask
rmask : ndarray
mask at CGrid rho-points
(umask, vmask, pmask) : ndarrays
masks at u-, v-, and psi-points