simpeg.directives.UpdateSensitivityWeights#

class simpeg.directives.UpdateSensitivityWeights(every_iteration=False, threshold_value=1e-12, threshold_method='amplitude', normalization_method='maximum', **kwargs)[source]#

Bases: InversionDirective

Sensitivity weighting for linear and non-linear least-squares inverse problems.

This directive computes the root-mean squared sensitivities for the forward simulation(s) attached to the inverse problem, then truncates and scales the result to create cell weights which are applied in the regularization. The underlying theory is provided below in the Notes section.

This directive requires that the map for the regularization function is either class:simpeg.maps.Wires or class:simpeg.maps.Identity. In other words, the sensitivity weighting cannot be applied for parametric inversion. In addition, the simulation(s) connected to the inverse problem must have a getJ or getJtJdiag method.

This directive’s place in the DirectivesList must be before any directives which update the preconditioner for the inverse problem (i.e. UpdatePreconditioner), and must be before any directives that estimate the starting trade-off parameter (i.e. EstimateBeta_ByEig and EstimateBetaMaxDerivative).

Parameters:

every_iterationbool

When True, update sensitivity weighting at every model update; non-linear problems. When False, create sensitivity weights for starting model only; linear problems.

thresholdfloat

Threshold value for smallest weighting value.

threshold_method{‘amplitude’, ‘global’, ‘percentile’}

Threshold method for how threshold_value is applied:

amplitude:
the smallest root-mean squared sensitivity is a fractional percent of the largest value; must be between 0 and 1.

global:
threshold_value is added to the cell weights prior to normalization; must be greater than 0.

percentile:
the smallest root-mean squared sensitivity is set using percentile threshold; must be between 0 and 100.

normalization_method{‘maximum’, ‘min_value’, None}

Normalization method applied to sensitivity weights.

Options are:

maximum:
sensitivity weights are normalized by the largest value such that the largest weight is equal to 1.

minimum:
sensitivity weights are normalized by the smallest value, after thresholding, such that the smallest weights are equal to 1.

None:
normalization is not applied.

Attributes

`debug`	verbose.debug has been deprecated.
`dmisfit`	Data misfit associated with the directive.
`everyIter`	every_iteration.everyIter has been deprecated.
`every_iteration`	Update sensitivity weights when model is updated.
`invProb`	Inverse problem associated with the directive.
`inversion`	Inversion object associated with the directive.
`normalization`	normalization_method.normalization has been deprecated.
`normalization_method`	Normalization method applied to sensitivity weights.
`opt`	Optimization algorithm associated with the directive.
`reg`	Regularization associated with the directive.
`simulation`	Return simulation for all data misfits.
`survey`	Return survey for all data misfits
`threshold`	threshold_value.threshold has been deprecated.
`threshold_method`	Threshold method for how threshold_value is applied:
`threshold_value`	Threshold value used to set minimum weighting value.
`verbose`	Whether or not to print debugging information.

Methods

`endIter`()	Execute end of iteration.
`finish`()	Update inversion parameter(s) according to directive at end of inversion.
`initialize`()	Compute sensitivity weights upon starting the inversion.
`update`()	Update sensitivity weights
`validate`(directiveList)	Validate directive against directives list.

Notes

Let \(\mathbf{J}\) represent the Jacobian. To create sensitivity weights, root-mean squared (RMS) sensitivities \(\mathbf{s}\) are computed by summing the squares of the rows of the Jacobian:

\[\mathbf{s} = \Bigg [ \sum_i \, \mathbf{J_{i, \centerdot }}^2 \, \Bigg ]^{1/2}\]

The dynamic range of RMS sensitivities can span many orders of magnitude. When computing sensitivity weights, thresholding is generally applied to set a minimum value.

Thresholding:

If global thresholding is applied, we add a constant \(\tau\) to the RMS sensitivities:

\[\mathbf{\tilde{s}} = \mathbf{s} + \tau\]

In the case of percentile thresholding, we let \(s_{\%}\) represent a given percentile. Thresholding to set a minimum value is applied as follows:

\[\begin{split}\tilde{s}_j = \begin{cases} s_j \;\; for \;\; s_j \geq s_{\%} \\ s_{\%} \;\; for \;\; s_j < s_{\%} \end{cases}\end{split}\]

If absolute thresholding is applied, we define \(\eta\) as a fractional percent. In this case, thresholding is applied as follows:

\[\begin{split}\tilde{s}_j = \begin{cases} s_j \;\; for \;\; s_j \geq \eta s_{max} \\ \eta s_{max} \;\; for \;\; s_j < \eta s_{max} \end{cases}\end{split}\]