Utility Classes and Functions (discretize.utils)

The utils package contains utilities for helping with common operations involving discrete meshes

Utility Classes

TensorType(mesh, tensor)

Class for determining property tensor type.


Carries out arithmetic operations between 0 and arbitrary quantities.


Carries out arithmetic operations involving the identity.

Utility Functions

Code Utilities


Determine if the input argument is a scalar.

as_array_n_by_dim(pts, dim)

Ensures the given array will have dim columns.


Decorator to wrap functions with soft dependencies.

Coordinate Transform Utilities

rotate_points_from_normals(xyz, v0, v1[, x0])

Rotate a set of xyz locations about a specified point.

rotation_matrix_from_normals(v0, v1[, tol])

Generate a 3x3 rotation matrix defining the rotation from vector v0 to v1.

cylindrical_to_cartesian(grid[, vec])

Transform a grid or a vector from cylindrical coordinates \((r, \theta, z)\) to Cartesian coordinates \((x, y, z)\).

cartesian_to_cylindrical(grid[, vec])

Transform a grid or a vector from Cartesian coordinates \((x, y, z)\) to cylindrical coordinates \((r, \theta, z)\).

Interpolation Utilities

interpolation_matrix(locs, x[, y, z])

Generate interpolation matrix which maps a tensor quantity to a set of locations.

volume_average(mesh_in, mesh_out[, values, ...])

Volume averaging interpolation between meshes.

IO utilities


Load discretize mesh saved to json file.

download(url[, folder, overwrite, verbose])

Download file(s) stored in a cloud directory.

Matrix Utilities

mkvc(x[, n_dims])

Creates a vector with specified dimensionality.


Generate sparse diagonal matrix from a vector.


Return inverse of a sparse diagonal matrix


Generate sparse identity matrix.

kron3(A, B, C)

Compute kronecker products between 3 sparse matricies.

spzeros(n1, n2)

Generate sparse matrix of zeros of shape=(n1, n2).


Create 1D difference (derivative) operator from nodes to centers.


Create 1D averaging operator from nodes to cell-centers.


Create 1D averaging operator from cell-centers to nodes.

ndgrid(*args[, vector, order])

Generate gridded locations for 1D, 2D, or 3D tensors.

ind2sub(shape, inds)

Return subscripts of tensor grid elements from indices.

sub2ind(shape, subs)

Return indices of tensor grid elements from subscripts.

get_subarray(A, ind)

Extract a subarray

inverse_3x3_block_diagonal(a11, a12, a13, ...)

Invert a set of 3x3 matricies from vectors containing their elements.

inverse_2x2_block_diagonal(a11, a12, a21, a22)

Invert a set of 2x2 matricies from vectors containing their elements.

make_property_tensor(mesh, tensor)

Construct the physical property tensor.

inverse_property_tensor(mesh, tensor[, ...])

Construct the inverse of the physical property tensor.

Mesh Utilities


Unpack a condensed representation of cell widths or time steps.

closest_points_index(mesh, pts[, grid_loc])

Find the indicies for the nearest grid location for a set of points.

extract_core_mesh(xyzlim, mesh[, mesh_type])

Extracts the core mesh from a global mesh.

random_model(shape[, seed, anisotropy, its, ...])

Create random tensor model.

refine_tree_xyz(mesh, xyz[, method, ...])

Refine region within a TreeMesh

active_from_xyz(mesh, xyz[, grid_reference, ...])

Return boolean array indicating which cells are below surface

mesh_builder_xyz(xyz, h[, padding_distance, ...])

Generate a tensor or tree mesh using a cloud of points.

Utilities for Curvilinear Meshes

example_curvilinear_grid(nC, exType)

Creates and returns the gridded node locations for a curvilinear mesh.

volume_tetrahedron(xyz, A, B, C, D)

Returns the tetrahedron volumes for a specified set of verticies.

face_info(xyz, A, B, C, D[, average, ...])

Returns normal surface vector and area for a given set of faces.

index_cube(nodes, grid_shape[, n])

Returns the index of nodes on a tensor (or curvilinear) mesh.