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.

Counter Utility Functions#


Class for recording iterations and operation times.





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#


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


Compute coterminal angle

define_plane_from_points(xyz1, xyz2, xyz3)

Compute constants defining a plane from a set of points.

eigenvalue_by_power_iteration(combo_objfct, ...)

Estimate largest eigenvalue in absolute value using power iteration.

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

Estimate the diagonal of a matrix.


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


Return unique rows, row indices and inverse indices.

Mesh Utility Functions#

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

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

Model Utility Functions#

depth_weighting(mesh, reference_locs[, ...])

Construct diagonal elements of a depth weighting matrix

surface2ind_topo(mesh, topo[, gridLoc, ...])

Get indices of active cells from topography.

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.

call_hooks(match[, mainFirst])

Wrap a function to an instance of a class.

check_stoppers(obj, stoppers)

Check stopping rules.

mem_profile_class(input_class, *args)

Creates a new class from the target class with memory profiled methods.

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.

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.