Solving function

pyunlocbox.solvers.solve(functions, x0, solver=None, rtol=0.001, atol=-inf, convergence_speed=-inf, maxit=200, verbosity='LOW')[source]

Solve an optimization problem whose objective function is the sum of some convex functions.

This function minimizes the objective function \(f(x) = \sum\limits_{m=0}^{m=M} f_m(x)\), i.e. solves \(\operatorname{arg\,min}\limits_x f(x)\) for \(x \in \mathbb{R}^N\) using whatever algorithm. It returns a dictionary with the found solution and some informations about the algorithm execution.

Parameters:

functions : list of objects

A list of convex functions to minimize. These are objects who must implement the pyunlocbox.functions.func.eval() method. The pyunlocbox.functions.func.grad() and / or pyunlocbox.functions.func.prox() methods are required by some solvers. Note also that some solvers can only handle two convex functions while others may handle more. Please refer to the documentation of the considered solver.

x0 : array_like

Starting point of the algorithm, \(x_0 \in \mathbb{R}^N\).

solver : solver class instance, optional

The solver algorithm. It is an object who must inherit from pyunlocbox.solvers.solver and implement the _pre(), _algo() and _post() methods. If no solver object are provided, a standard one will be chosen given the number of convex function objects and their implemented methods.

rtol : float, optional

The convergence (relative tolerance) stopping criterion. The algorithm stops if \(\left|\frac{n(k-1)-n(k)}{n(k)}\right|<rtol\) where \(n(k)=f(x)\) is the objective function at iteration \(k\). Default is \(10^{-3}\).

atol : float, optional

The absolute tolerance stopping criterion. The algorithm stops if \(n(k)<atol\). Default is minus infinity.

convergence_speed : float, optional

The minimum tolerable convergence speed of the objective function. The algorithm stops if n(k-1) - n(k) < convergence_speed. Default is minus infinity (i.e. the objective function may even increase).

maxit : int, optional

The maximum number of iterations. Default is 200.

verbosity : {‘NONE’, ‘LOW’, ‘HIGH’, ‘ALL’}, optional

The log level : 'NONE' for no log, 'LOW' for resume at convergence, 'HIGH' for info at all solving steps, 'ALL' for all possible outputs, including at each steps of the proximal operators computation. Default is 'LOW'.

Returns:

sol : ndarray

The problem solution.

solver : str

The used solver.

niter : int

The number of iterations.

time : float

The execution time in seconds.

eval : float

The final evaluation of the objective function \(f(x)\).

crit : {‘MAXIT’, ‘ATOL’, ‘RTOL’, ‘CONVSPEED’}

The used stopping criterion. ‘MAXIT’ if the maximum number of iterations maxit is reached, ‘ATOL’ if the objective function value is smaller than atol, ‘RTOL’ if the relative objective function improvement was smaller than rtol (i.e. the algorithm converged), ‘CONVSPEED’ if the objective function improvement is smaller than convergence_speed.

rel : float

The relative objective improvement at convergence.

objective : ndarray

The successive evaluations of the objective function at each iteration.

Examples

>>> import pyunlocbox
>>> f = pyunlocbox.functions.norm_l2(y=[4, 5, 6, 7])
>>> ret = pyunlocbox.solvers.solve([f], [0, 0, 0, 0], atol=1e-5)
INFO: Dummy objective function added.
INFO: Selected solver : forward_backward
Solution found after 10 iterations :
    objective function f(sol) = 7.460428e-09
    last relative objective improvement : 1.624424e+03
    stopping criterion : ATOL
>>> ret['sol']
array([ 3.99996922,  4.99996153,  5.99995383,  6.99994614])