Updated energy and minimization docstrings.

.gitignore

-*.html
+# custom 
+setup.cfg
+.idea
+.DS_Store
+
+# from https://github.com/github/gitignore/blob/master/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
 *.c
 *.o
 *.so
-*.pyc
-*.log
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
 *.egg
-*.egg-info
-*~
 
-.git/
-.svn/
-.spyderproject
-.document
-build
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
 
-.idea
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
 .coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# IPython Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# dotenv
+.env
+
+# virtualenv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+
+# Rope project settings
+.ropeproject
\ No newline at end of file

nifty/energies/energy.py

@@ -22,44 +22,44 @@ from keepers import Loggable
 
 
 class Energy(Loggable, object):
-    """ The Energy object provides the structure required for minimization schemes.
+    """ Provides the functional used by minimization schemes.
 
-   The implementation of a scalar function with its gradient and curvature at some position.
+   The Energy object is an implementation of a scalar function including its
+   gradient and curvature at some position.
 
     Parameters
     ----------
-    position : Field, float
-        The parameter of the scalar function and its first and second derivative.
+    position : Field
+        The input parameter of the scalar function.
 
     Attributes
     ----------
-    position : Field, float
-        The Field location in parameter space where value, gradient and curvature is evaluated.
-    value : float
-        The evaluation of the energy functional at given position.
-    gradient : Field, float
-        The gradient at given position in parameter direction.
-    curvature : callable
-        A positive semi-definite operator or function describing the curvature of the potential
-        at given position.
-
-    Raises
-    ------
-    NotImplementedError
-        Raised if
-            * value, gradient or curvature is called
-    AttributeError
-        Raised if
-            * copying of the position fails
+    position : Field
+        The Field location in parameter space where value, gradient and
+        curvature are evaluated.
+    value : np.float
+        The value of the energy functional at given `position`.
+    gradient : Field
+        The gradient at given `position` in parameter direction.
+    curvature : LinearOperator, callable
+        A positive semi-definite operator or function describing the curvature
+        of the potential at the given `position`.
 
     Notes
     -----
-    The Energy object gives the blueprint how to formulate the model in order to apply
-    various inference schemes. The functions value, gradient and curvature have to be
-    implemented according to the concrete inference problem.
+    An instance of the Energy class is defined at a certain location. If one
+    is interested in the value, gradient or curvature of the abstract energy
+    functional one has to 'jump' to the new position using the `at` method.
+    This method returns a new energy instance residing at the new position. By
+    this approach, intermediate results from computing e.g. the gradient can
+    safely be reused for e.g. the value or the curvature.
 
-    Memorizing the evaluations of some quantities minimizes the computational effort
-    for multiple calls.
+    Memorizing the evaluations of some quantities (using the memo decorator)
+    minimizes the computational effort for multiple calls.
+
+    See also
+    --------
+    memo
 
     """
 
@@ -74,7 +74,7 @@ class Energy(Loggable, object):
         self._position = position
 
     def at(self, position):
-        """ Initializes and returns new Energy object at new position.
+        """ Initializes and returns a new Energy object at the new position.
 
         Parameters
         ----------
@@ -87,20 +87,43 @@ class Energy(Loggable, object):
             Energy object at new position.
 
         """
+
         return self.__class__(position)
 
     @property
     def position(self):
+        """
+        The Field location in parameter space where value, gradient and
+        curvature are evaluated.
+
+        """
+
         return self._position
 
     @property
     def value(self):
+        """
+        The value of the energy functional at given `position`.
+
+        """
+
         raise NotImplementedError
 
     @property
     def gradient(self):
+        """
+        The gradient at given `position` in parameter direction.
+
+        """
+
         raise NotImplementedError
 
     @property
     def curvature(self):
+        """
+        A positive semi-definite operator or function describing the curvature
+        of the potential at the given `position`.
+
+        """
+
         raise NotImplementedError

nifty/energies/line_energy.py

@@ -20,52 +20,58 @@ from .energy import Energy
 
 
 class LineEnergy(Energy):
-    """A Energy object restricting an underlying Energy along only some line direction.
-    Given some Energy and line direction, its position is parametrized by a scalar
-    step size along the descent direction.
+    """ Evaluates an underlying Energy along a certain line direction.
+
+    Given an Energy class and a line direction, its position is parametrized by
+    a scalar step size along the descent direction relative to a zero point.
 
     Parameters
     ----------
     position : float
         The step length parameter along the given line direction.
     energy : Energy
