Mondaic

salvus.opt.regularization

salvus.opt.regularization salvus opt regularization

Explicit regularization terms for the inversion.

Each term computes a model dependent penalty and its gradient, optionally relative to a reference model and with scalar or point-wise weights.

As elsewhere in SalvusOpt, gradients are densities with respect to the inner product of the model class, i.e., gradient.dot(dm) is the directional derivative. This makes them additive to the misfit gradient.

The terms acting on spatial derivatives support UnstructuredModel only. They treat every mesh point as a single unknown, so their gradients are continuous across element boundaries.

Classes

FirstOrderTikhonov

class FirstOrderTikhonov(
    salvus.opt.regularization._FirstDerivativeRegularization
):
    def __init__(
        self,
        weight: types.float_ | ModelType = 1.0,
        reference_model: ModelType | None = None,
    ) -> None: ...

First order Tikhonov regularization, i.e., smoothing.

Penalizes the deviation d = m - m_ref as phi = 0.5 * integral W * |grad d| ** 2 dV. Constant models are not penalized.

Parameters
  • weight types.float_ | ModelType — Non-negative scalar, or an UnstructuredModel with non-negative point-wise weights for every parameter.
  • reference_model ModelType | None — Optional model the penalty is relative to.
Methods
compute_gradient()
def compute_gradient(
    self, model: ModelType, name: str | None = None
) -> ModelType: ...

Compute the gradient of the regularization term.

Parameters
  • model ModelType — The model to evaluate the gradient for.
  • name str | None — Optional name of the resulting gradient model.
Returns ModelType — The gradient as a model of the same type as the input.
compute_regularization()
def compute_regularization(self, model: ModelType) -> float: ...

Compute the value of the regularization term.

Parameters
  • model ModelType — The model to evaluate the penalty for.
Returns float — The value of the penalty.
compute_regularization_and_gradient()
def compute_regularization_and_gradient(
    self, model: ModelType, name: str | None = None
) -> tuple[float, ModelType]: ...

Compute the value and the gradient of the regularization term.

Cheaper than computing them separately.

Parameters
  • model ModelType — The model to evaluate the penalty for.
  • name str | None — Optional name of the resulting gradient model.
Returns tuple[float, ModelType] — A tuple of the value of the penalty and its gradient.

Regularization

class Regularization(typing.Generic):
    def __init__(
        self,
        weight: types.float_ | ModelType = 1.0,
        reference_model: ModelType | None = None,
    ) -> None: ...

Abstract base class for explicit regularization terms.

Parameters
  • weight types.float_ | ModelType — Non-negative scalar, or a model with non-negative point-wise weights for every parameter.
  • reference_model ModelType | None — Optional model the penalty is relative to.
Methods
compute_gradient()
def compute_gradient(
    self, model: ModelType, name: str | None = None
) -> ModelType: ...

Compute the gradient of the regularization term.

Parameters
  • model ModelType — The model to evaluate the gradient for.
  • name str | None — Optional name of the resulting gradient model.
Returns ModelType — The gradient as a model of the same type as the input.
compute_regularization()
def compute_regularization(self, model: ModelType) -> float: ...

Compute the value of the regularization term.

Parameters
  • model ModelType — The model to evaluate the penalty for.
Returns float — The value of the penalty.
compute_regularization_and_gradient()
def compute_regularization_and_gradient(
    self, model: ModelType, name: str | None = None
) -> tuple[float, ModelType]: ...

Compute the value and the gradient of the regularization term.

Cheaper than computing them separately.

Parameters
  • model ModelType — The model to evaluate the penalty for.
  • name str | None — Optional name of the resulting gradient model.
Returns tuple[float, ModelType] — A tuple of the value of the penalty and its gradient.

SecondOrderTikhonov

class SecondOrderTikhonov(
    salvus.opt.regularization._GradientBasedRegularization
):
    def __init__(
        self,
        weight: types.float_ | ModelType = 1.0,
        reference_model: ModelType | None = None,
    ) -> None: ...

Second order Tikhonov regularization, i.e., curvature penalty.

Penalizes the deviation d = m - m_ref as phi = 0.5 * integral W * |grad(P grad d)| ** 2 dV with the Frobenius norm. P averages the gradient per mesh point to make it continuous, so that kinks at element boundaries are penalized as well. Constant and linear models are not penalized.

Parameters
  • weight types.float_ | ModelType — Non-negative scalar, or an UnstructuredModel with non-negative point-wise weights for every parameter.
  • reference_model ModelType | None — Optional model the penalty is relative to.
Methods
compute_gradient()
def compute_gradient(
    self, model: ModelType, name: str | None = None
) -> ModelType: ...

