Regularization (fatiando.inversion.regularization)¶

Ready made classes for regularization.

Each class represents a regularizing function. They can be used by adding them to a Misfit derivative (all inversions in Fatiando are derived from Misfit). The regularization parameter is set by multiplying the regularization instance by a scalar, e.g., solver = misfit + 0.1*regularization.

See fatiando.gravmag.eqlayer.EQLGravity for an example.

List of classes

• Damping: Damping regularization (or 0th order Tikhonov regularization)
• Smoothness: Generic smoothness regularization (or 1st order Tikhonov regularization). Requires a finite difference matrix to specify the parameter derivatives to minimize.
• Smoothness1D: Smoothness for 1D problems. Automatically builds a finite difference matrix based on the number of parameters
• Smoothness2D: Smoothness for 2D grid based problems. Automatically builds a finite difference matrix of derivatives in the two spacial dimensions based on the shape of the parameter grid
• TotalVariation: Generic total variation regularization (enforces sharpness of the solution). Requires a finite difference matrix to specify the parameter derivatives.
• TotalVariation1D: Total variation for 1D problems. Similar to Smoothness1D
• TotalVariation2D: Total variation for 2D grid based problems. Similar to Smoothness2D

class fatiando.inversion.regularization.Damping(nparams)[source]¶

Bases: fatiando.inversion.regularization.Regularization

Damping (0th order Tikhonov) regularization.

Imposes the minimum norm of the parameter vector.

The regularizing function if of the form

\[\theta^{NM}(\bar{p}) = \bar{p}^T\bar{p}\]

Its gradient and Hessian matrices are, respectively,

\[\bar{\nabla}\theta^{NM}(\bar{p}) = 2\bar{\bar{I}}\bar{p}\]

\[\bar{\bar{\nabla}}\theta^{NM}(\bar{p}) = 2\bar{\bar{I}}\]

Parameters:

• nparams

  : int

  The number of parameter

Examples:

>>> import numpy
>>> damp = Damping(3)
>>> p = numpy.array([0, 0, 0])
>>> damp.value(p)
0.0
>>> damp.hessian(p).todense()
matrix([[ 2.,  0.,  0.],
        [ 0.,  2.,  0.],
        [ 0.,  0.,  2.]])
>>> damp.gradient(p)
array([ 0.,  0.,  0.])
>>> p = numpy.array([1, 0, 0])
>>> damp.value(p)
1.0
>>> damp.hessian(p).todense()
matrix([[ 2.,  0.,  0.],
        [ 0.,  2.,  0.],
        [ 0.,  0.,  2.]])
>>> damp.gradient(p)
array([ 2.,  0.,  0.])

The Hessian matrix is cached so that it is only generated on the first call to damp.hessian (unlike the gradient, which is calculated every time).

>>> damp.hessian(p) is damp.hessian(p)
True
>>> damp.gradient(p) is damp.gradient(p)
False

copy(deep=False)¶

Make a copy of me together with all the cached methods.

gradient(p)[source]¶

Calculate the gradient vector.

Parameters:

• p

  : 1d-array or None

  The parameter vector. If None, will return 0.

Returns:

• gradient

  : 1d-array

  The gradient

hessian(p)[source]¶

Calculate the Hessian matrix.

Parameters:

• p

  : 1d-array

  The parameter vector

Returns:

• hessian

  : 2d-array

  The Hessian

regul_param¶

The regularization parameter (scale factor) for the objetive function.

Defaults to 1.

value(p)[source]¶

Calculate the value of this function.

Parameters:

• p

  : 1d-array

  The parameter vector

Returns:

• value

  : float

  The value of this function evaluated at p

class fatiando.inversion.regularization.Smoothness(fdmat)[source]¶

Bases: fatiando.inversion.regularization.Regularization

Smoothness (1st order Tikhonov) regularization.

Imposes that adjacent parameters have values close to each other.

The regularizing function if of the form

