Function objects

Interface

class pyunlocbox.functions.func(verbosity='none')

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:

verbosity : {‘none’, ‘low’, ‘high’}, optional

The log level : 'none' for no log, 'low' for resume at convergence, 'high' to for all steps. Default is 'low'.

Examples

Lets 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])

eval(x)

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)

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)

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) = \min_z \frac{1}{2} ||x-z||_2^2 + \gamma f(z)\)

Dummy function

class pyunlocbox.functions.dummy(verbosity='none')

Bases: pyunlocbox.functions.func

Dummy function object.

This can be used as a second function object when there is only one function to minimize. The eval(), prox() and grad() methods then all return 0.

See generic attributes descriptions of the pyunlocbox.functions.func base class.

Examples

>>> import pyunlocbox
>>> f = pyunlocbox.functions.dummy(verbosity='low')
>>> x = [1, 2, 3, 4]
>>> f.eval(x)
dummy evaluation : 0.000000e+00
0
>>> f.prox(x, 1)
array([ 0.,  0.,  0.,  0.])
>>> f.grad(x)
array([ 0.,  0.,  0.,  0.])