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

Counter()	Class for recording iterations and operation times.
count(f)	Count function (DOCSTRING INCOMPLETE)
timeIt(f)	Timing function (DOCSTRING INCOMPLETE)

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.
io_utils.read_gg3d_ubc(obs_file)	Read UBC-GIF GG3D formatted survey or data files.
io_utils.read_grav3d_ubc(obs_file)	Read UBC-GIF GRAV3D formatted survey or data files.
io_utils.read_mag3d_ubc(obs_file)	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

av(n)	Create 1D averaging operator from nodes to cell-centers.
av_extrap(n)	Create 1D averaging operator from cell-centers to nodes.
cartesian2spherical(m)	Converts a set of 3D vectors from Cartesian to spherical coordinates.
coterminal(theta)	Compute coterminal angle
ddx(n)	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.
sdiag(v)	Generate sparse diagonal matrix from a vector.
sdinv(M)	Return inverse of a sparse diagonal matrix
speye(n)	Generate sparse identity matrix.
spherical2cartesian(m)	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.
unique_rows(M)	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_widths(value)	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
model_builder.create_block_in_wholespace(...)	Construct cell-centered model comprised of a block in a wholespace.
model_builder.create_ellipse_in_wholespace(...)	Construct cell-centered model comprised of an ellipsoid in a wholespace.
model_builder.create_from_function(...)	Define physical property model from scalar analytic function.
model_builder.create_layers_model(...)	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.
GaussianMixtureWithNonlinearRelationships(mesh)	Gaussian mixture class for non-linear relationships.
GaussianMixtureWithNonlinearRelationshipsWithPrior(gmmref)	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.
requires(var)	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.