\[\theta^{SV}(\bar{p}) = \bar{p}^T \bar{\bar{R}}^T \bar{\bar{R}}\bar{p}\]

Its gradient and Hessian matrices are, respectively,

\[\bar{\nabla}\theta^{SV}(\bar{p}) = 2\bar{\bar{R}}^T \bar{\bar{R}}\bar{p}\]

\[\bar{\bar{\nabla}}\theta^{SV}(\bar{p}) = 2\bar{\bar{R}}^T \bar{\bar{R}}\]

in which matrix \(\bar{\bar{R}}\) is a finite difference matrix. It represents the differences between one parameter and another and is what indicates what adjacent means.

Parameters:

• fdmat

  : 2d-array or sparse matrix

  The finite difference matrix

Examples:

>>> import numpy as np
>>> fd = np.array([[1, -1, 0],
...                [0, 1, -1]])
>>> smooth = Smoothness(fd)
>>> p = np.array([0, 0, 0])
>>> smooth.value(p)
0.0
>>> smooth.gradient(p)
array([0, 0, 0])
>>> smooth.hessian(p)
array([[ 2, -2,  0],
       [-2,  4, -2],
       [ 0, -2,  2]])
>>> p = np.array([1, 0, 1])
>>> smooth.value(p)
2.0
>>> smooth.gradient(p)
array([ 2, -4,  2])
>>> smooth.hessian(p)
array([[ 2, -2,  0],
       [-2,  4, -2],
       [ 0, -2,  2]])

The Hessian matrix is cached so that it is only generated on the first call to hessian (unlike the gradient, which is calculated every time).

>>> smooth.hessian(p) is smooth.hessian(p)
True
>>> smooth.gradient(p) is smooth.gradient(p)
False

copy(deep=False)¶

Make a copy of me together with all the cached methods.

gradient(p)[source]¶

Calculate the gradient vector.

Parameters:

• p

  : 1d-array or None

  The parameter vector. If None, will return 0.

Returns:

• gradient

  : 1d-array

  The gradient

hessian(p)[source]¶

Calculate the Hessian matrix.

Parameters:

• p

  : 1d-array

  The parameter vector

Returns:

• hessian

  : 2d-array

  The Hessian

regul_param¶

The regularization parameter (scale factor) for the objetive function.

Defaults to 1.

value(p)[source]¶

Calculate the value of this function.

Parameters:

• p

  : 1d-array

  The parameter vector

Returns:

• value

  : float

  The value of this function evaluated at p

class fatiando.inversion.regularization.Smoothness1D(npoints)[source]¶

Bases: fatiando.inversion.regularization.Smoothness

Smoothness regularization for 1D problems.

Extends the generic Smoothness class by automatically building the finite difference matrix.

Parameters:

• npoints

  : int

  The number of parameters

Examples:

>>> import numpy as np
>>> s = Smoothness1D(3)
>>> p = np.array([0, 0, 0])
>>> s.value(p)
0.0
>>> s.gradient(p)
array([0, 0, 0])
>>> s.hessian(p).todense()
matrix([[ 2, -2,  0],
        [-2,  4, -2],
        [ 0, -2,  2]])
>>> p = np.array([1, 0, 1])
>>> s.value(p)
2.0
>>> s.gradient(p)
array([ 2, -4,  2])
>>> s.hessian(p).todense()
matrix([[ 2, -2,  0],
        [-2,  4, -2],
        [ 0, -2,  2]])

copy(deep=False)¶

Make a copy of me together with all the cached methods.

gradient(p)¶

Calculate the gradient vector.

Parameters:

• p

  : 1d-array or None

  The parameter vector. If None, will return 0.

Returns:

• gradient

  : 1d-array

  The gradient

hessian(p)¶

Calculate the Hessian matrix.

Parameters:

• p

  : 1d-array

  The parameter vector

Returns:

• hessian

  : 2d-array

  The Hessian

