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 determines which mesh cells it intersects.
`get_discrete_topography`(mesh, active_cells)	Generate discrete topography locations from mesh and active cells.
`shift_to_discrete_topography`(mesh, pts, ...)	Shift locations relative to discrete surface topography.

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.

`BreakingChangeWarning`	Warning to let users know about a breaking change that was introduced.
`PerformanceWarning`	Warning raised when there is a possible performance impact.

Utility Classes and Functions (simpeg.utils)#