SimPEG.regularization.SmoothnessFirstOrder

class SimPEG.regularization.SmoothnessFirstOrder(mesh, orientation='x', reference_model_in_smooth=False, **kwargs)

Bases: BaseRegularization

First-order smoothness least-squares regularization.

SmoothnessFirstOrder regularization is used to ensure that values in the recovered model are smooth along a specified direction. When a reference model is included, the regularization preserves gradients/interfaces within the reference model along the direction specified (x, y or z). Optionally, custom cell weights can be used to control the degree of smoothness being enforced throughout different regions the model.

See the Notes section below for a comprehensive description.

Parameters:

meshdiscretize.base.BaseMesh mesh

The mesh on which the regularization is discretized.

orientation{‘x’, ‘y’, ‘z’}

The direction along which smoothness is enforced.

active_cellsNone, (n_cells, ) numpy.ndarray of bool

Boolean array defining the set of RegularizationMesh cells that are active in the inversion. If None, all cells are active.

mappingNone, SimPEG.maps.BaseMap

The mapping from the model parameters to the active cells in the inversion. If None, the mapping is the identity map.

reference_modelNone, (n_param, ) numpy.ndarray

Reference model. If None, the reference model in the inversion is set to the starting model. To include the reference model in the regularization, the reference_model_in_smooth property must be set to True.

reference_model_in_smoothbool, optional

Whether to include the reference model in the smoothness regularization.

unitsNone, str

Units for the model parameters. Some regularization classes behave differently depending on the units; e.g. ‘radian’.

weightsNone, dict

Custom weights for the least-squares function. Each key points to a numpy.ndarray that is defined on the regularization.RegularizationMesh. A (n_cells, ) numpy.ndarray is used to define weights at cell centers, which are averaged to the appropriate faces internally when weighting is applied. A (n_faces, ) numpy.ndarray is used to define weights directly on the faces specified by the orientation input argument.

Notes

We define the regularization function (objective function) for first-order smoothness along the x-direction as:

\[\phi (m) = \int_\Omega \, w(r) \, \bigg [ \frac{\partial m}{\partial x} \bigg ]^2 \, dv\]

where \(m(r)\) is the model and \(w(r)\) is a user-defined weighting function.

For implementation within SimPEG, the regularization function and its variables must be discretized onto a mesh. The discretized approximation for the regularization function (objective function) is expressed in linear form as:

\[\phi (\mathbf{m}) = \sum_i \tilde{w}_i \, \bigg | \, \frac{\partial m_i}{\partial x} \, \bigg |^2\]

where \(m_i \in \mathbf{m}\) are the discrete model parameter values defined on the mesh and \(\tilde{w}_i \in \mathbf{\tilde{w}}\) are amalgamated weighting constants that 1) account for cell dimensions in the discretization and 2) apply any user-defined weighting. This is equivalent to an objective function of the form:

\[\phi (\mathbf{m}) = \Big \| \mathbf{W \, G_x m } \, \Big \|^2\]

where

• \(\mathbf{G_x}\) is the partial cell gradient operator along the x-direction, and

• \(\mathbf{W}\) is the weighting matrix.

Note that since \(\mathbf{G_x}\) maps from cell centers to x-faces, \(\mathbf{W}\) is an operator that acts on variables living on x-faces.

Reference model in smoothness:

Gradients/interfaces within a discrete reference model \(\mathbf{m}^{(ref)}\) can be preserved by including the reference model the regularization. In this case, the objective function becomes:

\[\phi (\mathbf{m}) = \Big \| \mathbf{W G_x} \big [ \mathbf{m} - \mathbf{m}^{(ref)} \big ] \Big \|^2\]

This functionality is used by setting a reference model with the reference_model property, and by setting the reference_model_in_smooth parameter to True.

Custom weights and the weighting matrix:

Let \(\mathbf{w_1, \; w_2, \; w_3, \; ...}\) each represent an optional set of custom weights defined on the faces specified by the orientation property; i.e. x-faces for smoothness along the x-direction. Each set of weights were either defined directly on the faces or have been averaged from cell centers.

The weighting applied within the objective function is given by:

\[\mathbf{\tilde{w}} = \mathbf{v_x} \odot \prod_j \mathbf{w_j}\]

where \(\mathbf{v_x}\) are cell volumes projected to x-faces. The weighting matrix is given by:

\[\mathbf{W} = \textrm{diag} \Big ( \, \mathbf{\tilde{w}}^{1/2} \Big )\]

Each set of custom weights is stored within a dict as an numpy.ndarray. A (n_cells, ) numpy.ndarray is used to define weights at cell centers, which are averaged to the appropriate faces internally when weighting is applied. A (n_faces, ) numpy.ndarray is used to define weights directly on the faces specified by the orientation input argument. The weights can be set all at once during instantiation with the weights keyword argument as follows:

>>> array_1 = np.ones(mesh.n_cells)  # weights at cell centers
>>> array_2 = np.ones(mesh.n_faces_x)  # weights directly on x-faces
>>> reg = SmoothnessFirstOrder(
>>>     mesh, orientation='x', weights={'weights_1': array_1, 'weights_2': array_2}
>>> )

or set after instantiation using the set_weights method:

>>> reg.set_weights(weights_1=array_1, weights_2=array_2)

The default weights that account for cell dimensions in the regularization are accessed via:

>>> reg.get_weights('volume')

Attributes

W	Weighting matrix.
active_cells	Active cells defined on the regularization mesh.
cell_gradient	Partial cell gradient operator.
cell_weights	Deprecated property for 'volume' and user defined weights.
indActive	active_cells.indActive has been deprecated.
mapping	Mapping from the inversion model parameters to the regularization mesh.
model	The model parameters.
mref	reference_model.mref has been deprecated.
nP	Number of model parameters.
orientation	Direction along which smoothness is enforced.
parent	The parent objective function
reference_model	Reference model.
regmesh	regularization_mesh.regmesh has been deprecated.
regularization_mesh	Regularization mesh.
units	Units for the model parameters.
weights_keys	Return the keys for the existing cell weights

reference_model_in_smooth

Methods

__call__(m)	Evaluate the regularization function for the model provided.
deriv(m)	Gradient of the regularization function evaluated for the model provided.
deriv2(m[, v])	Hessian of the regularization function evaluated for the model provided.
f_m(m)	Evaluate the regularization kernel function.
f_m_deriv(m)	Derivative of the regularization kernel function.
get_weights(key)	Cell weights for a given key.
map_class	alias of IdentityMap
remove_weights(key)	Removes the weights for the key provided.
set_weights(**weights)	Adds (or updates) the specified weights to the regularization.
test([x, num])	Run a convergence test on both the first and second derivatives.