regul_param¶

The regularization parameter (scale factor) for the objetive function.

Defaults to 1.

value(p)¶

Calculate the value of this function.

Parameters:

• p

  : 1d-array

  The parameter vector

Returns:

• value

  : float

  The value of this function evaluated at p

class fatiando.inversion.regularization.Smoothness2D(shape)[source]¶

Bases: fatiando.inversion.regularization.Smoothness

Smoothness regularization for 2D problems.

Extends the generic Smoothness class by automatically building the finite difference matrix.

Parameters:

• shape

  : tuple = (ny, nx)

  The shape of the parameter grid. Number of parameters in the y and x (or z and x, time and offset, etc) dimensions.

Examples:

>>> import numpy as np
>>> s = Smoothness2D((2, 2))
>>> p = np.array([[0, 0],
...               [0, 0]]).ravel()
>>> s.value(p)
0.0
>>> s.gradient(p)
array([0, 0, 0, 0])
>>> s.hessian(p).todense()
matrix([[ 4, -2, -2,  0],
        [-2,  4,  0, -2],
        [-2,  0,  4, -2],
        [ 0, -2, -2,  4]])
>>> p = np.array([[1, 0],
...               [2, 3]]).ravel()
>>> s.value(p)
12.0
>>> s.gradient(p)
array([ 0, -8,  0,  8])
>>> s.hessian(p).todense()
matrix([[ 4, -2, -2,  0],
        [-2,  4,  0, -2],
        [-2,  0,  4, -2],
        [ 0, -2, -2,  4]])

copy(deep=False)¶

Make a copy of me together with all the cached methods.

gradient(p)¶

Calculate the gradient vector.

Parameters:

• p

  : 1d-array or None

  The parameter vector. If None, will return 0.

Returns:

• gradient

  : 1d-array

  The gradient

hessian(p)¶

Calculate the Hessian matrix.

Parameters:

• p

  : 1d-array

  The parameter vector

Returns:

• hessian

  : 2d-array

  The Hessian

regul_param¶

The regularization parameter (scale factor) for the objetive function.

Defaults to 1.

value(p)¶

Calculate the value of this function.

Parameters:

• p

  : 1d-array

  The parameter vector

Returns:

• value

  : float

  The value of this function evaluated at p

class fatiando.inversion.regularization.TotalVariation(beta, fdmat)[source]¶

Bases: fatiando.inversion.regularization.Regularization

Total variation regularization.

Imposes that adjacent parameters have a few sharp transitions.

The regularizing function if of the form

\[\theta^{VT}(\bar{p}) = \sum\limits_{k=1}^L |v_k|\]

where vector \(\bar{v} = \bar{\bar{R}}\bar{p}\). See Smoothness for the definition of the \(\bar{\bar{R}}\) matrix.

This functions is not differentiable at the null vector, so the following form is used to calculate the gradient and Hessian

\[\theta^{VT}(\bar{p}) \approx \theta^{VT}_\beta(\bar{p}) = \sum\limits_{k=1}^L \sqrt{v_k^2 + \beta}\]

Its gradient and Hessian matrices are, respectively,

\[\bar{\nabla}\theta^{VT}_\beta(\bar{p}) = \bar{\bar{R}}^T \bar{q}(\bar{p})\]

\[\bar{\bar{\nabla}}\theta^{VT}_\beta(\bar{p}) = \bar{\bar{R}}^T \bar{\bar{Q}}(\bar{p})\bar{\bar{R}}\]

and

\[\begin{split}\bar{q}(\bar{p}) = \begin{bmatrix} \dfrac{v_1}{\sqrt{v_1^2 + \beta}} \\ \dfrac{v_2}{\sqrt{v_2^2 + \beta}} \\ \vdots \\ \dfrac{v_L}{\sqrt{v_L^2 + \beta}} \end{bmatrix}\end{split}\]

