Commit 7412dcc3 authored by Matevz, Sraml (sraml)'s avatar Matevz, Sraml (sraml)

documentation Line search and Quasi Newton minimizer added

parent ad3a7d38
Pipeline #12185 passed with stage
in 4 minutes and 47 seconds
......@@ -24,49 +24,47 @@ from nifty import LineEnergy
class LineSearch(Loggable, object):
"""
Class for finding a step size.
"""
__metaclass__ = abc.ABCMeta
"""Class for finding a step size.
def __init__(self):
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.
"""
Parameters
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.
f : callable f(x, *args)
Objective function.
"""
__metaclass__ = abc.ABCMeta
def __init__(self):
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.,
......
......@@ -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.
"""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
----------
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).
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 `x` of the minimization.
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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment