Grid Definitions¶

GridDef Class¶

class pygeostat.data.grid_definition.GridDef(griddef=None, gridstr=None, gridarr=None, gridfl=None)¶

Class containing GSLIB grid definition.

Given either a GSLIB style grid string or an array arranged as [nx, xmn, xsiz, ny, ymn, ysiz, nz, zmn, zsiz] initialize the GridDef Class

Code author: Matthew Deutsch

Copy¶

GridDef.copy()¶: return a copy of this object

Block Volume¶

GridDef.blockvolume()¶: Return the volume of one block in the current grid definition

Cell Count¶

GridDef.count()¶: Return the number of blocks in the current grid definition

Change Block Number¶

GridDef.changeblocknum(nnx, nny, nnz, return_copy=False)¶

Function to change the number of blocks in the current grid while retaining the original bounding box.

Useful if attempting to work at a coarse grid (for speed) prior to obtaining a final estimate at the original resolution.

Parameters:	nnx (int) – New number of blocks in X direction nny (int) – New number of blocks in Y direction nnz (int) – New number of blocks in Z direction return_copy (bool) – if True will return a copy instead of modifying self

Example

Define a grid:

>>> import pygeostat as gs
>>> grid = gs.GridDef(gridstr="100 5 10  \n100 5 10  \n100 5 5")

Change the dimensions of the grid:

>>> grid.changedim(50,50,50)
>>> print(grid.nx,grid.xmn,grid.xsiz)
>>> print(grid.ny,grid.ymn,grid.ysiz)
>>> print(grid.nz,grid.zmn,grid.zsiz)

Use the changed resolution grid in a parameter file:

>>> parstr = "TestParFile \n{grd}"
>>> prog = gs.Program(program='./text.exe',parstr=parstr.format(grd=str(grid)))

Code author: Ryan Martin - 2015-11-13

Change Block Size¶

GridDef.changeblocksize(nxsiz, nysiz, nzsiz, return_copy=False)¶

Function to change the size of individual blocks in the grid. Finds the new number of blocks given the target sizes in each direction.

Parameters:	nxsiz (float) – New size of blocks in X nysiz (float) – New size of blocks in Y nzsiz (float) – New size of blocks in Z return_copy (bool) – if True will return a copy instead of modifying self

Code author: Ryan Martin - 2017-02-22

Convert To 2D¶

GridDef.convert_to_2d(orient='xy')¶: Flattens a grid to 2d by default on the xy plane, returning a new 2D GridDef object

Convert Index: 3D to 1D¶

GridDef.index3d_to_index1d(ix, iy, iz)¶

Will return the 0-indexed 1-Dimensional grid index given the 3 dimensional indices as well as a True/False indicator for inside or outside the grid definition.

Parameters:	ix (int or numpy.ndarray) – x index or n-length array of x indices iy (int or numpy.ndarray) – y index or n-length array of y indices iz (int or numpy.ndarray) – z index or n-length array of z indices
Returns:	1-d index or n-length array of 1-d indices ingrid (bool or numpy.ndarray): in (True) or out (False) of grid, returned if ingrid=True
Return type:	idx (int or numpy.ndarray)

Examples

Calculate a 1d grid index based on a 3d index (integers). Returns the index as an integer, as well as a boolean of whether the index is in the grid:

>>> ix, iy, iz = 2, 4, 0
>>> idx, ingrid = griddef.index3d_to_index1d(ix, iy, iz)

Calculate 1d grid indices based on 3d indices (numpy arrays). Returns an array of indices, as well as a boolean array of whether the index is in the grid:

>>> ix, iy, iz = np.arange(0, 5), np.arange(0, 5), np.zeros(5)
>>> idx, ingrid = griddef.index3d_to_index1d(ix, iy, iz)

Code author: Tyler Acorn June 2017, modified by Ryan M. Barnett March 2018

Convert Index: 1D to 3D¶

GridDef.index1d_to_index3d(idx)¶

Will return the 3-dimensional indices given a 1 dimensional index as well as a True/False indicator for inside or outside the grid definition.

Parameters:	idx (int or np.ndarray) – 1 dimensional index or numpy array of indices
Returns:	x index or numpy array of x indices iy (int or np.ndarray): y index or numpy array of y indices iz (int or np.ndarray): z index or numpy array of z indices ingrid (bool or np.ndarray): In (True) or Out (False) of grid
Return type:	ix (int or np.ndarray)

Examples

Calculate a 3d grid index based on a 1d index (integers). Returns the 3d index as an integer, as well as a boolean of whether the index is in the grid:

>>> idx = 918
>>> ix, iy, iz, ingrid = griddef.index1d_to_index3d(idx)

Calculate 3d grid indices based on 1d indices (numpy array). Returns a arrays of 3d indices, as well as a boolean array of whether the indices are in the grid:

