cofi.utils.QuadraticReg#

class cofi.utils.QuadraticReg(factor: numbers.Number, model_size: Union[numbers.Number, numpy.ndarray], reg_type: str = 'damping', ref_model: Optional[numpy.ndarray] = None, byo_matrix: Optional[numpy.ndarray] = None)[source]#

CoFI’s utility class to calculate damping, flattening (roughening), and smoothing regularization

They correspond to the zeroth order, first order and second order Tikhonov regularization approaches respectively.

  • If reg_type == "damping", then

    • reg produces \(\text{reg}=\text{factor}\times||m-m_0||_2^2\)

    • gradient produces \(\frac{\partial\text{reg}}{\partial m}=2\times\text{factor}\times(m-m_0)\)

    • hessian produces \(\frac{\partial^2\text{reg}}{\partial m}=2\times\text{factor}\times I\)

    • matrix is the identity matrix of size \((M,M)\)

    • where

      • \(m_0\) is a reference model that you can specify in ref_model argument (default to zero)

      • \(M\) is the number of model parameters

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

    • reg produces \(\text{reg}=\text{factor}\times||Dm||_2^2\)

    • gradient produces \(\frac{\partial\text{reg}}{\partial m}=2\times\text{factor}\times D^TDm\)

    • hessian produces \(\frac{\partial^2\text{reg}}{\partial m}=2\times\text{factor}\times D^TD\)

    • matrix is \(D\)

    • where

      • \(D\) matrix helps calculate the first order derivative of \(m\). 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

    • reg produces \(\text{reg}=\text{factor}\times||Dm||_2^2\)

    • gradient produces \(\frac{\partial\text{reg}}{\partial m}=2\times\text{factor}\times D^TDm\)

    • hessian produces \(\frac{\partial^2\text{reg}}{\partial m}=2\times\text{factor}\times D^TD\)

    • matrix is \(D\)

    • where

      • \(D\) matrix helps calculate the second order derivatives of \(m\). 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.

  • If reg_type == None, then we assume you want to use the argument byo_matrix,

    • reg produces \(\text{reg}=\text{factor}\times||Dm||_2^2\)

    • gradient produces \(\frac{\partial\text{reg}}{\partial m}=2\times\text{factor}\times D^TDm\)

    • hessian produces \(\frac{\partial^2\text{reg}}{\partial m}=2\times\text{factor}\times D^TD\)

    • matrix is \(D\)

    • where

      • \(D\) matrix is byo_matrix from the arguments (or identity matrix if byo_matrix is None)

Parameters
  • factor (Number) – the scale for the regularization term

  • model_size (Number) – the number of elements in a inference model

  • reg_type (str) – specify what kind of regularization is to be calculated, by default "damping"

  • ref_model (np.ndarray) – reference model used only when reg_type == "damping", by default None (if this is None, then reference model is assumed to be zero)

  • byo_matrix (np.ndarray) – bring-your-own matrix, activated only when reg_type == None

Raises

ValueError – when input arguments don’t conform to the standards described above. Check error message for details.

Examples

Generate a quadratic damping regularization matrix for model of size 3:

>>> from cofi.utils import QuadraticReg
>>> reg = QuadraticReg(factor=1, model_size=3)
>>> reg(np.array([1,2,3]))
3.0

To use together with cofi.BaseProblem:

>>> from cofi import BaseProblem
>>> from cofi.utils import QuadraticReg
>>> reg = QuadraticReg(factor=1, model_size=3)
>>> my_problem = BaseProblem()
>>> my_problem.set_regularization(reg)

You may also combine two regularization terms:

>>> from cofi import BaseProblem
>>> from cofi.utils import QuadraticReg
>>> reg1 = QuadraticReg(factor=1, model_size=3, reg_type="damping")
>>> reg2 = QuadraticReg(factor=2, model_size=3, reg_type="smoothing")
>>> my_problem = BaseProblem()
>>> my_problem.set_regularization(reg1 + reg2)

Reference Details

__call__(model: numpy.ndarray) numbers.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: numpy.ndarray) numpy.ndarray[source]#

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: numpy.ndarray) numpy.ndarray[source]#

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: numpy.ndarray) numbers.Number[source]#

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_size#

the number of model parameters

This is always a number describing number of unknowns

back to top