Solving function¶
-
pyunlocbox.solvers.
solve
(functions, x0, solver=None, relTol=0.001, absTol=-inf, convergence_speed=-inf, maxIter=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_{k=0}^{k=M} f_k(x)\), i.e. solves \(\operatorname{arg\,min}\limits_x \sum\limits_{k=0}^{k=M} f_k(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. Thepyunlocbox.functions.func.grad()
and / orpyunlocbox.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.relTol : float, optional
The convergence (relative tolerance) stopping criterion. The algorithm stops if \(\frac{n(k)-n(k-1)}{n(k)}<reltol\) where \(n(k)=f(x)=f_1(x)+f_2(x)\) is the objective function at iteration \(k\). Default is \(10^{-3}\).
absTol : float, optional
The absolute tolerance stopping criterion. The algorithm stops if \(n(k)<abstol\). 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).
maxIter : int, optional
The maximum number of iterations. Default is 200.
verbosity : {‘low’, ‘high’, ‘none’}, optional
The log level :
'none'
for no log,'low'
for resume at convergence,'high'
to for all steps. Default is'low'
.Returns: sol : ndarray
problem solution
solver : str
used solver
niter : int
number of iterations
time : float
execution time in seconds
eval : float
final evaluation of the objective function \(f(x)\)
crit : {‘MAX_IT’, ‘ABS_TOL’, ‘REL_TOL’, ‘CONV_SPEED’}
Used stopping criterion. ‘MAX_IT’ if the maximum number of iterations maxIter is reached, ‘ABS_TOL’ if the objective function value is smaller than absTol, ‘REL_TOL’ if the relative objective function improvement was smaller than relTol (i.e. the algorithm converged), ‘CONV_SPEED’ if the objective function improvement is smaller than convergence_speed.
rel : float
relative objective improvement at convergence
objective : ndarray
successive evaluations of the objective function at each iteration
Examples
Simple example showing the automatic selection of a solver (and a second function) :
>>> import pyunlocbox >>> f1 = pyunlocbox.functions.norm_l2(y=[4, 5, 6, 7]) >>> ret = pyunlocbox.solvers.solve([f1], [0, 0, 0, 0], absTol=1e-5) INFO: Added dummy objective function. 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 : ABS_TOL >>> ret['sol'] array([ 3.99996922, 4.99996153, 5.99995383, 6.99994614])