Function objects

Interface

class pyunlocbox.functions.func(y=0, A=None, At=None, tight=True, nu=1, tol=0.001, maxit=200)[source]

Bases: object

This class defines the function object interface.

It is intended to be a base class for standard functions which will implement the required methods. It can also be instantiated by user code and dynamically modified for rapid testing. The instanced objects are meant to be passed to the pyunlocbox.solvers.solve() solving function.

Parameters:

y : array_like, optional

Measurements. Default is 0.

A : function or ndarray, optional

The forward operator. Default is the identity, \(A(x)=x\). If A is an ndarray, it will be converted to the operator form.

At : function or ndarray, optional

The adjoint operator. If At is an ndarray, it will be converted to the operator form. If A is an ndarray, default is the transpose of A. If A is a function, default is A, \(At(x)=A(x)\).

tight : bool, optional

True if A is a tight frame, False otherwise. Default is True.

nu : float, optional

Bound on the norm of the operator A, i.e. \(\|A(x)\|^2 \leq \nu \|x\|^2\). Default is 1.

tol : float, optional

The tolerance stopping criterion. The exact definition depends on the function object, please see the documentation of the considered function. Default is 1e-3.

maxit : int, optional

The maximum number of iterations. Default is 200.

Examples

Let’s define a parabola as an example of the manual implementation of a function object :

>>> import pyunlocbox
>>> f = pyunlocbox.functions.func()
>>> f._eval = lambda x: x**2
>>> f._grad = lambda x: 2*x
>>> x = [1, 2, 3, 4]
>>> f.eval(x)
array([ 1,  4,  9, 16])
>>> f.grad(x)
array([2, 4, 6, 8])
>>> f.cap(x)
['EVAL', 'GRAD']
cap(x)[source]

Test the capabilities of the function object.

Parameters:

x : array_like

The evaluation point. Not really needed, but this function calls the methods of the object to test if they can properly execute without raising an exception. Therefore it needs some evaluation point with a consistent size.

Returns:

cap : list of string

A list of capabilities (‘EVAL’, ‘GRAD’, ‘PROX’).

eval(x)[source]

Function evaluation.

Parameters:

x : array_like

The evaluation point.

Returns:

z : float

The objective function evaluated at x.

Notes

This method is required by the pyunlocbox.solvers.solve() solving function to evaluate the objective function.

grad(x)[source]

Function gradient.

Parameters:

x : array_like

The evaluation point.

Returns:

z : ndarray

The objective function gradient evaluated at x.

Notes

This method is required by some solvers.

prox(x, T)[source]

Function proximal operator.

Parameters:

x : array_like

The evaluation point.

T : float

The regularization parameter.

Returns:

z : ndarray

The proximal operator evaluated at x.

Notes

This method is required by some solvers.

The proximal operator is defined by \(\operatorname{prox}_{f,\gamma}(x) = \operatorname{arg\,min} \limits_z \frac{1}{2} \|x-z\|_2^2 + \gamma f(z)\)

Dummy function

class pyunlocbox.functions.dummy(**kwargs)[source]

Bases: pyunlocbox.functions.func

Dummy function object.

This can be used as a second function object when there is only one function to minimize. It always evaluates as 0.

Examples

>>> import pyunlocbox
>>> f = pyunlocbox.functions.dummy()
>>> x = [1, 2, 3, 4]
>>> f.eval(x)
0
>>> f.prox(x, 1)
array([1, 2, 3, 4])
>>> f.grad(x)
array([ 0.,  0.,  0.,  0.])