Compute the gradient of the regularization term.

Parameters
  • model ModelType — The model to evaluate the gradient for.
  • name str | None — Optional name of the resulting gradient model.
Returns ModelType — The gradient as a model of the same type as the input.
compute_regularization()
def compute_regularization(self, model: ModelType) -> float: ...

Compute the value of the regularization term.

Parameters
  • model ModelType — The model to evaluate the penalty for.
Returns float — The value of the penalty.
compute_regularization_and_gradient()
def compute_regularization_and_gradient(
    self, model: ModelType, name: str | None = None
) -> tuple[float, ModelType]: ...

Compute the value and the gradient of the regularization term.

Cheaper than computing them separately.

Parameters
  • model ModelType — The model to evaluate the penalty for.
  • name str | None — Optional name of the resulting gradient model.
Returns tuple[float, ModelType] — A tuple of the value of the penalty and its gradient.

TotalVariation

class TotalVariation(salvus.opt.regularization._FirstDerivativeRegularization):
    def __init__(
        self,
        epsilon: types.float_,
        weight: types.float_ | UnstructuredModel = 1.0,
        reference_model: UnstructuredModel | None = None,
    ) -> None: ...

Total variation regularization.

Penalizes the deviation d = m - m_ref as phi = integral W * (sqrt(|grad d| ** 2 + eps ** 2) - eps) dV, which favors piece-wise constant models with sharp interfaces. eps makes the penalty differentiable, and subtracting it makes constant models free. For large eps, this approaches FirstOrderTikhonov / eps.

Parameters
  • epsilon types.float_ — Strictly positive smoothing parameter, in units of the spatial gradient of the parameters.
  • weight types.float_ | UnstructuredModel — Non-negative scalar, or an UnstructuredModel with non-negative point-wise weights for every parameter.
  • reference_model UnstructuredModel | None — Optional model the penalty is relative to.
Methods
compute_gradient()
def compute_gradient(
    self, model: ModelType, name: str | None = None
) -> ModelType: ...

Compute the gradient of the regularization term.

Parameters
  • model ModelType — The model to evaluate the gradient for.
  • name str | None — Optional name of the resulting gradient model.
Returns ModelType — The gradient as a model of the same type as the input.
compute_regularization()
def compute_regularization(self, model: ModelType) -> float: ...

Compute the value of the regularization term.

Parameters
  • model ModelType — The model to evaluate the penalty for.
Returns float — The value of the penalty.
compute_regularization_and_gradient()
def compute_regularization_and_gradient(
    self, model: ModelType, name: str | None = None
) -> tuple[float, ModelType]: ...

Compute the value and the gradient of the regularization term.

Cheaper than computing them separately.

Parameters
  • model ModelType — The model to evaluate the penalty for.
  • name str | None — Optional name of the resulting gradient model.
Returns tuple[float, ModelType] — A tuple of the value of the penalty and its gradient.

ZeroOrderTikhonov

class ZeroOrderTikhonov(salvus.opt.regularization.Regularization):
    def __init__(
        self,
        weight: types.float_ | ModelType = 1.0,
        reference_model: ModelType | None = None,
    ) -> None: ...

Zeroth order Tikhonov regularization, i.e., damping.

Penalizes the deviation d = m - m_ref as phi = 0.5 * <d, W * d>, with the weight W and the inner product of the model class.

Scalar weights work for every model class, point-wise weights for UnstructuredModel and GenericModel.

Parameters
  • weight types.float_ | ModelType — Non-negative scalar, or a model with non-negative point-wise weights for every parameter.
  • reference_model ModelType | None — Optional model the penalty is relative to.
Methods
compute_gradient()
def compute_gradient(
    self, model: ModelType, name: str | None = None
) -> ModelType: ...

Compute the gradient of the regularization term.

Parameters
  • model ModelType — The model to evaluate the gradient for.
  • name str | None — Optional name of the resulting gradient model.
Returns ModelType — The gradient as a model of the same type as the input.
compute_regularization()
def compute_regularization(self, model: ModelType) -> float: ...

Compute the value of the regularization term.

Parameters
  • model ModelType — The model to evaluate the penalty for.
Returns float — The value of the penalty.
compute_regularization_and_gradient()
def compute_regularization_and_gradient(
    self, model: ModelType, name: str | None = None
) -> tuple[float, ModelType]: ...

Compute the value and the gradient of the regularization term.

Cheaper than computing them separately.

Parameters
  • model ModelType — The model to evaluate the penalty for.
  • name str | None — Optional name of the resulting gradient model.
Returns tuple[float, ModelType] — A tuple of the value of the penalty and its gradient.