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.

Logger#

Function to fetch the SimPEG logger. It can be used to stream messages to the logger, and to temporarily adjust its configuration (e.g. change log level).

get_logger()

Get the default event logger.

Counter Utility Functions#

Counter()

Class for recording iterations and operation times.

count(f)

Count function (DOCSTRING INCOMPLETE)

timeIt(f)

Timing function (DOCSTRING INCOMPLETE)

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#

cartesian2spherical(m)

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

coterminal(theta)

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.

spherical2cartesian(m)

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

unique_rows(M)

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

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

Construct diagonal elements of a distance weighting matrix

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.

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.

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.

Solver utilities#

Functions to get and set the default solver meant to be used in PDE simulations.

get_default_solver([warn])

Return the default solver used by simpeg.

set_default_solver(solver_class)

Set the default solver used by simpeg.

Custom warnings#

List of custom warnings used in SimPEG.

PerformanceWarning

Warning raised when there is a possible performance impact.