Grid Definitions¶

GridDef Class¶

class pygeostat.data.grid_definition.GridDef(griddef=None, grid_str=None, grid_arr=None, grid_file=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

Copy¶

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

Block Volume¶

GridDef.block_volume¶: 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

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)

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)

Coordinate(s) to 1D Index¶

GridDef.get_index(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.get_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)

Coordinate(s) to 3D Index¶

GridDef.get_index3d(x, y, z)¶

Retruns 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.get_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.get_index3d(x, y, z)

Change Block Size¶

GridDef.change_blocksize(xsiz_new, ysiz_new, zsiz_new, 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

xsiz_new (float) – New size of blocks in X
ysiz_new (float) – New size of blocks in Y
zsiz_new (float) – New size of blocks in Z
return_copy (bool) – if True will return a copy instead of modifying self

Change Block Number¶

GridDef.change_blocknum(nx_new, ny_new, nz_new, return_copy=False)¶

Function to change the blocksize of 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

nx_new (int) – New number of blocks in X direction
ny_new (int) – New number of blocks in Y direction
nz_new (int) – New number of blocks in Z direction

Example

Define a grid:

>>> import pygeostat as gs
>>> grid = gs.GridDef(grid_str="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)))

Pad Grid¶

GridDef.pad_grid(nx_pad, ny_pad, nz_pad, return_copy=False)¶

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

Parameters

nx_pad (int or tuple) – number of cells in x direction to add to the grid on each side
ny_pad (int or tuple) – number of cells in y direction to add to the grid on each side
nz_pad (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)

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

Get Coordinates based on Index/Indices¶

GridDef.get_coordinates(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.get_coordinates()
Generate coordinates (floats) corresponding with a specific 3d index:
>>> x, y, z = griddef.get_coordinates(1, 1, 1)

Get Slice Index¶

GridDef.get_slice_index(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_slice_index('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)

Grid Array¶

GridDef.grid_array¶: 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_points(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)

Sample Random Points from Grid¶

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

Sample 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

Slice Coordinate¶

GridDef.get_slice_coordinate(orient, index)¶

Returns the real coordinate for a slice given the index in the grid and orientation NOTE: assumes 0-indexed slice coordinates 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_slice_coordinate(‘xy’,10)

Slice Index¶

GridDef.get_slice_index(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_slice_index('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)

Vertical Indices¶

GridDef.get_vertical_indices(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)