simpeg.regularization.CrossReferenceRegularization

class simpeg.regularization.CrossReferenceRegularization(mesh, ref_dir, active_cells=None, mapping=None, weights=None, **kwargs)

Bases: Smallness, BaseVectorRegularization

Cross reference regularization for models representing vector quantities.

CrossReferenceRegularization encourages the vectors in the recovered model to be oriented in the same directions as the vector in a reference vector model. The regularization function (objective function) constrains the inversion by penalizing the magnitude of the-cross product of the vector model with a reference vector model. The cross product, and therefore the objective function, is minimized when vectors in the model and reference vector model are parallel (or anti-parallel) to each other. And it is maximized when the vectors are perpendicular to each other. The reference vector model can be set using a single vector, or by defining a vector for each mesh cell.

Parameters:

meshdiscretize.base.BaseMesh, RegularizationMesh

The mesh defining the model discretization.

ref_dir(mesh.dim,) array_like or (mesh.dim, n_active) array_like

The reference direction model. This can be either a constant vector applied to every model cell, or different for every active model cell.

active_cellsindex_array, optional

Boolean array or an array of active indices indicating the active cells of the inversion domain mesh.

mappingsimpeg.maps.IdentityMap, optional

An optional linear mapping that would go from the model space to the space where the cross-product is enforced.

weightsdict of [str: array_like], optional

Any cell based weights for the regularization. Note if given a weight that is (n_cells, dim), meaning it is dependent on the vector component, it will compute the geometric mean of the component weights per cell and use that as a weight.

**kwargs

Arguments passed on to the parent classes: Smallness and BaseVectorRegularization.

Notes

Consider the case where the model is a vector quantity \(\vec{m}(r)\). The regularization function (objective function) for cross-reference regularization is given by:

\[\phi (\vec{m}) = \int_\Omega \, \vec{w}(r) \, \cdot \, \Big [ \vec{m}(r) \, \times \, \vec{m}^{(ref)}(r) \Big ]^2 \, dv\]

where \(\vec{m}^{(ref)}(r)\) is the reference model vector and \(\vec{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 given by:

\[\phi (\vec{m}) \approx \sum_i \tilde{w}_i \, \cdot \, \Big | \vec{m}_i \, \times \, \vec{m}_i^{(ref)} \Big |^2\]

where \(\tilde{m}_i \in \mathbf{m}\) are the model vectors at cell centers 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.

In practice, the model is a discrete vector of the form:

\[\begin{split}\mathbf{m} = \begin{bmatrix} \mathbf{m_p} \\ \mathbf{m_s} \\ \mathbf{m_t} \end{bmatrix}\end{split}\]

where \(\mathbf{m_p}\), \(\mathbf{m_s}\) and \(\mathbf{m_t}\) represent vector components in the primary, secondary and tertiary directions at cell centers, respectively. The cross product between \(\mathbf{m}\) and a similar reference vector \(\mathbf{m^{(ref)}}\) (set with ref_dir) is a linear operation of the form:

\[\begin{split}\mathbf{m} \times \mathbf{m^{ref}} = \mathbf{X m} = \begin{bmatrix} \mathbf{0} & -\boldsymbol{\Lambda_s} & \boldsymbol{\Lambda_t} \\ \boldsymbol{\Lambda_p} & \mathbf{0} & -\boldsymbol{\Lambda_t} \\ -\boldsymbol{\Lambda_p} & \boldsymbol{\Lambda_s} & \mathbf{0} \end{bmatrix} \! \begin{bmatrix} \mathbf{m_p} \\ \mathbf{m_s} \\ \mathbf{m_t} \end{bmatrix}\end{split}\]

where \(\mathbf{X}\) is a linear operator that applies the cross-product on \(\mathbf{m}\), \(\mathbf{W}\) is the weighting matrix, and:

\[\boldsymbol{\Lambda_j} = \textrm{diag} \Big ( \mathbf{m_j^{(ref)}} \Big ) \;\;\;\; \textrm{for} \; j=p,s,t\]

The discrete regularization function in linear form can ultimately be expressed as:

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

Custom weights and the weighting matrix:

Let \(\mathbf{w_1, \; w_2, \; w_3, \; ...}\) each represent an optional set of custom cell weights. Each individual set of cell weights acts independently on the the directional components of the cross-product and is a discrete vector of the form:

\[\begin{split}\mathbf{w_j} = \begin{bmatrix} \mathbf{w_p} \\ \mathbf{w_s} \\ \mathbf{w_t} \end{bmatrix}\end{split}\]

The weighting applied within the objective function is given by:

\[\mathbf{\tilde{w}} = \big ( \mathbf{e_3 \otimes v} ) \odot \prod_j \mathbf{w_j}\]

where

• \(\mathbf{e_3}\) is a vector of ones of length 3,

• \(\otimes\) is the Kronecker product, and

• \(\mathbf{v}\) are the cell volumes.

The weighting matrix used to apply the weights in the regularization function is given by:

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

Each set of custom cell weights is stored within a dict as a list of (n_cells, ) numpy.ndarray. The weights can be set all at once during instantiation with the weights keyword argument as follows:

>>> reg = CrossReferenceRegularization(
>>>     mesh, weights={'weights_1': array_1, 'weights_2': array_2}
>>> )

where array_1 and array_2 are (n_cells, dim) numpy.ndarray. Weights can also be 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_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.
n_comp	Number of components in the model.
parent	The parent objective function
ref_dir	The reference direction model.
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

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, random_seed])	Run a convergence test on both the first and second derivatives.