>>> idx = np.array([0, 230, 460, 690, 920])
>>> ix, iy, iz, ingrid = griddef.index1d_to_index3d(idx)

Code author: Tyler Acorn June 2017, modified by Ryan M. Barnett March 2018

Coordinate(s) to 1D Index¶

GridDef.coord_to_index1d(x, y, z)¶

Will return the 0-indexed 1-Dimensional grid index given 3 coordinates as well as a True/False indicator for inside or outside the grid definition.

Uses:: pygeostat.coord_to_index3d()

Parameters:	x (float or numpy.ndarray) – x-coordinate value or numpy array of x-coordinate values y (float or numpy.ndarray) – y-coordinate value or numpy array of y-coordinate values z (float or numpy.ndarray) – z-coordinate value or numpy array of z-coordinate values
Returns:	1-d index of the grid block containing the coordinates ingrid (bool or numpy.ndarray): in (True) or out (False) of the grid
Return type:	idx (int or numpy.ndarray)

Examples

Calculate a 1d grid index based on an input coordinate (floats). Returns the index as an integer, as well as a boolean of whether the coordinate is in the grid:

>>> x, y, z = 30.5, 12.5, 0.5
>>> idx, ingrid = griddef.gridIndexCoords(x, y, z)

Calculate 1d grid indices based on input coordinates (numpy arrays). Returns the indices as an array, as well as a boolean array of whether the coordinates are in the grid:

>>> idx = np.array([0, 230, 460, 690, 920])
>>> ix, iy, iz, ingrid = griddef.index1d_to_index3d(idx)

Code author: modified from original pygeostat base by Ryan M. Barnett March 2018

Coordinate(s) to 3D Index¶

GridDef.coord_to_index3d(x, y, z)¶

Will return the 0-indexed 3-Dimensional grid indices given 3 coordinates as well as a True/False indicator for inside or outside the grid definition.

Parameters:	x (float or numpy.ndarray) – x-coordinate value or numpy array of x-coordinate values y (float or numpy.ndarray) – y-coordinate value or numpy array of y-coordinate values z (float or numpy.ndarray) – z-coordinate value or numpy array of z-coordinate values
Returns:	x index of the grid block iy (int or numpy.ndarray): y index of the grid block iz (int or numpy.ndarray): z index of the grid block ingrid (bool or numpy.ndarray): in (True) or out (False) of the grid
Return type:	ix (int or numpy.ndarray)

Examples

Calculate a 3d grid index based on an input coordinate (floats). Returns the index as integers, as well as a boolean of whether the coordinate is in the grid:

>>> x, y, z = 30.5, 12.5, 0.5
>>> ix, iy, iz, ingrid = griddef.coord_to_index3d(x, y, z)

Calculate 3d grid indices based on input coordinates (numpy arrays). Returns the indices as arrays, as well as a boolean array of whether the coordinates are in the grid:

>>> x, y = np.linspace(30.5, 100.5, 5), np.linspace(30.5, 100.5, 5)
>>> ix, iy, iz, ingrid = griddef.coord_to_index3d(x, y, z)

Code author: modified from original pygeostat base by Ryan M. Barnett March 2018

Pad Grid¶

GridDef.padgrid(nxpad, nypad, nzpad, return_copy=False)¶

Pad the grid on either side in all directions by the number of cells specified on input

Parameters:	nxpad (int or tuple) – number of cells in x direction to add to the grid on each side nypad (int or tuple) – number of cells in y direction to add to the grid on each side nzpad (int or tuple) – number of cells in z direction to add to the grid on each side return_copy (bool) – return copy or reinitialize self

Examples

Generate a grid definition:

>>> griddef = gs.GridDef(gridstr="50 0.5 1 \n50 0.5 1 \n1 0.5 1")

Symmetrically pad the grid cells in the x and y directions

>>> griddef2 = griddef2.padgrid(10, 10, 0, return_copy=True)

Asymmetrically pad the grid with cells in the x and y directions

>>> griddef2.padgrid((6, -5), 5, 0)

Code author: Ryan Martin - 2017-04-07

Extents¶

GridDef.extents(orient=None)¶

Return the extents of the current grid definition.

Parameters:	orient (str) – acceptable is ‘x’,’y’, or ‘z’ to give the dimensions along that direction
Returns:	various tuples based on what was passed None will return [(xmin, xmax), (ymin, ymax), (zmin, zmax)]

Extract Subgrid Around Points¶

GridDef.extractsubgrid(datafile, gridbuffer=None)¶

Extract a subgrid from self that spans the data in datafile

Parameters:	datafile (DataFile) – The datafile with x, y, z, attributes defined gridbuffer (int or 3-tuple) – number of grid cells to buffer the data with, optionally provide an integer for each direction as a 3-long tuple
Returns:	griddef – the griddef extracted from self
Return type:	GridDef

