Merge branch 'docstrings_energy_minimization' of gitlab.mpcdf.mpg.de:ift/NIFTy...

Merge branch 'docstrings_energy_minimization' of gitlab.mpcdf.mpg.de:ift/NIFTy into docstrings_energy_minimization

nifty/energies/energy.py

@@ -22,23 +22,24 @@ from keepers import Loggable
 class Energy(Loggable, object):
     """ The Energy object provides the structure required for minimization schemes.
 
-    It is the abstract implementation of a scalar function with its gradient and curvature at some position.
+   The implementation of a scalar function with its gradient and curvature at some position.
 
     Parameters
     ----------
-    position : Field
+    position : Field, float
         The parameter of the scalar function and its first and second derivative.
 
     Attributes
     ----------
-    position : Field
+    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
+    gradient : Field, float
         The gradient at given position in parameter direction.
-    curvature : InvertibleOperator
-        An implicit operator encoding the curvature at given position.
+    curvature : callable
+        A positive semi-definite operator or function describing the curvature of the potential
+        at given position.
 
     Raises
     ------
@@ -58,7 +59,6 @@ class Energy(Loggable, object):
     Memorizing the evaluations of some quantities minimizes the computational effort
     for multiple calls.
 
-
     """
     def __init__(self, position):
         self._cache = {}
@@ -88,10 +88,6 @@ class Energy(Loggable, object):
     def position(self):
         return self._position
 
-    @position.setter
-    def position(self, position):
-        self._position = position
-
     @property
     def value(self):
         raise NotImplementedError

nifty/energies/line_energy.py

@@ -20,6 +20,52 @@ 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.
+
+    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)
+
+    Attributes
+    ----------
+    position :  float
+        The step length along the given line direction.
+    value : float
+        The evaluation of the energy functional at given position.
+    gradient : float
+        The gradient along the line direction projected on the current line position.
+    curvature : callable
+        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.
+    energy : Energy
+        The underlying Energy at the resulting position along the line according to the step length.
+
+    Raises
+    ------
+    NotImplementedError
+        Raised if
+            * value, gradient or curvature of the attribute energy is 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.
+
+
+    """
     def __init__(self, position, energy, line_direction, zero_point=None):
         super(LineEnergy, self).__init__(position=position)
         self.line_direction = line_direction
@@ -32,6 +78,19 @@ 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.
+
+        Parameters
+        ----------
+        position : float
+            Parameter for the new position.
+
+        Returns
+        -------
+        out : LineEnergy
+            LineEnergy object at new position with same zero point.
+
+        """
         return self.__class__(position,
                               self.energy,
                               self.line_direction,

nifty/minimization/relaxed_newton.py

@@ -21,6 +21,21 @@ from .line_searching import LineSearchStrongWolfe
 
 
 class RelaxedNewton(QuasiNewtonMinimizer):
+    """ A implementation of the relaxed Newton minimization scheme.
+    The relaxed Newton minimization exploits gradient and curvature information to
+    propose a step. A linesearch optimizes along this direction.
+
+    Parameter
+    ---------
+    line_searcher : LineSearch,
+        An implementation of a line-search algorithm.
+    callback :
+    convergence_tolerance : float,
+        Specifies the
+    convergence_level :
+    iteration_limit :
+
+    """
     def __init__(self, line_searcher=LineSearchStrongWolfe(), callback=None,
                  convergence_tolerance=1E-4, convergence_level=3,
                  iteration_limit=None):