inversion_ideas.Flatness#

class inversion_ideas.Flatness(mesh, direction, *, active_cells=None, cell_weights=None, reference_model=None)#

Flatness regularization.

Regularize a weighted norm of a spatial derivative of the model.

Parameters:

meshdiscretize.base.BaseMesh: Mesh to use in the regularization.
direction{“x”, “y”, “z”}: Direction of the spatial derivative.
active_cells(n_cells) array or None, optional: Array full of bools that indicate the active cells in the mesh. It must have the same amount of elements as cells in the mesh.
cell_weights(n_active) array or dict of (n_active) arrays or None, optional: Array with cell weights. For multiple cell weights, pass a dictionary where keys are strings and values are the different weights arrays. If None, no cell weights are going to be used.
reference_model(n_active) array or None, optional: Array with values for the reference model.

Attributes

`cell_weights`	Regularization weights on cells.
`n_params`	Number of model parameters.
`name`	Name of the objective function.
`weights_matrix`	Diagonal matrix with the square root of cell weights averaged on faces.

n_active

Methods

`__call__`(model)	Evaluate the regularization on a given model.
`gradient`(model)	Evaluate the gradient of the objective function for a given model.
`hessian`(model)	Evaluate the hessian of the objective function for a given model.
`hessian_diagonal`(model)	Get the main diagonal of the Hessian.
`info`()	Get information about the objective function.
`set_name`(value)	Set name for the objective function.

Notes

Implement a discretized version of the smoothness regularization defined as follows, assuming that the direction of the derivative is along \(x\):

\[\phi_x(\mathbf{m}) = \int_\Omega w(\mathbf{r}) \lvert \frac{\partial m}{\partial x} - \frac{\partial m^\text{ref}}{\partial x} \rvert^2 \text{d}\mathbf{r},\]

where \(w(\mathbf{r})\) is the value of weights on the point \(\mathbf{r}\), \(m\) and \(m^\text{ref}\) are the model and reference model, respectively.

When discretizing it into the mesh, the smallness regularization can be expressed by:

\[\phi_s(\mathbf{m}) = \lVert \mathbf{W}^f \mathbf{V}^f \mathbf{G}_x (\mathbf{m} - \mathbf{m}^\text{ref}) \rVert^2,\]

where \(\mathbf{W}^f\) are the square root of cell weights averaged on faces, \(\mathbf{V}^f\) are the square root of cell volumes averaged on faces, \(\mathbf{G}_x\) is the partial cell gradient operator along the \(x\) direction, \(\mathbf{m} = [m_1, \dots, m_M]\) and \(\mathbf{m}^\text{ref} = [m_1^\text{ref}, \dots, m_M^\text{ref}]\) are the model and reference model vectors, respectively.

Important

After applying the \(\mathbf{G}_x\) to the model, the partial derivatives are located on the center of the faces. For this reason we need to average the cell volumes and the cell weights to faces before using them in the regularization.

Attributes#

Flatness.cell_weights#: Regularization weights on cells.

Flatness.n_active#

Flatness.n_params#

Flatness.name#: Name of the objective function.

Flatness.weights_matrix#: Diagonal matrix with the square root of cell weights averaged on faces.

Flatness.active_cells#

Methods#

Methods documentation

Flatness.__call__(model)#

Evaluate the regularization on a given model.

Parameters:

model(n_params) array: Array with model values.

Flatness.gradient(model)#

Evaluate the gradient of the objective function for a given model.

Parameters:

model(n_params) array: Array with model values.

Returns:

(n_params,) array: Gradient vector for the given model.

Flatness.hessian(model)#

Evaluate the hessian of the objective function for a given model.

Parameters:

model(n_params) array: Array with model values.

Returns:

(n_params, n_params) array or LinearOperator: 2D array or LinearOperator that represents the Hessian matrix of the objective funciton, or an approximated version of it.

Flatness.hessian_diagonal(model)#

Get the main diagonal of the Hessian.

Parameters:

model(n_params) array: Array with model values.

Returns:

(n_params,) array: Array containing the diagonal of the Hessian.

Flatness.info()#: Get information about the objective function.

Flatness.set_name(value)#: Set name for the objective function.