\[\begin{split}\bar{\bar{Q}}(\bar{p}) = \begin{bmatrix} \dfrac{\beta}{(v_1^2 + \beta)^{\frac{3}{2}}} & 0 & \ldots & 0 \\ 0 & \dfrac{\beta}{(v_2^2 + \beta)^{\frac{3}{2}}} & \ldots & 0 \\ \vdots & \vdots & \ddots & \vdots \\ 0 & 0 & \ldots & \dfrac{\beta}{(v_L^2 + \beta)^{\frac{3}{2}}} \end{bmatrix}\end{split}\]

Parameters:

• beta

  : float

  The beta parameter for the differentiable approximation. The larger it is, the closer total variation is to Smoothness. Should be a small, positive value.

• fdmat

  : 2d-array or sparse matrix

  The finite difference matrix

copy(deep=False)¶

Make a copy of me together with all the cached methods.

gradient(p)[source]¶

Calculate the gradient vector.

Parameters:

• p

  : 1d-array

  The parameter vector.

Returns:

• gradient

  : 1d-array

  The gradient

hessian(p)[source]¶

Calculate the Hessian matrix.

Parameters:

• p

  : 1d-array

  The parameter vector

Returns:

• hessian

  : 2d-array

  The Hessian

regul_param¶

The regularization parameter (scale factor) for the objetive function.

Defaults to 1.

value(p)[source]¶

Calculate the value of this function.

Parameters:

• p

  : 1d-array

  The parameter vector

Returns:

• value

  : float

  The value of this function evaluated at p

class fatiando.inversion.regularization.TotalVariation1D(beta, npoints)[source]¶

Bases: fatiando.inversion.regularization.TotalVariation

Total variation regularization for 1D problems.

Extends the generic TotalVariation class by automatically building the finite difference matrix.

Parameters:

• beta

  : float

  The beta parameter for the differentiable approximation. The larger it is, the closer total variation is to Smoothness. Should be a small, positive value.

• npoints

  : int

  The number of parameters

copy(deep=False)¶

Make a copy of me together with all the cached methods.

gradient(p)¶

Calculate the gradient vector.

Parameters:

• p

  : 1d-array

  The parameter vector.

Returns:

• gradient

  : 1d-array

  The gradient

hessian(p)¶

Calculate the Hessian matrix.

Parameters:

• p

  : 1d-array

  The parameter vector

Returns:

• hessian

  : 2d-array

  The Hessian

regul_param¶

The regularization parameter (scale factor) for the objetive function.

Defaults to 1.

value(p)¶

Calculate the value of this function.

Parameters:

• p

  : 1d-array

  The parameter vector

Returns:

• value

  : float

  The value of this function evaluated at p

class fatiando.inversion.regularization.TotalVariation2D(beta, shape)[source]¶

Bases: fatiando.inversion.regularization.TotalVariation

Total variation regularization for 2D problems.

Extends the generic TotalVariation class by automatically building the finite difference matrix.

Parameters:

• beta

  : float

  The beta parameter for the differentiable approximation. The larger it is, the closer total variation is to Smoothness. Should be a small, positive value.

• shape

  : tuple = (ny, nx)

  The shape of the parameter grid. Number of parameters in the y and x (or z and x, time and offset, etc) dimensions.

copy(deep=False)¶

Make a copy of me together with all the cached methods.

gradient(p)¶

Calculate the gradient vector.

Parameters:

• p

  : 1d-array

  The parameter vector.

Returns:

• gradient

  : 1d-array

  The gradient

hessian(p)¶

Calculate the Hessian matrix.

Parameters:

• p

  : 1d-array

  The parameter vector

Returns:

• hessian

  : 2d-array

  The Hessian

regul_param¶

The regularization parameter (scale factor) for the objetive function.

Defaults to 1.

value(p)¶

Calculate the value of this function.

Parameters:

• p

  : 1d-array

  The parameter vector

Returns:

• value

  : float

  The value of this function evaluated at p