cofi.utils.LpNormRegularization

class cofi.utils.LpNormRegularization(p: Number = 2, weighting_matrix: str | ndarray = 'damping', model_shape: tuple | None = None, reference_model: ndarray | None = None)

CoFI’s utility class to calculate Lp-norm regularization, given the p value (default to 2), an optional weighting matrix and an optional reference value

\(L(p, W, m_0) = ||W(m-m_0)||_p^p = \sum_i |W(m-m_0)_i|^p\)

With element-wise gradient of:

\(\sum_i p|(W(m-m_0))_i|^{p-1}sign((W(m-m_0))_i)W_{ij}\)

And element-wise hessian of:

\(\sum_i p(p-1)|(W(m-m_0))_i|^{p-2}W_{ij}W_{ik}\)

Where \(W\) is a weighting matrix either generated given a specified type (e.g. weighting_matrix="smoothing"), or a bring-your-own matrix (e.g. weighting_matrix=my_matrix). This weighting matrix is by default in sparse type scipy.sparse.csr_matrix.

The weighting matrix (if not bring-your-own) can be generated provided with an option from {"damping", "flattening", "smoothing"}.

• If weighting_matrix == "damping", then

  • matrix is the identity matrix of size \((M,M)\), where \(M\) is the number of model parameters

• If weighting_matrix == "roughening" (or equivalently "flattening"), then

  • matrix is \(W\) that we generate based on the model shape you’ve provided. We use the Python package findiff to generate it. “By default, findiff uses finite difference schemes with second order accuracy in the grid spacing.” (See findiff documentation on Derivatives for more details). For 1D problems, it looks like

    \(\begin{pmatrix}-1.5&2&-0.5&&&\\-0.5&&0.5&&&&&\\&-0.5&&0.5&&&&\\&&...&&...&&&\\&&&-0.5&&0.5&\\&&&&-0.5&&0.5\\&&&&0.5&-2&1.5\end{pmatrix}\)

    While for higher dimension problems, by default it’s a flattened version of an N-D array. The actual ordering of model parameters in higher dimensions is controlled by findiff.operators.FinDiff.

• If reg_type == "smoothing", then

  • matrix is \(W\) that we generate based on the model shape you’ve provided. We use the Python package findiff to generate it. “By default, findiff uses finite difference schemes with second order accuracy in the grid spacing.” (See findiff documentation on Derivatives for more details). For 1D problems, it looks like

    \(\begin{pmatrix}2&-5&4&-1&&&\\1&-2&1&&&&\\&1&-2&1&&&\\&&...&...&...&&\\&&&1&-2&1&\\&&&&1&-2&1\\&&&-1&4&-5&2\end{pmatrix}\)

    While for higher dimension problems, by default it’s a flattened version of an N-D array. The actual ordering of model parameters in higher dimensions is controlled by findiff.operators.FinDiff.

Parameters:

• p (Number) – order value (p in the formula above), default to 2

• weighting_matrix (str or np.ndarray) – regularization type (one of {"damping", "flattening" "smoothing"}), or a bring-your-own weighting matrix, default to “damping” (identity matrix for weighting)

• model_shape (tuple) – shape of the model, must be supplied if the reference_model is not given

• reference_model (np.ndarray) – \(m_0\) in the formula above

Raises:

• ValueError – if neither model_size nor reference_model is given

• DimensionMismatchError – if both model_size and reference_model are given but they don’t match in dimension

Examples

Generate an L1 norm damping regularization for models of size 3:

>>> from cofi.utils import LpNormRegularization
>>> my_reg = LpNormRegularization(p=1, model_shape=(3,))
>>> my_reg(np.array([0,2,1]))
3.0

To use togethter with cofi.BaseProblem:

>>> from cofi import BaseProblem
>>> my_problem.set_regularization(my_reg)

Reference Details

__call__(model: ndarray) → Number

a class instance itself can also be called as a function

It works exactly the same as reg.

In other words, the following two usages are exactly the same:

>>> my_reg = QuadraticReg(factor=1, model_size=3)
>>> my_reg_value = my_reg(np.array([1,2,3]))            # usage 1
>>> my_reg_value = my_reg.reg(np.array([1,2,3]))        # usage 2

gradient(model: ndarray) → ndarray

the gradient of regularization function with respect to model given a model

The usual size for the gradient is \((M,)\) where \(M\) is the number of model parameters

hessian(model: ndarray) → ndarray

the hessian of regularization function with respect to model given a model

The usual size for the Hessian is \((M,M)\) where \(M\) is the number of model parameters

reg(model: ndarray) → Number

the regularization function value given a model to evaluate

matrix

the regularization matrix

This is either an identity matrix, or first/second order difference matrix (generated by Python package findiff), or a custom matrix brought on your own.

model_shape

model_size

the number of unknowns that current regularization function accepts

back to top