Warning

untested for 2D griddefs

Examples

Import a datafile asserting the columns specifying the point geometry:

>>> datafile = gs.DataFile("pointfile.out", x="X", y="Y", z="Z")

Specify the griddef for the whole domain

>>> domaingrid = gs.GridDef("100 3452.0 5.0 \n 100 667.0 5.0 \n 50 0.0 5.0)

Extract the subgrid from the total grid that spans the data:

>>> subgrid = domaingrid.extractsubgrid(datafile)

Code author: Ryan Martin - 2017-06-04

Generate Grid Point Array¶

GridDef.gridcoord(ix=None, iy=None, iz=None, idx=None)¶

Returns the 3 coordinate values based on the passed grid index. If no indices are passed, then the coordinates of all grid nodes are returned. Either all 3-D indices must all be passed (ix, iy, iz), the 1-D index is passed (idx), or all kwargs are None (returns all coordinates).

Parameters:	ix (int) – x index iy (int) – y index iz (int) – z index idx (int) – 1-D index
Returns:	x-coordinate value, or values if all grid nodes are returned y (float or numpy.ndarray): y-coordinate value, or values if all grid nodes are returned z (float or numpy.ndarray): z-coordinate value, or values if all grid nodes are returned
Return type:	x (float or numpy.ndarray)

Note

The option to return all grid node coordinates is memory intensive for > 60 M cell grids.

Usage:

Generate a grid definition, and generate the coordinate arrays:
>>> griddef = gs.GridDef(gridstr="50 0.5 1 \n50 0.5 1 \n50 0.5 1")
>>> x, y, z = griddef.gridcoord()
Generate coordinates (floats) corresponding with a specific 3d index:
>>> x, y, z = griddef.gridcoord(1, 1, 1)

Code author: Ryan Martin - 2016-05-17 (gengridpoints), mod. by Ryan Barnett, 2018-03-23

Iterate Through Grid XYZ¶

GridDef.iterxyz()¶

Function to iterate through the grid points.

No parameters.

Usage:

>>> griddef = gs.GridDef('50 0.5 1\n50 0.5 1\n50 0.5 1')
>>> for i, (x, y, z) in griddef.iterxyz():
...   print(i, x, y, z) # i is the 1d index in the griddef. x, y, z, are the pts

Code author: Ryan Martin - 2017-02-21

Get Slice Index¶

GridDef.get_sliceindex(orient, coordinate)¶

Returns the index in the grid along the correct dimension for the specificed slice i.e. the z index for an ‘xy’ slice

>>> griddef.get_slicecord('xy',700.2)

Parameters:	orient (str) – orientation of the current slice (‘xy’, ‘yz’, ‘xz’) coordinate (float) – index of the current slice
Returns:	index to the specified slice
Return type:	index (int)

Code author: Ryan Martin - 2016-05-02

Get 1D Start-End Index for Realization #¶

GridDef.get_rindex_start_end(realization)¶

Utility function for getting the starting and ending 1D realizations index values based on the GridDef

Parameters:	realization (int) – The realization number to get starting and ending index for
Returns:	(start_index, end_index)
Return type:	index (tuple)

Code author: Tyler Acorn - September 2017

Get Realization Index¶

GridDef.get_realization_index(realization)¶

Utility function for getting the 1D realizations index based on the griddef

Parameters:	realization (int) – The realization number to get index for
Returns:	list of index values for the realizations
Return type:	index (list)

Code author: Tyler Acorn - September 2017

Grid String¶

GridDef.__str__()¶: Return the string representation of the current grid definition

Grid Array¶

GridDef.gridarray()¶: Return the array of grid parameters (nx, xmn, xsiz, ny, ymn, ysiz, nz, zmn, zsiz)

Origin¶

GridDef.origin()¶: Return the origin of the current grid definition

Outline Points¶

GridDef.outline_pts(orient='xy')¶

return the xpts and ypts for plotline an outline of the current grid definition in the defined orientation

Parameters:	orient (str) – The orientation to return the corner points of the grid `'xy'`, `'xz'`, `'yz'` are the only accepted values
Returns:	the corner points of the grid in the specified orientation
Return type:	xpts, ypts (float, float)

Plot Grid Lines¶

GridDef.plotgridlines(ax, orient='xy', colors='k', linestyles='solid', lw=0.5, fixextents=False)¶

Given the plotting axis, ax, and the panelgrid, plot the boundaries of the panel with ax.hlines and ax.vlines functions

Parameters:

ax (mpl.axes) – a plotting axis, for example, ax = gs.pixelplt(data, griddef)
orient (str) – one of the slice orientations
colors (str) – permissible mpl colors, passed to hlines and vlines functions
linestyles (str) – permissible mpl linestyles, passed to hlines and vlines functions
lw (float) – the line weight of the boundaries. Passed to hlines and vlines functions

Examples

First generate the plotting axis of the total grid with some random data, then plot the grid lines for each grid

>>> ax = gs.pixelplt(empty1, totalgrid, orient=orient, figsize=(10, 10))
>>> totalgrid.plotgridlines(ax, lw=0.05, colors='black', orient=orient, fixextents=True)
>>> bh4_smu_grid.plotgridlines(ax, lw=0.1, colors='red', orient=orient)
>>> bh4_data_grid.plotgridlines(ax, lw=0.025, colors='blue', orient=orient)

Code author: Ryan Martin - 2017-06-04

Random Points from Grid¶

GridDef.random_points(n=100)¶: Generate random points from within the grid

Random Indices from Grid¶

GridDef.random_indices(dim=3, n=20, seed=None, buffer_x=None, buffer_y=None, buffer_z=None)¶

Generate a list of random indices from within the grid

Parameters:

dim (int) – 1 returns a 1D index, 3 returns x, y, and z indexes.
n (int) – The number of indices to return for each dimension
seed (int) – If provided will initialized the random number generator with the seed. If not provided then you will get different values every time you run this function
buffer_x (int) – you can set a buffer if you don’t want any random indices near the edge of the x border of the grid, Note: only works for dim=3
buffer_y (int) – you can set a buffer if you don’t want any random indices near the edge of the y border of the grid, Note: only works for dim=3
buffer_z (int) – you can set a buffer if you don’t want any random indices near the edge of the z border of the grid, Note: only works for dim=3

Returns:

“dim = 1” indice (list): a 1D indice of size n “dim = 3” xind (list): a list of indices in x dimension of size n yind (list): a list of indices in y dimension of size n zind (list): a list of indices in z dimension of size n

Set Axis Extents¶

GridDef.setaxisextents(ax, orient='xy')¶

Set the extents of the axis to the extent of the grid in the given orientation

Parameters:	ax (mpl.axes) – the axis that is being plotted on, e.g. ax = gs.pixelplt(data, griddef) orient (str) – one of xy, xz, or yz

Slice Coordinate¶

GridDef.get_slicecord(orient, index)¶

Returns the real coordinate for a slice given the index in the grid and orientation NOTE: assumes 0-indexed slice cordinates are passed.

Parameters:	orient (str) – orientation of the current slice (‘xy’, ‘yz’, ‘xz’) index (int) – index of the current slice
Returns:	coordinate of the current slice
Return type:	cord (float)

Usage:

>>> griddef.get_slicecord('xy',10)

Code author: Ryan Martin - 2015-10-16

Slice Index¶

GridDef.get_sliceindex(orient, coordinate)

Returns the index in the grid along the correct dimension for the specificed slice i.e. the z index for an ‘xy’ slice

>>> griddef.get_slicecord('xy',700.2)

Parameters:	orient (str) – orientation of the current slice (‘xy’, ‘yz’, ‘xz’) coordinate (float) – index of the current slice
Returns:	index to the specified slice
Return type:	index (int)

Code author: Ryan Martin - 2016-05-02

Vertical Indices¶

GridDef.xycoord_to_index1(x, y)¶

Returns grid indices corresponding with drilling a vertical drill hole intersecting all z blocks on the way down

Parameters:	x (float) – x-coordinate value y (float) – y-coordinate value
Returns:	grid indices of vertical ‘drill hole’
Return type:	indices (dict)

Griddef from Centroid¶

pygeostat.data.grid_definition.griddef_from_centroid(centroid, buf_x, buf_y, buf_z, xsize, ysize, zsize)¶

return a griddef from the centroid coordinate using the number of cells in the x, y, and z directions as well as the size of the cells

Parameters:

centroid (tuple) – A tuple of size 3 with the (x_coordinate, y_coordinate, z_coordinate)
buf_x (int, tuple) – number of cells in the x direction. if a single integer is passed then the buffer will be buf_x above and buf_x below the centroid
buf_y (int, tuple) – number of cells in the y direction. if a single integer is passed then the buffer will be buf_y above and buf_y below the centroid
buf_z (int, tuple) – number of cells in the z direction. if a single integer is passed then the buffer will be buf_z above and buf_z below the centroid
xsize (float) – Size of the cell in the x-direction
ysize (float) – Size of the cell in the y-direction
zsize (float) – Size of the cell in the z-direction

Returns:

gs.GridDef()

Code author: Tyler Acorn - November 19, 2017

Indexes Between Griddefs¶

pygeostat.data.gridtools.grid_diff_idx(target, outer)¶

Wrapper function for the high-speed jit implementation. For all nodes in target, find the indexes in the outer grid

Parameters:	target (GridDef) – indexes for these points in the outergrid are found outer (GridDef) – indexes into this grid are found