-        The Energy object which will be restricted along the given line direction
-    line_direction : Field, float
-        Line direction restricting the Energy.
-    zero_point :  Field, float
-        Fixing the zero point of the line restriction. Used to memorize this position in new
-        initializations (default : None)
+        The Energy object which will be evaluated along the given direction.
+    line_direction : Field
+        Direction used for line evaluation.
+    zero_point :  Field *optional*
+        Fixing the zero point of the line restriction. Used to memorize this
+        position in new initializations. By the default the current position
+        of the supplied `energy` instance is used (default : None).
 
     Attributes
     ----------
-    position :  float
-        The step length along the given line direction.
+    position : float
+        The position along the given line direction relative to the zero point.
     value : float
-        The evaluation of the energy functional at given position.
+        The value of the energy functional at given `position`.
     gradient : float
-        The gradient along the line direction projected on the current line position.
+        The gradient of the underlying energy instance along the line direction
+        projected on the line direction.
     curvature : callable
-        A positive semi-definite operator or function describing the curvature of the potential
-        at given position.
+        A positive semi-definite operator or function describing the curvature
+        of the potential at given `position`.
     line_direction : Field
-        Direction along which the movement is restricted. Does not have to be normalized.
+        Direction along which the movement is restricted. Does not have to be
+        normalized.
     energy : Energy
-        The underlying Energy at the resulting position along the line according to the step length.
+        The underlying Energy at the `position` along the line direction.
 
     Raises
     ------
     NotImplementedError
         Raised if
-            * value, gradient or curvature of the attribute energy is not implemented.
+            * value, gradient or curvature of the attribute energy are not
+              implemented.
 
     Notes
     -----
-    The LineEnergy is used in minimization schemes in order to determine the step size along
-    some descent direction using a line search. It describes an underlying Energy which is restricted
-    along one direction, only requiring the step size parameter to determine a new position.
-
+    The LineEnergy is used in minimization schemes in order perform line
+    searches. It describes an underlying Energy which is restricted along one
+    direction, only requiring the step size parameter to determine a new
+    position.
 
     """
+
     def __init__(self, position, energy, line_direction, zero_point=None):
         super(LineEnergy, self).__init__(position=position)
         self.line_direction = line_direction
@@ -78,19 +84,20 @@ class LineEnergy(Energy):
         self.energy = energy.at(position=position_on_line)
 
     def at(self, position):
-        """ Initializes and returns new LineEnergy object at new position, memorizing the zero point.
+        """ Returns LineEnergy at new position, memorizing the zero point.
 
         Parameters
         ----------
         position : float
-            Parameter for the new position.
+            Parameter for the new position on the line direction.
 
         Returns
         -------
         out : LineEnergy
-            LineEnergy object at new position with same zero point.
+            LineEnergy object at new position with same zero point as `self`.
 
         """
