cofi.utils.QuadraticReg#

class cofi.utils.QuadraticReg(weighting_matrix: str | ndarray = 'damping', model_shape: tuple | None = None, reference_model: ndarray | None = None)[source]#

CoFI’s utility class to calculate weighted L2 norm regularization with an optional reference model

\(L(W, m_0) = ||D(m-m_0)||_2^2\)

With gradient of:

\(2\times W(m-m_0)\)

And hessian of:

\(2\times W.T W\)

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.

This class is a special case of LpNormRegularization with p=2.

Parameters:
  • 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 quadratic smoothing regularization for models of size 3:

>>> from cofi.utils import QuadraticReg
>>> my_reg = QuadraticReg(weighting_matrix="smoothing", model_shape=(4,))
>>> my_reg(np.array([0,2,1,0]))
53.99999999999999

To use togethter with cofi.BaseProblem:

>>> from cofi import BaseProblem
>>> my_problem = 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