cofi.utils.BaseRegularization

class cofi.utils.BaseRegularization

Base class for a regularization term

Check QuadraticReg for a concrete example.

Basic interface

The basic properties / methods for a regularization term in cofi.utils include the following:

BaseRegularization.model_size	the number of unknowns that current regularization function accepts
BaseRegularization.reg(model)	the regularization function value given a model to evaluate
BaseRegularization.gradient(model)	the gradient of regularization function with respect to model given a model
BaseRegularization.hessian(model)	the hessian of regularization function with respect to model given a model
BaseRegularization.__call__(model)	a class instance itself can also be called as a function

Adding two terms

Two instances of BaseRegularization can also be added together using the + operator:

BaseRegularization.__add__(other_reg)

Adds two regularization terms

Reference Details

__add__(other_reg)

Adds two regularization terms

Parameters:

other_reg (BaseRegularization) – the second argument of “+” operator; must also be a BaseRegularization instance

Returns:

a regularization term resRegularization such that:

• \(\text{resRegularization.reg}(m)=\text{self.reg}(m)+\text{other_reg.reg}(m)\)

• \(\text{resRegularization.gradient}(m)=\text{self.gradient}(m)+\text{other_reg.gradient}(m)\)

• \(\text{resRegularization.hessian}(m)=\text{self.hessian}(m)+\text{other_reg.hessian}(m)\)

Return type:

BaseRegularization

Raises:

• TypeError – when the other_reg is not a regularization term generated by CoFI Utils

• DimensionMismatchError – when the other_reg doesn’t accept model_size that matches the one of self

Examples

>>> from cofi import BaseProblem
>>> from cofi.utils import QuadraticReg
>>> reg1 = QuadraticReg(model_shape=(3,), weighting_matrix="damping")
>>> reg2 = QuadraticReg(model_shape=(3,), weighting_matrix="smoothing")
>>> my_problem = BaseProblem()
>>> my_problem.set_regularization(reg1 + reg2)

__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

__rmul__(coefficient)

Multiply a regularization term with a constant number

Parameters:

coefficient (Number) – the first argument of “*” operator; must be a Number

Returns:

a regularization term resRegularization such that:

• \(\text{resRegularization.reg}(m)=\text{coefficient}\times\text{self.reg}(m)\)

• \(\text{resRegularization.gradient}(m)=\text{coefficient}\times\text{self.gradient}(m)\)

• \(\text{resRegularization.hessian}(m)=\text{coefficient}\times\text{self.hessian}(m)\)

Return type:

BaseRegularization

Raises:

TypeError – when the coefficient is not of a python Number type

Examples

>>> from cofi import BaseProblem
>>> from cofi.utils import QuadraticReg
>>> reg = QuadraticReg(model_shape=(3,), weighting_matrix="damping")
>>> my_problem = BaseProblem()
>>> my_problem.set_regularization(10 * reg)

abstract 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

abstract 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

abstract reg(model: ndarray) → Number

the regularization function value given a model to evaluate

model_shape

the shape of models that current regularization function accepts

model_size

the number of unknowns that current regularization function accepts

back to top