Utility Classes and Functions (SimPEG.utils)#

The utils package contains utilities for helping with common operations involving SimPEG.

Many of the utilities are imported from discretize.utils. See that package’s documentation for many details on items.

Coordinates Utility Functions#

rotation_matrix_from_normals(v0, v1[, tol])

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

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

Rotate a set of xyz locations about a specified point.

Counter Utility Functions#


Class for recording iterations and operation times.





Curvilinear Utility Functions#

example_curvilinear_grid(nC, exType)

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

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.

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

Returns the tetrahedron volumes for a specified set of verticies.

IO Utility Functions#

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

Download all files stored in a cloud directory.

io_utils.read_dcip2d_ubc(file_name, ...)

Read UBC-GIF DCIP2D formatted survey or data files.

io_utils.read_dcip3d_ubc(file_name, data_type)

Read UBC-GIF DCIP3D formatted survey or data files.

io_utils.read_dcipoctree_ubc(file_name, ...)

Read UBC-GIF DCIP OcTree formatted survey or data files.

io_utils.read_dcip_xyz(file_name, data_type)

Read 2D or 3D DC/IP data from XYZ-formatted file.


Read UBC-GIF GG3D formatted survey or data files.


Read UBC-GIF GRAV3D formatted survey or data files.


Read UBC-GIF MAG3D formatted survey or data files.

io_utils.write_dcip2d_ubc(file_name, ...[, ...])

Write UBC-GIF DCIP2D formatted survey or data files.

io_utils.write_dcip3d_ubc(file_name, ...[, ...])

Write UBC-GIF DCIP3D formatted survey or data files.

io_utils.write_dcipoctree_ubc(file_name, ...)

Write UBC-GIF DCIP OcTree formatted survey or data files.

io_utils.write_dcip_xyz(file_name, data_object)

Write 2D or 3D DC/IP data to XYZ-formatted file.

io_utils.write_grav3d_ubc(filename, data_object)

Write UBC-GIF GRAV3D formatted survey or data files.

io_utils.write_gg3d_ubc(filename, data_object)

Write UBC-GIF GG3D formatted survey or data files.

io_utils.write_mag3d_ubc(filename, data_object)

Write UBC-GIF MAG3D formatted survey or data files.

Matrix Utility Functions#


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


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


Converts a set of 3D vectors from Cartesian to spherical coordinates.


Compute coterminal angle


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

define_plane_from_points(xyz1, xyz2, xyz3)

Compute constants defining a plane from a set of points.

diagEst(*args, **kwargs)

diagEst has been deprecated.

eigenvalue_by_power_iteration(combo_objfct, ...)

Estimate highest eigenvalue of one or a combo of objective functions using power iterations and the Rayleigh quotient.

estimate_diagonal(matrix_arg, n[, k, approach])

Estimate the diagonal of a matrix.

get_subarray(A, ind)

Extract a subarray

kron3(A, B, C)

Compute kronecker products between 3 sparse matricies.

ind2sub(shape, inds)

Return subscripts of tensor grid elements from indices.

inverse_2x2_block_diagonal(a11, a12, a21, a22)

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

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

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

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

Construct the inverse of the physical property tensor.

make_property_tensor(mesh, tensor)

Construct the physical property tensor.

mkvc(x[, n_dims])

Creates a vector with specified dimensionality.

ndgrid(*args[, vector, order])

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


Generate sparse diagonal matrix from a vector.


Return inverse of a sparse diagonal matrix


Generate sparse identity matrix.


Converts a set of 3D vectors from spherical to Catesian coordinates.

spzeros(n1, n2)

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

sub2ind(shape, subs)

Return indices of tensor grid elements from subscripts.


Return unique rows, row indices and inverse indices.

Mesh Utility Functions#

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.


Unpack a condensed representation of cell widths or time steps.

surface2inds(vrtx, trgl, mesh[, boundaries, ...])

Takes a triangulated surface and determine which mesh cells it intersects.

Model Utility Functions#

model_builder.add_block(cell_centers, model, ...)

Add a homogeneous block to an existing cell centered model

model_builder.create_2_layer_model(...[, ...])

Create a basic two layered model


Construct cell-centered model comprised of a block in a wholespace.


Construct cell-centered model comprised of an ellipsoid in a wholespace.


Define physical property model from scalar analytic function.


Create physical property model consisting of a set of infinite horizontal layers.

model_builder.create_random_model(shape[, ...])

Create random model by convolving a kernel with a uniformly distributed random model.

model_builder.get_indices_block(p0, p1, ...)

Get indices for cells whose centers lie inside specified block

model_builder.get_indices_polygon(mesh, pts)

Get indices for cells whose centers lie within the convex hull of a set of points.

model_builder.get_indices_sphere(center, ...)

Get indices for cells whose centers lie inside a sphere

Plotting Utility Functions#

plot2Ddata(xyz, data[, vec, nx, ny, ax, ...])

Interpolate and plot unstructured 2D data.

plot_1d_layer_model(thicknesses, values[, ...])

Plot the vertical profile for a 1D layered Earth model.

PGI Utility Classes and Functions#

WeightedGaussianMixture(n_components, mesh)

Weighted Gaussian mixture class

GaussianMixtureWithPrior(gmmref[, kappa, ...])

This class built upon the WeightedGaussianMixture, which itself built upon from the mixture.gaussian_mixture.GaussianMixture class from Scikit-Learn.


Gaussian mixture class for non-linear relationships.


Gaussian mixture class for non-linear relationships with priors.

Code Utility Functions#

Many of the functions here are used internally to SimPEG and have minimal documentation.

as_array_n_by_dim(pts, dim)

Ensures the given array will have dim columns.

call_hooks(match[, mainFirst])

Wrap a function to an instance of a class.

check_stoppers(obj, stoppers)

Check stopping rules.

create_wrapper_from_class(input_class, ...)

Create wrapper class with memory profiler.

dependent_property(name, value, children, doc)

Dependent property.

deprecate_class([removal_version, ...])

Utility function to deprecate a class

deprecate_function(new_function, old_name[, ...])

Deprecate function

deprecate_method(method, old_name[, ...])

Deprecate method

deprecate_module(old_name, new_name[, ...])

Deprecate module

deprecate_property(prop, old_name[, ...])

Deprecate property

hook(obj, method[, name, overwrite, silent])

Dynamically bind a class's method to an instance of a different class.

print_done(obj, printers[, name, pad])

Print completion of an operation.

printDone(*args, **kwargs)

printDone has been deprecated.

print_line(obj, printers[, pad])

Print line.

print_stoppers(obj, stoppers[, pad, stop, done])

Print stoppers.

print_titles(obj, printers[, name, pad])

Print titles.


Wrap a function to require a specfic attribute.

set_kwargs(obj[, ignore])

Set key word arguments for an object or throw an error if any do not exist.

validate_float(property_name, var[, ...])

Validate float property

validate_integer(property_name, var[, ...])

Validate integer property

validate_list_of_types(property_name, var, ...)

Validate list of instances of a certain class

validate_location_property(property_name, var)

Validate a location

validate_ndarray_with_shape(property_name, var)

Validate numerical array property

validate_string(property_name, var[, ...])

Validate a string property

validate_callable(property_name, obj)

Validate if an object is callable

validate_direction(property_name, obj[, dim])

Validate if an object represents a direction.

validate_active_indices(property_name, ...)

Validates an array intended to indicate a list of active indices.