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 anndarray
, 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 isTrue
.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.])