+
         return self.__class__(position,
                               self.energy,
                               self.line_direction,

nifty/minimization/conjugate_gradient.py

@@ -23,56 +23,58 @@ from keepers import Loggable
 
 
 class ConjugateGradient(Loggable, object):
-    """Implementation of the Conjugate Gradient scheme.
-    
+    """ Implementation of the Conjugate Gradient scheme.
+
     It is an iterative method for solving a linear system of equations:
                                     Ax = b
-    
-    SUGGESTED LITERATURE:
-        Thomas V. Mikosch et al., "Numerical Optimization", Second Edition, 
-        2006, Springer-Verlag New York
-        
+
     Parameters
     ----------
-    convergence_tolerance : scalar
-        Tolerance specifying convergence. (default: 1E-4)
-    convergence_level : integer
-        Number of times the tolerance should be undershot before exiting. 
-        (default: 3)
+    convergence_tolerance : float *optional*
+        Tolerance specifying the case of convergence. (default: 1E-4)
+    convergence_level : integer *optional*
+        Number of times the tolerance must be undershot before convergence
+        is reached. (default: 3)
     iteration_limit : integer *optional*
-        Maximum number of iterations performed. (default: None)
-    reset_count : integer, *optional*
+        Maximum number of iterations performed (default: None).
+    reset_count : integer *optional*
         Number of iterations after which to restart; i.e., forget previous
-        conjugated directions. (default: None)
-    preconditioner : function *optional*
-        The user can provide a function which transforms the variables of the 
-        system to make the converge more favorable.(default: None)
-    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 
-        an Energy object(energy) and integer(iteration_number). (default: None)
+        conjugated directions (default: None).
+    preconditioner : Operator *optional*
+        This operator can be provided which transforms the variables of the
+        system to improve the conditioning (default: None).
+    callback : callable *optional*
+        Function f(energy, iteration_number) supplied by the user to perform
+        in-situ analysis at every iteration step. When being called the
+        current energy and iteration_number are passed. (default: None)
 
     Attributes
     ----------
     convergence_tolerance : float
-        Tolerance specifying convergence.
-    convergence_level : float
-        Number of times the tolerance should be undershot before exiting.
+        Tolerance specifying the case of convergence.
+    convergence_level : integer
+        Number of times the tolerance must be undershot before convergence
+        is reached. (default: 3)
     iteration_limit : integer
         Maximum number of iterations performed.
     reset_count : integer
         Number of iterations after which to restart; i.e., forget previous
         conjugated directions.
     preconditioner : function
-        The user can provide a function which transforms the variables of the 
-        system to make the converge more favorable.
-    callback : function
-        Function f(energy, iteration_number) specified by the user to print 
-        iteration number and energy value at every iteration step. It accepts 
-        an Energy object(energy) and integer(iteration_number).
-    
-    """    
-    
+        This operator can be provided which transforms the variables of the
+        system to improve the conditioning (default: None).
+    callback : callable
+        Function f(energy, iteration_number) supplied by the user to perform
+        in-situ analysis at every iteration step. When being called the
+        current energy and iteration_number are passed. (default: None)
+
+    References
+    ----------
+    Thomas V. Mikosch et al., "Numerical Optimization", Second Edition,
+    2006, Springer-Verlag New York
+
+    """
+
     def __init__(self, convergence_tolerance=1E-4, convergence_level=3,
                  iteration_limit=None, reset_count=None,
                  preconditioner=None, callback=None):
@@ -95,14 +97,15 @@ class ConjugateGradient(Loggable, object):
         self.callback = callback
 
     def __call__(self, A, b, x0):
-        """Runs the conjugate gradient minimization.
+        """ Runs the conjugate gradient minimization.
+        For `Ax = b` the variable `x` is infered.
 
         Parameters
         ----------
         A : Operator
             Operator `A` applicable to a Field.
         b : Field
-            Resulting Field of the operation `A(x)`.
+            Result of the operation `A(x)`.
         x0 : Field
             Starting guess for the minimization.
 
@@ -115,6 +118,7 @@ class ConjugateGradient(Loggable, object):
             has converged or not.
 
         """
+
         r = b - A(x0)
         d = self.preconditioner(r)
         previous_gamma = r.dot(d)

nifty/minimization/descent_minimizer.py

@@ -27,53 +27,56 @@ from .line_searching import LineSearchStrongWolfe
 
 
 class DescentMinimizer(Loggable, object):
-    """A class used by other minimization methods to find a local minimum.
-    
-    Descent minimization methods are used to find a local minimum of a scalar function
-    by following a descent direction. This class implements the minimization procedure,
-    the descent direction has to be implemented separately.
-    
+    """ A base class used by gradient methods to find a local minimum.
+
+    Descent minimization methods are used to find a local minimum of a scalar
+    function by following a descent direction. This class implements the
+    minimization procedure once a descent direction is known. The descent
+    direction has to be implemented separately.
+
     Parameters
     ----------
-    line_searcher : callable
-        Function which finds the step size in 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 
-        an Energy object(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)
+    line_searcher : callable *optional*
+        Function which infers the step size in the descent direction
+        (default : LineSearchStrongWolfe()).
+    callback : callable *optional*
+        Function f(energy, iteration_number) supplied by the user to perform
+        in-situ analysis at every iteration step. When being called the
+        current energy and iteration_number are passed. (default: None)
+    convergence_tolerance : float *optional*
+        Tolerance specifying the case of convergence. (default: 1E-4)
+    convergence_level : integer *optional*
+        Number of times the tolerance must be undershot before convergence
+        is reached. (default: 3)
     iteration_limit : integer *optional*
-        Maximum number of iterations performed. (default: None)
-    
+        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.
+        Tolerance specifying the case of convergence.
+    convergence_level : integer
+        Number of times the tolerance must be undershot before convergence
+        is reached. (default: 3)
     iteration_limit : integer
         Maximum number of iterations performed.
-    line_searcher : callable
-        Function which finds the step size into the descent direction
+    line_searcher : LineSearch
+        Function which infers the optimal step size for functional minization
+        given a 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 
-        an Energy object(energy) and integer(iteration_number).
-    
-    Raises
+        Function f(energy, iteration_number) supplied by the user to perform
+        in-situ analysis at every iteration step. When being called the
+        current energy and iteration_number are passed.
+
+    Notes
     ------
-    StopIteration
-        Raised if
-            *callback function does not match the specified form.
+    The callback function can be used to externally stop the minimization by
+    raising a `StopIteration` exception.
+    Check `get_descent_direction` of a derived class for information on the