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(np.array([1,2,3]))
3.0


To use together with cofi.BaseProblem:

>>> from cofi import BaseProblem
>>> my_problem = BaseProblem()
>>> my_problem.set_regularization(reg)


You may also combine two regularization terms:

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


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) [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