From 7412dcc34b9d19107ddf3ec671b6bf3f3511f968 Mon Sep 17 00:00:00 2001 From: "Matevz, Sraml (sraml)" Date: Tue, 9 May 2017 14:02:55 +0200 Subject: [PATCH] documentation Line search and Quasi Newton minimizer added --- .../line_searching/line_search.py | 54 +++++---- nifty/minimization/quasi_newton_minimizer.py | 103 +++++++++++++----- 2 files changed, 102 insertions(+), 55 deletions(-) diff --git a/nifty/minimization/line_searching/line_search.py b/nifty/minimization/line_searching/line_search.py index 612f6a07..3cadcc01 100644 --- a/nifty/minimization/line_searching/line_search.py +++ b/nifty/minimization/line_searching/line_search.py @@ -24,50 +24,48 @@ from nifty import LineEnergy class LineSearch(Loggable, object): + """Class for finding a step size. + + Initialize the line search procedure which can be used by a specific line + search method. Its finds the step size in a specific direction in the + minimization process. + + Attributes + ---------- + line_energy : LineEnergy Object + LineEnergy object from which we can extract energy at a specific point. + f_k_minus_1 : Field + Value of the field at the k-1 iteration of the line search procedure. + prefered_initial_step_size : float + Initial guess for the step length. + """ - Class for finding a step size. - """ + __metaclass__ = abc.ABCMeta def __init__(self): - """ - Parameters - ---------- - - f : callable f(x, *args) - Objective function. - - fprime : callable f'(x, *args) - Objective functions gradient. - - f_args : tuple (optional) - Additional arguments passed to objective function and its - derivation. - """ + self.line_energy = None self.f_k_minus_1 = None self.prefered_initial_step_size = None def _set_line_energy(self, energy, pk, f_k_minus_1=None): - """ - Set the coordinates for a new line search. + """Set the coordinates for a new line search. Parameters ---------- - xk : ndarray, d2o, field - Starting point. - - pk : ndarray, d2o, field + energy : Energy object + Energy object from which we can calculate the + energy, gradient and curvature at a specific point. + pk : Field Unit vector in search direction. - f_k : float (optional) - Function value f(x_k). - - fprime_k : ndarray, d2o, field (optional) - Function value fprime(xk). - + f_k_minus_1 : float *optional* + Value of the field at the k-1 iteration of the line search + procedure. + """ self.line_energy = LineEnergy(position=0., energy=energy, diff --git a/nifty/minimization/quasi_newton_minimizer.py b/nifty/minimization/quasi_newton_minimizer.py index 764a90d6..6f20c4a9 100644 --- a/nifty/minimization/quasi_newton_minimizer.py +++ b/nifty/minimization/quasi_newton_minimizer.py @@ -26,6 +26,54 @@ from .line_searching import LineSearchStrongWolfe class QuasiNewtonMinimizer(Loggable, object): + """A Class used by other minimization methods to find local minimum. + + Quasi-Newton methods are used to find local minima or maxima of a function + by approximating the Jacobian or Hessian matrix at every iteration. The + class performs general steps(gets the gradient, descend direction, step + size and checks the conergence) which can be used then by a specific + minimization method. + + Parameters + ---------- + line_searcher : callable + Function which finds the step size into the descent direction. (default: + LineSearchStrongWolfe()) + callback : function, *optional* + Function f(energy, iteration_number) specified by the user to print + iteration number and energy value at every iteration step. It accepts + a function(energy) and integer(iteration_number). (default: None) + convergence_tolerance : scalar + Tolerance specifying convergence. (default: 1E-4) + convergence_level : integer + Number of times the tolerance should be undershot before + exiting. (default: 3) + iteration_limit : integer *optional* + Maximum number of iterations performed. (default: None) + + Attributes + ---------- + convergence_tolerance : float + Tolerance specifying convergence. + convergence_level : float + Number of times the tolerance should be undershot before + exiting. + iteration_limit : integer + Maximum number of iterations performed. + line_searcher : callable + Function which finds the step size into the descent direction + callback : function + Function f(energy, iteration_number) specified by the user to print + iteration number and energy value at every iteration step. It accepts + a function(energy) and integer(iteration_number). + + Raises + ------ + StopIteration + Raised if + *callback function does not match the specified form. + """ + __metaclass__ = abc.ABCMeta def __init__(self, line_searcher=LineSearchStrongWolfe(), callback=None, @@ -43,33 +91,34 @@ class QuasiNewtonMinimizer(Loggable, object): self.callback = callback def __call__(self, energy): - """ - Runs the steepest descent minimization. - - Parameters - ---------- - x0 : field - Starting guess for the minimization. - alpha : scalar, *optional* - Starting step width to be multiplied with normalized gradient - (default: 1). - tol : scalar, *optional* - Tolerance specifying convergence; measured by maximal change in - `x` (default: 1E-4). - clevel : integer, *optional* - Number of times the tolerance should be undershot before - exiting (default: 8). - self.iteration_limit : integer, *optional* - Maximum number of iterations performed (default: 100,000). - - Returns - ------- - x : field - Latest `x` of the minimization. - convergence : integer - Latest convergence level indicating whether the minimization - has converged or not. - + """Runs the minimization on the provided Energy class. + + Accepts the NIFTY Energy class which describes our system and it runs + the minimization to find the minimum/maximum of the system. + + Parameters + ---------- + energy : Energy object + Energy object provided by the user from which we can calculate the + energy, gradient and curvature at a specific point. + + Returns + ------- + x : field + Latest `energy` of the minimization. + convergence : integer + Latest convergence level indicating whether the minimization + has converged or not. + + Note + ---- + It stops the minimization if: + *callback function does not match the specified form. + *a perfectly flat point is reached. + *according to line-search the minimum is found. + *target convergence level is reached. + *iteration limit is reached. + """ convergence = 0 -- GitLab